Skip to content

Commit 0501468

Browse files
luisleo526claude
andcommitted
docs: task-13 fix round 1 — v4 report mirrors (schema, Rust), probe-suppress/range-end independence, trail_price fill-path citation, return conventions, unreleased entry
Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01PXmkFdpbvYDBUY3txrJ2MR
1 parent 46b2ced commit 0501468

6 files changed

Lines changed: 48 additions & 26 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -230,11 +230,11 @@ TradingView ties some day-boundary logic (intraday order caps, session rollovers
230230
| `pf_version_get` / `pf_version_string` / `pf_abi_version` | Runtime version, version string, struct-layout version (`PF_ABI_VERSION == 4`) |
231231
| `strategy_request_abort` / `strategy_last_run_status` | Cooperative abort of a run in progress; `0`=completed, `1`=aborted |
232232
| `strategy_set_realtime_tail` | Live-runtime surface (ABI v4): the array's last bar is a still-forming tail — `barstate.islast=false`, `last_bar_index`/`last_bar_time` frozen at the horizon bar, no range-end row |
233-
| `strategy_set_probe_suppress_tail_logic` | ABI v4: the last bar runs only the broker's pre-`on_bar` steps (pending-order settlement, intraday-cap/loss checks) and returns — no `on_bar`, no range-end/margin-call/bracket-reissue processing |
233+
| `strategy_set_probe_suppress_tail_logic` | ABI v4: the last bar runs only the broker's pre-`on_bar` steps (pending-order settlement, intraday-cap/loss checks) and returns — no `on_bar`, no margin-call / POOC second pass / bracket-reissue processing (the range-end row is `strategy_set_realtime_tail`'s to skip; the flags are independent) |
234234
| `strategy_set_path_order` / `strategy_last_bar_dual_entry_path` | ABI v4: force the intrabar O→H/L→C leg order (`AUTO`/`HIGH_FIRST`/`LOW_FIRST`) for path-dependent fill probing; read which side won a same-bar dual-entry-stop arbitration |
235235
| `strategy_set_broker_state_hash_recording` / `strategy_broker_state_hash` | ABI v4: toggle a 64-bit broker-state hash appended per script bar to `pf_report_t::broker_state_hash`; read the final state's hash |
236236
| `strategy_pending_orders_len` / `strategy_pending_order_get` / `strategy_pending_order_layout` | ABI v4: the resting pending-order book after the most recent run — count, a POD snapshot per order (`pf_pending_order_v1_t`), and the snapshot's self-describing field layout |
237-
| `strategy_pending_order_fill_qty` / `_level_resolved` / `_effective_levels` / `strategy_trail_best_price` | ABI v4: engine-computed values for a resting order — the quantity it would fill at a given price, whether its relative offsets resolve yet, its resolved stop/limit/trail-activation levels, and the live position's trail extreme |
237+
| `strategy_pending_order_fill_qty` / `_level_resolved` / `_effective_levels` / `strategy_trail_best_price` | ABI v4: engine-computed values for a resting order — the quantity it would open if filled at a given price, whether its relative offsets resolve yet, its resolved stop/limit/trail-activation levels, and the live position's trail extreme |
238238
| `strategy_position_avg_price` / `strategy_position_cycle_seq` / `strategy_position_size` | ABI v4: the live position's volume-weighted average entry price, its cycle id, and its script-facing signed size |
239239
| `strategy_closed_trade_entry_id` / `_exit_id` / `_exit_comment` / `_close_cause` | ABI v4: per-closed-trade id/comment strings and a `close_cause` enum (`SCRIPT`/`BRACKET`/`MARGIN_CALL`/`INTRADAY_LOSS_CAP`/`INTRADAY_FILL_CAP`/`RANGE_END`), indexed like `strategy_closed_trade_entry_incarnation` |
240240
| `strategy_current_equity` / `strategy_script_bars_processed` | ABI v4: `initial_capital + netprofit` (not Pine's `strategy.equity`, which also adds open profit); total script bars dispatched by the most recent run |
@@ -273,7 +273,7 @@ Documentation: [C ABI reference](https://cdocs.pineforge.dev) · [Getting starte
273273

274274
## Releases
275275

276-
- **v0.14.0** (2026-09-08) — ABI v4 live surface for `pineforge-live`: 24 new default-off exports (cooperative abort, realtime tail, probe-suppress tail logic, forced path order, a per-bar broker-state hash, the pending-order book as a generated POD mirror, closed-trade id/comment/close-cause, position and equity accessors). No flag changes a historical run: `scripts/live_flags_off_identity.py` (312 corpus probes, 0 differ vs the pre-v4 branch point), `scripts/live_flags_lane.py` (312 probes, 0 positives, 130 open-at-end trades subtracted), and `scripts/bar_identity_lane.py` (row 1: 222,295 bars compared, 2 explained open divergences, 0 else) all pass. 56 symbols.
276+
- **Unreleased** (branch `live/abi-v4`) — ABI v4 live surface for `pineforge-live`: 24 new default-off exports (cooperative abort, realtime tail, probe-suppress tail logic, forced path order, a per-bar broker-state hash, the pending-order book as a generated POD mirror, closed-trade id/comment/close-cause, position and equity accessors). No flag changes a historical run: `scripts/live_flags_off_identity.py` (312 corpus probes, 0 differ vs the pre-v4 branch point), `scripts/live_flags_lane.py` (312 probes, 0 positives, 130 open-at-end trades subtracted), and `scripts/bar_identity_lane.py` (row 1: 222,295 bars compared, 2 explained open divergences, 0 else) all pass. 56 symbols.
277277
- **v0.13.0** (2026-09-05) — the parity campaign, rounds 1–11: TradingView's broker rules pinned with sensor exports and landed with replay tests — ten-significant-digit money, trailing-stop restarts, zero-offset trails, declined-reversal bracket legs, the surviving `strategy.close`, sparse `ta.atr`/`ta.tr`, pivot tick snap, same-bar entry/close transactions, early-close higher-timeframe buckets, 64-bit epoch arrays. Closed test 3,880/3,881; corpus 309/309. ABI v3, 32 symbols, 198 tests.
278278
- **v0.7 – v0.12** (June–August 2026) — native and auxiliary `request.security()` feeds, ABI v2 metrics + equity curve, streaming mode, range-end accounting. See [GitHub releases](https://github.com/pineforge-4pass/pineforge-engine/releases).
279279
- **v0.6.0** — performance sprint: cached static inputs, thread-local timestamp caching, lazy timezone caching; up to 6.7M bars/s.

‎docs/cheatsheet-runtime-and-execution.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -345,13 +345,15 @@ Audited gaps a forward/real-time executor must know (beyond per-order fills).
345345
for NaN-qty siblings.
346346
- **Trail caveats:** `trail_price` **is read by the fill path**, not ignored:
347347
when `trail_points` is unset it is used verbatim as the trail-activation
348-
level (`resolve_exit_path_fill` and the dormant-bracket trail check,
349-
`engine_fills.cpp:4916-4926,8006-8019` — `has_trail` tests
350-
`!std::isnan(o.trail_price)` alongside `trail_points`, and
351-
`*trail_activation`/`activation` default to `o.trail_price` before
352-
`trail_points`, when set, overrides it); `trail_points` wins over
353-
`trail_price` when both are set. `trail_points`/`trail_offset` are
354-
`ceil`-ed to whole ticks before computing the activation level;
348+
level (`compute_exit_trail_state`, `engine_path_resolve.cpp:683-707`,
349+
called by `resolve_exit_path_fill` from the exit fill path
350+
`engine_fills.cpp:8628-8635`; and the dormant-bracket trail check
351+
`engine_fills.cpp:8006-8019` — `has_trail` tests
352+
`!std::isnan(o.trail_price)` alongside `trail_points`, and the activation
353+
defaults to `trail_price` before `trail_points`, when set, overrides it);
354+
`trail_points` wins over `trail_price` when both are set.
355+
`trail_points`/`trail_offset` are `ceil`-ed to whole ticks before
356+
computing the activation level;
355357
**no-offset trail** (`exits_at_activation`) fires at the activation level
356358
itself; `trail_best_price_` resets to `close` on the first `strategy.exit`
357359
for an id (preserved on re-issue).
@@ -459,8 +461,8 @@ then `execute_partial_exit_qty` (`engine_orders.cpp:154-155`) applies it
459461
**again** → the bracket close-then-enter exit may be **double-slipped**. The
460462
public corpus is **not** uniformly `slippage=0`: 252/312 probes declare no
461463
slippage (where double-rounding zero is idempotent and this path is
462-
effectively masked), but 60/312 declare a non-zero `slippage` (`slippage=1|2`;
463-
62/312 also declare a non-zero `commission_value`) — for those 60 the
464+
effectively masked), but 60/312 declare a non-zero `slippage` (`slippage=1|2`; and,
465+
independently, 62/312 declare a non-zero `commission_value`) — for those 60 the
464466
idempotent-zero argument does not apply, and whether any of them actually
465467
exercises `close_opposite_then_enter` is unverified. Worth a targeted test
466468
before trusting slippage on that path.

‎docs/pages/examples-rust.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -163,12 +163,16 @@ struct PfReport {
163163
metrics: PfMetrics,
164164
equity_curve: *mut PfEquityPoint,
165165
equity_curve_len: i64,
166+
167+
// ABI v4: per-script-bar broker-state hash (NULL / 0-length unless recording is on)
168+
broker_state_hash: *mut u64,
169+
broker_state_hash_len: i64,
166170
}
167171

168172
const PF_MAGNIFIER_ENDPOINTS: c_int = 3;
169173

170174
// PfReport is CALLER-allocated: before any run, resolve `pf_abi_version`
171-
// via libloading and assert it returns 3 (PF_ABI_VERSION) — an old .so
175+
// via libloading and assert it returns 4 (PF_ABI_VERSION) — an old .so
172176
// writing into this larger struct (or vice versa) corrupts memory silently.
173177

174178
// ── Safe wrapper ──────────────────────────────────────────────────────

‎docs/pages/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ End-to-end, runnable examples that go beyond the MACD tutorial:
8383

8484
## API at a glance
8585

86-
The entire public surface fits in **one header** and **28 functions**:
86+
The entire public surface fits in **one header** and **56 functions**:
8787

8888
| Group | Symbols | Reference |
8989
| --- | --- | --- |
@@ -94,7 +94,7 @@ The entire public surface fits in **one header** and **28 functions**:
9494
| Version | `pf_version_get`, `pf_abi_version`, `pf_version_string` | @ref pf_version |
9595
| Types | `pf_bar_t`, `pf_trade_tick_t`, `pf_trade_t`, `pf_report_t`, metrics, diagnostics, trace, equity, version, and `pf_magnifier_distribution_t` | @ref pf_types |
9696

97-
Every PineForge-generated strategy `.so` exports exactly these 28 symbols
97+
Every PineForge-generated strategy `.so` exports exactly these 56 symbols
9898
and zero internal C++ symbols — see
9999
**[ABI stability](@ref abi_stability)** for the full guarantee.
100100

‎docs/pages/live-surface.md‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
**ABI v4** (`PF_ABI_VERSION == 4`) appends 24 exports and two `pf_report_t`
66
fields for `pineforge-live`, the recompute-based live runtime built on top
7-
of this engine (see [pineforge-live design spec §3](https://github.com/pineforge-4pass/pineforge-workflow-live)
7+
of this engine (see [`pineforge-workflow-live/docs/superpowers/specs/2026-09-07-pineforge-live-design.md` §3](https://github.com/pineforge-4pass/pineforge-workflow-live)
88
for the full contract this surface serves). Every one of the 24 symbols is
99
**default off / read-only** and **never changes a historical run**: the
1010
four configuration setters below default to the pre-v4 behavior, and every
@@ -21,7 +21,7 @@ runtime works by *recomputing* it (see @ref streaming for why the
2121

2222
| Symbol | Purpose | Default | Changes history when off? |
2323
| --- | --- | --- | --- |
24-
| `strategy_request_abort` | Set a cooperative abort flag, consumed by the run in progress, checked at the top of both bar loops. | N/A — an action, not configuration; cleared at `run()` entry. | No |
24+
| `strategy_request_abort` | Set a cooperative abort flag, consumed by the run in progress, checked at the top of every bar loop (the single-timeframe `run()` loop, `run_simple_bar_loop`, `run_aggregation_bar_loop`). | N/A — an action, not configuration; cleared at `run()` entry. | No |
2525
| `strategy_last_run_status` | `0` completed, `1` `NOT_COMPLETED` (aborted), `-1` if `s` is `NULL`. | N/A — read-only. | No |
2626
| `strategy_set_realtime_tail` | Mark the array's last bar as a still-forming tail (§3.1 semantics below). | Off (`on == 0`). | No |
2727
| `strategy_set_probe_suppress_tail_logic` | Run only the broker's pre-`on_bar` steps on the last bar and stop (§3.2 below). | Off (`on == 0`). | No |
@@ -32,9 +32,9 @@ runtime works by *recomputing* it (see @ref streaming for why the
3232
| `strategy_pending_orders_len` | Count of orders resting in the pending-order book after the most recent `run()` — the book in force for the next bar. `0` if `s` is `NULL`. | N/A — read-only. | No |
3333
| `strategy_pending_order_get` | Copy the *i*-th resting order into a `pf_pending_order_v1_t` snapshot (see [The pending-order mirror](#live_surface_pending_mirror)). | N/A — read-only. | No |
3434
| `strategy_pending_order_layout` | The field table (`pf_field_desc_t[]`: name, type, offset, size) of `pf_pending_order_v1_t` as this runtime compiled it. Static storage, no handle needed. | N/A — static. | No |
35-
| `strategy_pending_order_fill_qty` | The contracts the *i*-th resting order would open if filled at a given price, and which of 4 sizing rules (`EXPLICIT`/`FROZEN_PLACEMENT`/`DEFAULT_STOP_PLACEMENT`/`AT_FILL`) produced it, plus a `close_only` flag. | N/A — read-only. | No |
35+
| `strategy_pending_order_fill_qty` | The contracts the *i*-th resting order would open if filled at a given price, and which of 4 sizing rules (`EXPLICIT`/`FROZEN_PLACEMENT`/`DEFAULT_STOP_PLACEMENT`/`AT_FILL`) produced it, plus a `close_only` flag. Returns `0` on success; `1` — with `qty` NaN, `close_only` 0, `partition` -1 — when the order is an EXIT (its fill qty is decided against the live position at the fill); `-1` with nothing written when `s` is `NULL`, `index` is out of range, or any out-pointer is `NULL`. | N/A — read-only. | No |
3636
| `strategy_pending_order_level_resolved` | `1` when the *i*-th order's `from_entry`-relative offsets resolve now (entries/plain orders/empty-`from_entry` exits: always; a bound exit: only once that entry has filled in the current cycle). `-1` if `s` is `NULL` or `index` is out of range. | N/A — read-only. | No |
37-
| `strategy_pending_order_effective_levels` | The *i*-th order's resolved `stop`/`limit`/`trail_activation` price levels, as the fill path resolves them. `NaN` for an unset/unresolvable leg. | N/A — read-only. | No |
37+
| `strategy_pending_order_effective_levels` | The *i*-th order's resolved `stop`/`limit`/`trail_activation` price levels, as the fill path resolves them. `NaN` for an unset/unresolvable leg. Returns `0`; `-1` with nothing written under the same three conditions as `strategy_pending_order_fill_qty` (`s` `NULL`, `index` out of range, or any out-pointer `NULL`). | N/A — read-only. | No |
3838
| `strategy_trail_best_price` | The running trail extreme (`trail_best_price_`) the exit trail legs ride: high-since-fill for a long, low-since-fill for a short. `NaN` if `s` is `NULL` or no position has filled. | N/A — read-only. | No |
3939
| `strategy_position_avg_price` | The live position's volume-weighted average entry price. `NaN` if `s` is `NULL` or the position is flat. | N/A — read-only. | No |
4040
| `strategy_position_cycle_seq` | The live position's cycle id: `0` when flat, a fresh nonzero id per open/reversal, unchanged across same-direction adds. `-1` if `s` is `NULL`. | N/A — read-only. | No |
@@ -70,7 +70,8 @@ configuration**, not one-shot: it stays in effect until a caller passes
7070
3. `bar_index` stays put; `last_bar_index` (and `last_bar_time`) are frozen
7171
at the horizon bar (`horizon_bars - 1`), when `horizon_bars > 0`.
7272
4. The range-end synthetic close row/trade is skipped (no `open_at_end`
73-
row); the final equity point keeps `open_profit`.
73+
row); the final equity point keeps `open_profit`, and the drawdown/runup
74+
scalars are folded without the range-end row.
7475
5. Interior bars (every bar before the last) are unaffected.
7576

7677
Default off (`on == 0`): every historical run stays byte-identical to
@@ -102,8 +103,14 @@ not coupled; set each explicitly.
102103
Dispatch-path scope: honoured only on the standard `dispatch_bar` path (the
103104
single-timeframe run loop and the `input_tf == script_tf` simple bar loop).
104105
Silent no-op under `calc_on_order_fills` and under the bar magnifier —
105-
both are gated features in v1 and a probe must not enable them. Clear this
106-
flag before `strategy_stream_begin`; the warmup replay is a `run()`.
106+
both are gated features in v1 and a probe must not enable them. On the
107+
non-magnifier aggregation path (`input_tf < script_tf`) the semantics are
108+
UNDEFINED until the partial-bucket forming-bar flag lands: callers must
109+
feed an `input_tf == script_tf` array until that flag exists. Under
110+
`process_orders_on_close`, the pre-script carried-position margin helpers
111+
that `process_margin_call` would otherwise run are also skipped on the
112+
suppressed last bar. Clear this flag before `strategy_stream_begin`; the
113+
warmup replay is a `run()`.
107114

108115
Default off (`on == 0`): every historical run stays byte-identical to
109116
before this flag existed.
@@ -154,8 +161,10 @@ existed.
154161

155162
`strategy_request_abort(s)` sets an atomic flag from any thread, consumed
156163
by the run in progress and cleared at `run()` entry (a no-op when idle),
157-
checked at the top of both bar loops. `strategy_last_run_status(s)` (an
158-
append-only status accessor) reports whether the most recent run completed
164+
checked at the top of every bar loop (the single-timeframe `run()` loop,
165+
`run_simple_bar_loop`, `run_aggregation_bar_loop`).
166+
`strategy_last_run_status(s)` (an append-only status accessor) reports
167+
whether the most recent run completed
159168
(`0`) or was aborted (`1`, `NOT_COMPLETED`); `-1` if `s` is `NULL`. L0 pins
160169
**"abort before run → run completes"**: requesting an abort before a run
161170
starts must not prevent that run from completing, since the flag is

‎docs/pages/report-schema.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,15 +53,22 @@ typedef struct pf_report_s {
5353
/* Per-script-bar equity curve (ABI v2) */
5454
pf_equity_point_t* equity_curve;
5555
int64_t equity_curve_len; /* NOTE: int64, not int */
56+
57+
/* Per-script-bar broker-state hash (ABI v4; NULL / 0-length unless
58+
* strategy_set_broker_state_hash_recording is on) */
59+
uint64_t* broker_state_hash;
60+
int64_t broker_state_hash_len;
5661
} pf_report_t;
5762
```
5863

5964
@note The `metrics` / `equity_curve` fields were appended in **ABI
6065
version 2** (`PF_ABI_VERSION`). `pf_report_t` is caller-allocated, so
61-
consumers must check `pf_abi_version() == 3` before running — a `.so`
66+
consumers must check `pf_abi_version() == 4` before running — a `.so`
6267
with no `pf_abi_version` symbol is ABI v1 and predates these fields.
6368
**ABI version 3** appends `pf_trade_t::open_at_end`, the range-end close
64-
flag; a v2 reader would misindex the trades array.
69+
flag; a v2 reader would misindex the trades array. **ABI version 4**
70+
appends `pf_report_t::broker_state_hash` / `broker_state_hash_len`; a v3
71+
reader's struct is 16 bytes too small.
6572

6673
## Trade fields
6774

0 commit comments

Comments
 (0)