Repository navigation
Commit 70ddaa3
Add opt-in recorded outputs and validate output manifests (#356)
* Recorded outputs: the recorder, C ABI group pf_outputs and run_json --outputs
A module can record what it computes on each bar besides its trades:
doubles in named slots per bar, doubles kept once per run, and events with
an optional message, one row per bar the module publishes.
- BacktestEngine gains the recorder (engine.hpp tail block,
engine_report.cpp): declare_outputs, output_run_begin, output_bar,
output_value, output_event, output_constant and the outputs_enabled_
flag for the host, readers for the C side. The host states the shape,
each run's boundary and each row's identity (its open time); a row
restarts at an equal open and a lower one fails the run. State sits
outside both hashed regions; nothing a run computes reads it.
- pineforge.h gains group pf_outputs: nine runtime exports
(strategy_outputs_set_enabled and the readers, the size-prefixed
pf_output_event_v1_t) and three per-module declarations
(strategy_outputs_api_version, strategy_outputs_manifest,
strategy_signal_safety_receipt). PF_ABI_VERSION stays 4; pf_report_t
and every existing symbol are unchanged.
- native_c_api.h lists the six writers as C++-only base-class seams at
zero line shift; check_c_abi_runtime.py counts 73 runtime
implementations and 93 declarations.
- docker/run_json.py --outputs writes the record as the report's
"outputs" block.
- Tests: test_outputs_recorder (hand values, every refusal),
test_outputs_stream_equivalence (stream == batch, the stale carried
callback, negative controls), test_outputs_truncation (a cut batch
records the prefix, negative control), test_outputs_run_reuse,
test_outputs_off_identity (trades, equity and hashes equal with
recording undeclared, off and on), test_outputs_c_api_c99,
scripts/test_run_json_outputs.py and scripts/test_report_outputs_keys.py;
the ci_verify row floors rise by those rows.
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
* docs: recorded outputs (lane SM-E1)
docs/outputs.md describes the record (rows, values, events, run
constants, colours as an encoding), the C++ host API and its row rules,
the C readers, batches and streams, run_json --outputs, and the costs.
ADR-0001 gains the recorder's codegen-ABI row and the C-surface row; the
report-schema, abi-stability and docker pages describe the outputs
block, the new exports and the epoch ruling; the stated PF_API counts
(73 runtime, 93 in pineforge.h, 136 across both headers) follow the tree;
CHANGELOG gains the Unreleased entry.
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
* Recorded outputs: twin pf_output_phase_t to NativeRunPhase; restate counts
check_native_c_api_surface.py requires every C enumeration to be twinned
to its kernel enumeration or ruled C-only: pf_output_phase_t mirrors
NativeRunPhase value for value (src/c_abi.cpp asserts the same), so it
joins pf_native_run_phase_e as a twin. test_ci_verify.py pins the
check_c_abi_runtime.py counts (93 declarations, 73 implementations), and
the two remaining pages that state them follow the tree.
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
* Recorded outputs: the truncation test carries a colour slot beside its run constant
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
* Recorded outputs: run-failure codes for every refusal; review fixes
On the stable run-failure codes (#351):
- strategy_outputs_set_enabled records its refusals through the failure
record, code outputs_rejected (reason not_declared or run_in_progress),
and clears it when it succeeds, so strategy_get_last_error_code reads ""
after a switch that worked.
- The recorder's refusals carry their codes: a broken precondition is
engine_invariant (still a std::logic_error), the event queue or the rows
reaching INT_MAX are pine_runtime_limit (limit output_events or
output_rows; the row cap is new and keeps bar_index an int32_t), a bar
recalculated after a caller cleared its events is outputs_rejected
(reason recalculated_after_clear).
- docker/run_failure_codes.json gains outputs_rejected, the two limits,
strategy_library_incompatible's reasons outputs_api_mismatch and
outputs_manifest_invalid, and the recorder's texts; the registry, the
catalog diff and the code tables of run-failure-codes.md are regenerated.
- run_json: OutputsError is a RunFailure, written as the coded failure
line. --outputs requires the manifest and every reader, checks the
outputs API version, refuses a manifest that is not a JSON object, names
a slot the library does not record or lacks an output an event names,
and copies each event's message when it reads the event.
Tests: test_outputs_recorder checks each refusal's code and the getters,
and a stream ended on a forming bar records confirmed 0;
run_json_codes_test.py and test_report_outputs_keys.py cover the new
refusals; test_run_json_outputs.py asserts the coded lines and that a
colour slot is written as JSON integers. Test comments say what they test
instead of naming internal design records.
Docs: the switch's codes and that a call changing nothing answers 0
(pineforge.h, docs/outputs.md); a message holding a NUL reads to its first
NUL while message_hash64 covers every recorded byte; call output_bar first
in every calculation that writes; the ADR row names OutputEvent and the
readers.
Also restores the endif() of the per-entry-exit fixture block in
tests/CMakeLists.txt, which the rebase onto main left out.
Revises four sentences of the lane SM-E1 docs commit: the ADR row's
first cell (`declare_outputs`, `output_run_begin`, `output_bar`,
`output_value`, `output_event`, `output_constant`, `outputs_enabled_`)
now also names the readers and OutputEvent; docs/outputs.md's "Fails
(throws `std::logic_error`) when" list and its "`open_ms` is below the
last row's" rule now give each refusal's code; report-schema.md's
"`--outputs` on a module that records nothing" line now shows the coded
failure line.
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
* Recorded outputs: a neutral outputs_limit code; the switch keeps the failure record
The recorder is a generic kernel unit, so its two INT_MAX caps no longer
raise pine_runtime_limit. The catalog gains outputs_limit (class
strategy_limit, "A recorded-outputs capacity limit was reached during the
run.") with reason too_many_events or too_many_rows and max; both caps raise
it. pine_runtime_limit is main's entry again (limits map_pairs,
max_bars_back, matrix_elements, udt_objects), so its row of
run-failure-codes.md reads 4 values again. The enum, the registry, the
catalog diff and the page's tables are regenerated. test_outputs_recorder
checks the caps' exception as their sites throw it, as
test_run_failure_codes does for recalc_cap, and that a reason outside the
list reads engine_invariant.
strategy_outputs_set_enabled now follows strategy_set_trace_enabled and the
checked settings setters, which never clear a failure record: a success
leaves the record as it was, and a refusal keeps a failed run's own text
and code, as the C boundary keeps them for any refused call. Tests cover a
success after a refusal, and a success and a refusal after a failed run.
docs/outputs.md and engine.hpp say which exception type each failure throws
(std::runtime_error for the caps and a recalculation after a clear), and
pineforge.h and docs/outputs.md state the switch's record rule. Revised
sentences: docs/outputs.md's "The event queue and the rows reaching
`INT_MAX` are `pine_runtime_limit`", "A recalculation of a bar after a
caller cleared that bar's events is `outputs_rejected`", the
`strategy_outputs_set_enabled(s, on)` row ("0 with no failure left behind")
and the costs line "The event queue holds at most `INT_MAX` events between
clears"; the pine_runtime_limit row of run-failure-codes.md.
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
* test: cover malformed output manifest entries at harness boundary
* fix: validate consumed output manifest values before lookup
* test: bind recorded outputs to typed provenance at the harness boundary
* docs: distinguish planned recorded outputs from the 1.4.0 release
* docs: mark recorded outputs as unreleased for 1.5.0
* docs: clarify unreleased output failure reasons
---------
Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>1 parent 31a40a1 commit 70ddaa3
39 files changed
Lines changed: 5268 additions & 154 deletions
File tree
- docker
- docs
- adr
- design
- pages
- include/pineforge
- scripts
- src
- tests
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
8 | 35 | | |
9 | 36 | | |
10 | 37 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
33 | 33 | | |
34 | 34 | | |
35 | 35 | | |
36 | | - | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
37 | 40 | | |
38 | 41 | | |
39 | 42 | | |
| |||
501 | 504 | | |
502 | 505 | | |
503 | 506 | | |
504 | | - | |
505 | | - | |
506 | | - | |
507 | | - | |
508 | | - | |
| 507 | + | |
| 508 | + | |
| 509 | + | |
| 510 | + | |
| 511 | + | |
| 512 | + | |
| 513 | + | |
509 | 514 | | |
510 | 515 | | |
511 | 516 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
266 | 266 | | |
267 | 267 | | |
268 | 268 | | |
| 269 | + | |
| 270 | + | |
| 271 | + | |
| 272 | + | |
| 273 | + | |
| 274 | + | |
| 275 | + | |
| 276 | + | |
| 277 | + | |
| 278 | + | |
| 279 | + | |
| 280 | + | |
| 281 | + | |
| 282 | + | |
| 283 | + | |
| 284 | + | |
| 285 | + | |
| 286 | + | |
| 287 | + | |
| 288 | + | |
| 289 | + | |
| 290 | + | |
| 291 | + | |
| 292 | + | |
| 293 | + | |
| 294 | + | |
| 295 | + | |
269 | 296 | | |
270 | 297 | | |
271 | 298 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
249 | 249 | | |
250 | 250 | | |
251 | 251 | | |
| 252 | + | |
| 253 | + | |
| 254 | + | |
| 255 | + | |
| 256 | + | |
| 257 | + | |
| 258 | + | |
| 259 | + | |
| 260 | + | |
| 261 | + | |
| 262 | + | |
| 263 | + | |
| 264 | + | |
252 | 265 | | |
253 | 266 | | |
254 | 267 | | |
| |||
453 | 466 | | |
454 | 467 | | |
455 | 468 | | |
| 469 | + | |
| 470 | + | |
| 471 | + | |
| 472 | + | |
| 473 | + | |
| 474 | + | |
| 475 | + | |
| 476 | + | |
| 477 | + | |
| 478 | + | |
| 479 | + | |
| 480 | + | |
| 481 | + | |
| 482 | + | |
| 483 | + | |
| 484 | + | |
| 485 | + | |
| 486 | + | |
| 487 | + | |
| 488 | + | |
| 489 | + | |
| 490 | + | |
| 491 | + | |
| 492 | + | |
| 493 | + | |
| 494 | + | |
| 495 | + | |
| 496 | + | |
| 497 | + | |
| 498 | + | |
| 499 | + | |
| 500 | + | |
| 501 | + | |
| 502 | + | |
| 503 | + | |
| 504 | + | |
| 505 | + | |
| 506 | + | |
| 507 | + | |
| 508 | + | |
| 509 | + | |
| 510 | + | |
| 511 | + | |
| 512 | + | |
| 513 | + | |
456 | 514 | | |
457 | 515 | | |
458 | 516 | | |
| |||
1117 | 1175 | | |
1118 | 1176 | | |
1119 | 1177 | | |
1120 | | - | |
| 1178 | + | |
| 1179 | + | |
| 1180 | + | |
1121 | 1181 | | |
1122 | 1182 | | |
1123 | 1183 | | |
1124 | 1184 | | |
1125 | 1185 | | |
1126 | 1186 | | |
| 1187 | + | |
| 1188 | + | |
| 1189 | + | |
| 1190 | + | |
| 1191 | + | |
| 1192 | + | |
| 1193 | + | |
| 1194 | + | |
| 1195 | + | |
| 1196 | + | |
| 1197 | + | |
1127 | 1198 | | |
1128 | 1199 | | |
1129 | 1200 | | |
| |||
0 commit comments