Skip to content

Commit b01fe68

Browse files
luisleo526claude
andcommitted
cr150 lane proof (squash of the lane branch on the freeze head 2754739)
Lab proof commit, never pushed. Its tree equals the lane head; its single parent is the freeze head 2754739 (core/cr150-p00-contracts: batch A #457 + CANARY-WIRE + SyntaxError fix), as the GitHub squash will write it. CR-150 lane: see the lane REPORT.md for design, tests and wiring. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
1 parent 2754739 commit b01fe68

11 files changed

Lines changed: 595 additions & 96 deletions

‎docker/run_failure_codes.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1170,7 +1170,10 @@
11701170
"magnifier_volume_weighted",
11711171
"bench",
11721172
"ohlcv_bin",
1173-
"verify_bin"
1173+
"verify_bin",
1174+
"report_sink",
1175+
"run_id",
1176+
"spill_dir"
11741177
]
11751178
}
11761179
},

‎docker/run_failure_codes_diff.json‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
"to": {
99
"version": null,
1010
"unreleased": true,
11-
"catalogSha256": "1d74dce76db87e07d9a7edb9683ab53f83410ad7d5b62e1e8960912b7201e162"
11+
"catalogSha256": "d1fb47948619bee0492db323649ee99a4898bf0053bc66be9bf4a59783db3798"
1212
},
1313
"catalogSchema": {
1414
"before": "pineforge-run-failure-catalog/v1",
@@ -180,7 +180,10 @@
180180
"magnifier_volume_weighted",
181181
"bench",
182182
"ohlcv_bin",
183-
"verify_bin"
183+
"verify_bin",
184+
"report_sink",
185+
"run_id",
186+
"spill_dir"
184187
]
185188
}
186189
]

‎docker/run_json.py‎

Lines changed: 94 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -4076,7 +4076,7 @@ def _throughput_block(items_processed, samples_ns, *, bar_magnifier) -> dict:
40764076
"so", "ohlcv", "inputs", "overrides", "input_tf", "script_tf", "bar_magnifier",
40774077
"magnifier_samples", "magnifier_dist", "generated_cpp", "transpiled", "syminfo",
40784078
"trade_start_ms", "chart_tz", "magnifier_volume_weighted", "bench", "warmup",
4079-
"repeats", "symbol_feeds", "ohlcv_bin", "verify_bin",
4079+
"repeats", "symbol_feeds", "ohlcv_bin", "verify_bin", "report_sink", "run_id", "spill_dir",
40804080
})
40814081

40824082

@@ -4885,6 +4885,13 @@ def _main(argv, binary_inputs) -> int:
48854885
help="pf_bar_t/v1 binary chart (or the symbol index chart); alternative to --ohlcv.")
48864886
ap.add_argument("--verify-bin", choices=("full", "sidecar"), default="full",
48874887
help="Binary verification: full checks SHA-256; sidecar checks metadata. Both check order.")
4888+
ap.add_argument("--report-sink", type=Path, default=None, metavar="PATH",
4889+
help="Write the body run's pf-report-sink/v1 file to PATH and emit summary JSON.")
4890+
ap.add_argument("--run-id", default="",
4891+
help="Caller run identifier copied into the report sink header (default empty).")
4892+
ap.add_argument("--spill-dir", type=Path, default=None, metavar="DIR",
4893+
help="Writable directory for engine scratch and unlinked report temporaries; "
4894+
"defaults to the system temporary directory.")
48884895
# Selected-window mode (selected-window/v1; see the section above main). All of these are
48894896
# absent from an ordinary command line, which then behaves exactly as before.
48904897
ap.add_argument("--report-policy", default=None,
@@ -4940,9 +4947,15 @@ def _main(argv, binary_inputs) -> int:
49404947
return _capabilities_main(args)
49414948
if args.ohlcv is not None and args.ohlcv_bin is not None:
49424949
raise _request_invalid("error: --ohlcv and --ohlcv-bin are mutually exclusive", "ohlcv_bin")
4950+
_validate_sink_options(args)
49434951
selected = _selected_requested(args)
49444952
if selected and args.ohlcv_bin is not None:
49454953
raise _request_invalid("error: selected-window mode requires a CSV chart", "ohlcv_bin")
4954+
if selected and (args.report_sink is not None or args.run_id or args.spill_dir is not None):
4955+
# L9S owns selected-window sink assembly. Never accept a named sink
4956+
# request here and silently return the selected array report instead.
4957+
raise _request_invalid(
4958+
"error: selected-window mode does not yet support report sink options", "arguments")
49464959
if (selected or args.report_shape is not None or args.curve_point_budget is not None
49474960
or args.results_digest is not None):
49484961
import selected_window_report
@@ -4996,7 +5009,7 @@ def _main(argv, binary_inputs) -> int:
49965009
# --symbol-feeds).
49975010
symbol_feeds = None
49985011

4999-
def _make_state():
5012+
def _make_state(*, body=False):
50005013
"""Create + fully configure a fresh strategy state — everything EXCEPT the
50015014
timed run_backtest_full call. Mirrors scripts/run_strategy.py's setup so the
50025015
engine behaves identically to the ctypes validation harness. The handle is
@@ -5021,7 +5034,7 @@ def _make_state():
50215034
lib.strategy_set_magnifier_volume_weighted(st, 1)
50225035
if args.outputs:
50235036
enable_outputs(lib, st)
5024-
sink = _new_report_sink(lib, st, args)
5037+
sink = _new_report_sink(lib, st, args, body=body)
50255038
except BaseException:
50265039
try:
50275040
lib.strategy_free(st)
@@ -5078,7 +5091,7 @@ def _run(st, rep):
50785091
# --- Body run: one configured run for trades / metrics / diagnostics. ---
50795092
report = ReportC()
50805093
binding = None
5081-
state, sink = _make_state()
5094+
state, sink = _make_state(body=True)
50825095
try:
50835096
# The last state owns CSV copies. Borrowed binary views stay alive
50845097
# through native cleanup and the outer input stack's cleanup.
@@ -5134,7 +5147,7 @@ def _run(st, rep):
51345147
outputs_block = None
51355148
if args.outputs:
51365149
outputs_block = (
5137-
_sink_outputs_block(lib, state, sink, output_files)
5150+
_sink_outputs_block(lib, state, sink, output_files, summary_only=sink.named)
51385151
if sink is not None else build_outputs_block(make_outputs_reader(lib, state)))
51395152
applied_runtime["outputs"] = True
51405153
incarnation_accessor = getattr(
@@ -5236,7 +5249,7 @@ def _run(st, rep):
52365249
return 0
52375250

52385251

5239-
# --- CR-150 L9A: full JSON from the fixed v1 report sink -----------------------
5252+
# --- CR-150 L9A/L9B: full and summary JSON from the fixed v1 report sink -------
52405253

52415254
class ReportSinkC(ctypes.Structure):
52425255
"""Exact pf_report_sink_v1; the setter copies all three strings."""
@@ -5267,50 +5280,77 @@ def _bind_report_sink(lib) -> None:
52675280
function.restype, function.argtypes = restype, argtypes
52685281

52695282

5270-
def _new_report_sink(lib, state, args):
5283+
def _validate_sink_options(args):
5284+
# A refused value keeps the generic "arguments" option; an argparse refusal names the flag.
5285+
# Reject C-string truncation and non-UTF-8 argv before loading a library.
5286+
for name in ("report_sink", "run_id", "spill_dir"):
5287+
value = getattr(args, name)
5288+
if value is None:
5289+
continue
5290+
text = os.fspath(value)
5291+
label = "--" + name.replace("_", "-")
5292+
try:
5293+
text.encode("utf-8")
5294+
except UnicodeEncodeError:
5295+
raise _request_invalid(f"error: {label} must hold UTF-8 text", "arguments") from None
5296+
if "\0" in text:
5297+
raise _request_invalid(f"error: {label} must not contain NUL", "arguments")
5298+
5299+
5300+
def _new_report_sink(lib, state, args, *, body=True):
52715301
names = ("pf_report_sink_version", "strategy_set_report_sink_v1",
52725302
"strategy_report_sink_receipt_v1")
52735303
present = [hasattr(lib, name) for name in names]
52745304
if not any(present):
5305+
if getattr(args, "report_sink", None) is not None:
5306+
raise StrategyLibraryError("the strategy library has no report sink API",
5307+
{"reason": "symbol_missing"})
52755308
return None # old modules keep their existing report ABI
52765309
if not all(present) or int(lib.pf_report_sink_version()) != 1:
52775310
raise _engine_invariant("the strategy library has an incompatible report sink ABI")
5278-
# The named-sink CLI is L9B. These attributes also give L9B/L9S one
5279-
# directory for the engine's scratch and every Python temporary.
5280-
return _TemporaryReportSink(lib, state, directory=getattr(args, "spill_dir", None),
5281-
run_id=getattr(args, "run_id", ""))
5311+
# Only the body run may create/truncate the caller's sink. Bench states
5312+
# retain the existing unlinked-file lifetime.
5313+
return _ReportSink(lib, state, directory=getattr(args, "spill_dir", None),
5314+
run_id=getattr(args, "run_id", ""),
5315+
path=getattr(args, "report_sink", None) if body else None)
52825316

52835317

5284-
class _TemporaryReportSink:
5285-
"""A named, owner-only (0600) temporary file, addressed by its real path.
5318+
class _ReportSink:
5319+
"""A caller-owned named path, or a named owner-only (0600) temporary file,
5320+
addressed by its real path.
52865321
52875322
The engine opens the path itself with its existing path-only API
52885323
(O_WRONLY | O_CREAT | O_TRUNC, no O_EXCL: src/report_sink_writer.cpp), so
5289-
the empty file created here is accepted and truncated by it. Every reader
5290-
opens the same path again and so owns its offset. No descriptor path
5291-
(/proc/self/fd, /dev/fd) is used: Darwin's /dev/fd/N is a dup that shares
5292-
the file offset. No named sink, new wire format or public fd API is
5293-
introduced. close() unlinks the file and may be called again, unless
5294-
``keep`` is set (the harness's test-only artifact switch). Keep the owner
5295-
open until both report_free and strategy_free have returned.
5324+
the empty temporary file created here is accepted and truncated by it, and a
5325+
caller's --report-sink is created or truncated by the engine and persists
5326+
for its caller. Every reader opens the same path again and so owns its
5327+
offset. No descriptor path (/proc/self/fd, /dev/fd) is used: Darwin's
5328+
/dev/fd/N is a dup that shares the file offset. close() unlinks a temporary
5329+
file and may be called again, unless ``keep`` is set (the harness's
5330+
test-only artifact switch); it never unlinks a caller's named sink. Keep
5331+
the owner open until both report_free and strategy_free have returned.
52965332
"""
52975333

5298-
def __init__(self, lib, state, *, directory=None, run_id=""):
5334+
def __init__(self, lib, state, *, directory=None, run_id="", path=None):
52995335
self.directory = os.fspath(directory) if directory is not None else tempfile.gettempdir()
53005336
self.header, self.counts, self.sha256 = {}, {}, ""
5337+
self.named, self.run_id = path is not None, run_id
53015338
self.keep, self.closed = False, False
5302-
try:
5303-
handle, path = tempfile.mkstemp(prefix="pineforge-report-sink-", suffix=".sink",
5304-
dir=self.directory)
5305-
except OSError as error:
5306-
raise RunFailure("report sink open failed", "report_sink_failed") from error
5307-
self.path = os.path.abspath(path)
5308-
try:
5339+
if self.named:
5340+
self.path = os.fspath(path)
5341+
else:
5342+
try:
5343+
handle, temporary = tempfile.mkstemp(prefix="pineforge-report-sink-",
5344+
suffix=".sink", dir=self.directory)
5345+
except OSError as error:
5346+
raise RunFailure("report sink open failed", "report_sink_failed") from error
5347+
self.path = os.path.abspath(temporary)
53095348
os.close(handle) # the engine and every reader open the path themselves
5349+
try:
53105350
descriptor = ReportSinkC(ctypes.sizeof(ReportSinkC), 1, os.fsencode(self.path),
53115351
run_id.encode("utf-8"), os.fsencode(self.directory))
53125352
if lib.strategy_set_report_sink_v1(state, ctypes.byref(descriptor)) != 0:
5313-
raise _engine_invariant("the fresh strategy refused its temporary report sink")
5353+
raise _engine_invariant("the fresh strategy refused its report sink")
53145354
except BaseException:
53155355
self.close()
53165356
raise
@@ -5324,6 +5364,8 @@ def verify(self, lib, state, report):
53245364
self.header, self.counts, self.sha256 = reader.header, reader.counts, reader.sha256
53255365
except SinkFormatError as error:
53265366
raise _engine_invariant(f"the engine's report sink is invalid: {error}") from error
5367+
if self.header["run_id"] != self.run_id:
5368+
raise _engine_invariant("the report sink run id differs from the request")
53275369
receipt = ReportSinkReceiptC()
53285370
receipt.struct_size, receipt.version = ctypes.sizeof(receipt), 1
53295371
if lib.strategy_report_sink_receipt_v1(state, ctypes.byref(receipt)) != 0 or receipt.complete != 1:
@@ -5348,7 +5390,7 @@ def records(self, tag=None):
53485390

53495391
def close(self):
53505392
if not self.closed:
5351-
if not self.keep:
5393+
if not self.keep and not self.named:
53525394
try:
53535395
os.unlink(self.path)
53545396
except FileNotFoundError:
@@ -5517,6 +5559,22 @@ def _build_sink_report(report, ohlcv_path, n_bars, first_ts, last_ts, elapsed,
55175559
applied_inputs, applied_overrides, applied_runtime)
55185560
out["summary"] = _sink_summary(report, sink)
55195561
_validate_report_result(out) # trades are still []; the pre-pass checked every T
5562+
if sink.named:
5563+
reference = {
5564+
"path": sink.path,
5565+
"schema": sink.header["schema"],
5566+
"version": sink.header["version"],
5567+
"run_id": sink.header["run_id"],
5568+
"counts": sink.counts,
5569+
"sha256": sink.sha256,
5570+
}
5571+
# Insert the reference at the old trades position; all other small
5572+
# keys retain the frozen producer's order and values.
5573+
return {
5574+
("report_sink" if key == "trades" else key):
5575+
(reference if key == "trades" else value)
5576+
for key, value in out.items() if key != "equity_curve"
5577+
}
55205578
out["trades"] = _JSONRecordArray(lambda: (_sink_trade(row) for row in sink.records("T")))
55215579
out["equity_curve"] = _JSONRecordArray(lambda: (row.as_dict() for row in sink.records("E")))
55225580
return out
@@ -5602,11 +5660,13 @@ def series(slot, encoding):
56025660
return block
56035661

56045662

5605-
def _sink_outputs_block(lib, state, sink, resources):
5663+
def _sink_outputs_block(lib, state, sink, resources, *, summary_only=False):
56065664
# L6b-1 declares O/V/K but L6b-3 writes them. Until that dependency lands,
56075665
# its existing output readers are authoritative. Once K is emitted even
56085666
# an empty output run takes the streamed path below.
56095667
if not any(sink.counts.get(tag, 0) for tag in "OVK"):
5668+
if summary_only:
5669+
raise _engine_invariant("the report sink is missing its output records")
56105670
return _legacy_streamed_outputs_block(lib, state)
56115671
if sink.counts.get("K") != 1:
56125672
raise _engine_invariant("the report sink must contain one output constants record")
@@ -5616,6 +5676,9 @@ def _sink_outputs_block(lib, state, sink, resources):
56165676
constants = tuple(float("nan") if value is None else value for value in record.values)
56175677
raw_manifest = _outputs_manifest(lib, state)
56185678
block = _outputs_metadata(raw_manifest, slots, constants)
5679+
if summary_only:
5680+
return {key: block[key] for key in (
5681+
"schema_version", "message_format", "manifest_sha256", "manifest", "constants", "hlines")}
56195682
entries = sorted(_manifest_entries(block["manifest"], "series", ("slot", "output")),
56205683
key=lambda entry: entry["slot"])
56215684
outputs = {entry["index"]: entry for entry in
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
"""CR-150 L9B preflight discovery for the named-sink summary contract tests."""
2+
from pathlib import Path
3+
import sys
4+
5+
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "tests"))
6+
7+
from test_run_json_sink_summary import * # noqa: F401,F403,E402

‎docs/pages/run-failure-codes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,7 @@ The `outputs_limit` and `outputs_rejected` rows below are released in 1.5.0, and
151151
| `run_aborted` | `engine_fault` | yes | none | The run was aborted on request. |
152152
| `run_mode_unsupported` | `unsupported` | no | `feature` (vocab, 11 values) | A feature the requested run mode does not support. |
153153
| `run_options_rejected` | `input` | no | `input_tf` (timeframe, optional), `option` (vocab, 11 values), `script_tf` (timeframe, optional) | The run's own options (timeframes, intrabar path, magnifier, path order) were refused. |
154-
| `run_request_invalid` | `input` | no | `option` (vocab, 22 values) | The harness command line or one of its JSON options is invalid. |
154+
| `run_request_invalid` | `input` | no | `option` (vocab, 25 values) | The harness command line or one of its JSON options is invalid. |
155155
| `security_feed_refused` | `input` | no | `reason` (vocab, 11 values) | An auxiliary or native request.security feed was refused. |
156156
| `setting_rejected` | `input` | no | `entrypoint` (vocab, 4 values, optional), `input` (pine_source, optional), `reason` (vocab, 21 values, optional) | A run setting (an input or a strategy() override) was refused. |
157157
| `setting_unsupported` | `unsupported` | no | none | A setting this compiled strategy cannot honour. |

‎scripts/run_strategy.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2004,7 +2004,7 @@ def _new_harness_report_sink(lib, state):
20042004
run_json._bind_report_sink(lib)
20052005
if int(lib.pf_report_sink_version()) != 1:
20062006
raise RuntimeError("strategy library has an incompatible report sink ABI")
2007-
return run_json._TemporaryReportSink(lib, state)
2007+
return run_json._ReportSink(lib, state)
20082008

20092009

20102010
def _harness_sink_equity_count(lib, state) -> int:

0 commit comments

Comments
 (0)