@@ -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
52415254class 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
0 commit comments