You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit efb8c7e
Browse filesBrowse the repository at this point in the historyBrowse files
o1w-contract round 2: the one O(1) report contract — modes, pages, envelope (supervisor commit)
Executor result of lane core-cr150-o1w-contract (Codex gpt-6.1-sol), committed by the supervisor.
Round 2 rewrites the round-1 draft onto the final names: include/pineforge/report_mode.h
(ReportMode FULL/SUMMARY_ONLY/STREAMED, ReportEnvelopeV1, fill_report_envelope_v1,
set_report_mode_v1) and include/pineforge/report_pages.hpp (TradeSourceV1, EquityPointSourceV1,
detached row/point visitors, HeldEquityPointV1), with engine.hpp reader acquisition,
metrics_stream.hpp point-provider overloads, the contract document docs/design/o1-report-contract.md,
report-schema.md, a C++ contract test, a Python unsupported-mode test and four-row/four-point
fixtures. The a1ctr draft's report_output.hpp is folded in by renaming (appendix in the contract
document records every old->new name and every omitted draft-only option). ABI counts unchanged
(104 public declarations / 84 implementations; native-C 43/43).
NOT VERIFIED: no compile, no test, no corpus ran on this tree. Lab rows owed: test_o1_report_contract,
test_o1_report_mode_unsupported (fail-before on the unchanged tree, green after), doc-anchors
re-pin, then the full proof.
Co-Authored-By: Claude Code <[email protected]>
`<pineforge/report_pages.hpp>` declares the single C++ reader family in
200
+
`pineforge::report`; it uses the modes/envelope above. `TradeSourceV1::at`
201
+
returns an exact `TradeRowV1` value. `read_page` copies into caller-owned
202
+
bounded buffers; `visit` walks a logical range forward and `visit_backward`
203
+
walks the same range newest logical row first, including tied/nonmonotonic
204
+
exit times. `TradeTextV1` selects IDs/comments for byte-exact bounded reads.
205
+
`EquityPointSourceV1` provides value/index/page/ordered-forward point reads.
206
+
Callbacks receive detached values; no API returns a reference or pointer into
207
+
a resident page that may be retired. Invalid ranges/buffers and backing
208
+
failures fail explicitly.
209
+
210
+
Native engine accessors return caller-owned reader adapters by value:
211
+
`completed_trade_source_v1()` covers semantic completed history in every
212
+
mode, excluding the range-end suffix; `report_trade_source_v1()` covers the
213
+
whole captured final report; `report_equity_source_v1()` covers captured
214
+
final presented points, including a selected anchor. Report readers require
215
+
validated completion. SUMMARY_ONLY rejects the two omitted report sources
216
+
explicitly rather than returning fictitious empty readers.
217
+
218
+
`held_report_equity_point_v1()` returns one final `HeldEquityPointV1` by value
219
+
in every mode. `present=false` means zero logical points; otherwise `index`
220
+
is the last logical index and `value` is the exact final presented point.
221
+
This held value does not change SUMMARY_ONLY's `captured=0` or NULL/0 curve.
222
+
During execution the metrics owner holds the editable tail and pre-tail
223
+
fold snapshot until presentation finalizes it; summary/replay passes use
224
+
the same point visitor without creating a private curve tape.
225
+
226
+
The [reader contract and old-draft name mapping](../design/o1-report-contract.md)
227
+
define lifetimes, half-open ranges, backward traversal, cancellation and
228
+
errors. Reader declarations do not establish runtime support and add no
229
+
C export, mode or envelope-version change.
230
+
87
231
## Trade fields
88
232
89
233
| Field | Type | Meaning |
90
234
| --- | --- | --- |
91
-
|`total_trades`|`int`|Closed-trade count. Always equal to `trades_len`. |
92
-
|`trades`|`pf_trade_t*`|Heap array, ordered by exit time ascending. |
93
-
|`trades_len`|`int`|Length of `trades`. |
235
+
|`total_trades`|`int`|Logical closed-trade total, including range-end rows. Equals `trades_len` only on the owning-array route; remains T when SUMMARY_ONLY, STREAMED or a legacy sink returns no resident rows. |
236
+
|`trades`|`pf_trade_t*`|Owning array in report order: script-driven closed rows, then report-only range-end rows. NULL in SUMMARY_ONLY/STREAMED. |
237
+
|`trades_len`|`int`|Resident array length, independent of the logical total. |
94
238
|`net_profit`|`double`| Sum of all closed-trade PnL in account currency. |
95
239
96
240
### pf_trade_t
@@ -188,6 +332,10 @@ Populated only when:
188
332
1. The source script contains `// @pf-trace name=expr` pragmas, **and**
189
333
2. #strategy_set_trace_enabled was called with `1` before the run.
190
334
335
+
In the explicit envelope, FULL returns the resident records, SUMMARY_ONLY
336
+
omits them, and STREAMED publishes them externally. The trace/name logical
337
+
counts and capture flags remain explicit in metadata.
338
+
191
339
| Field | Meaning |
192
340
| --- | --- |
193
341
|`trace[i].timestamp`| Bar timestamp (Unix ms). |
@@ -201,9 +349,11 @@ buffer, no formatting.
201
349
202
350
## Metrics (ABI v2)
203
351
204
-
`pf_report_t::metrics` is a `pf_metrics_t` — four embedded blocks
205
-
computed at report time. The complete per-metric reference (definitions,
206
-
units, NaN rules, validation status) lives on @ref metrics.
352
+
`pf_report_t::metrics` is a `pf_metrics_t` — four embedded blocks.
353
+
Legacy reports compute them at report time; SUMMARY_ONLY returns the frozen,
354
+
validated metrics without a resident curve or trade array. All 768 bytes,
355
+
including the equity-derived ratios, must match FULL. The complete per-metric
356
+
reference (definitions, units, NaN rules, validation status) lives on @ref metrics.
0 commit comments