Skip to content

Commit 46b2ced

Browse files
luisleo526claude
andcommitted
docs: ABI v4 live surface; cheatsheet corrections (trail_price is read; v4 accessors; corpus slippage facts)
README.md: symbol table and version line updated from ABI v3/32 symbols to ABI v4/56 symbols (32 + 24, verified by counting `^PF_API ` declarations); 24 new rows for the live-runtime surface; pf_report_t's broker_state_hash array and pf_pending_order_v1_t noted; v0.14.0 release line added. docs/cheatsheet-runtime-and-execution.md: three corrections against the actual code (per AGENTS.md SOP, spec item 3.9) -- - trail_price IS read by the fill path (engine_fills.cpp:4916-4926, 8006-8019: used as the trail-activation level whenever trail_points is unset), not "accepted but ignored". - the equity curve exists since ABI v2; ABI v4 adds the closed-trade id/exit-id/exit-comment/close-cause accessors and strategy_script_bars_processed; entry_bar_index/exit_bar_index were already struct fields on pf_trade_t pre-v4 (no "ABI vN" doc-comment tag), so the old "no bar_index over the C ABI" claim was already wrong independent of this task -- what remains genuinely unavailable is stated explicitly. - corpus slippage/commission facts corrected: 252/312 probes run slippage=0, but 60/312 declare slippage=1|2 and 62/312 a non-zero commission_value -- the adjacent "masked because all probes run slippage=0" argument for the possible close_opposite_then_enter double-slip bug does not hold for those 60; flagged inline rather than silently kept, since whether any of them exercises that path is unverified (out of scope here: src/ is not touched by this task). docs/pages/streaming.md: new paragraph stating pineforge-live does not use the strategy_stream_* lifecycle (different fill model) and instead recomputes run_backtest_full over script-TF bars with the ABI v4 flags; links to the new page. docs/pages/live-surface.md (new): the 24 v4 symbols in one table (purpose/ default/"changes history?"=No), flag semantics for realtime_tail, probe_suppress_tail_logic, path_order and broker_state_hash_recording matching spec sec 3.1-3.4 exactly, abort semantics (3.5), string lifetimes and exit-id conventions, the report array, the generated pending-order mirror, and an evidence section naming the three L0 lanes with their published numbers (identity 312/0 differ; live-flags 312/0 positives/130 open-at-end subtracted; bar-identity row 1: 222295 bars/2 explained/0 else). Added to docs/Doxyfile's INPUT list (this repo's Doxygen nav) and linked from docs/pages/index.md's realtime-feed tab. Verified: check_c_abi_runtime.py, check_broker_state_hash_coverage.py, gen_pending_order_mirror.py --check all pass; grep -c strategy_set_realtime_tail README.md docs/pages/live-surface.md -> README.md:1, live-surface.md:5; ctest 240/240; src/include/corpus/tests untouched by this commit. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_013ZEL52UCofp3j7gfABW7uB
1 parent d897538 commit 46b2ced

6 files changed

Lines changed: 315 additions & 16 deletions

File tree

‎README.md‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -209,7 +209,7 @@ TradingView ties some day-boundary logic (intraday order caps, session rollovers
209209

210210
## Public C ABI
211211

212-
`<pineforge/pineforge.h>` is the single canonical consumer header. Every compiled strategy `.so` exports exactly these 32 symbols and no internal C++ symbol (`-fvisibility=hidden`, `PF_API` on the public set, checked in CI by `scripts/check_c_abi_runtime.py`):
212+
`<pineforge/pineforge.h>` is the single canonical consumer header. Every compiled strategy `.so` exports exactly these 56 symbols and no internal C++ symbol (`-fvisibility=hidden`, `PF_API` on the public set, checked in CI by `scripts/check_c_abi_runtime.py`):
213213

214214
| Symbol | Role |
215215
|---|---|
@@ -227,9 +227,21 @@ TradingView ties some day-boundary logic (intraday order caps, session rollovers
227227
| `strategy_set_native_security_feed` / `strategy_set_aux_security_feed` | Feed `request.security()` from a native higher-timeframe series / an auxiliary bar-aligned feed |
228228
| `strategy_set_account_currency_fx_series` | Effective-time quote-to-account FX |
229229
| `strategy_get_last_error` | The latest runtime error |
230-
| `pf_version_get` / `pf_version_string` / `pf_abi_version` | Runtime version, version string, struct-layout version (`PF_ABI_VERSION == 3`) |
231-
232-
POD types `pf_bar_t`, `pf_trade_tick_t`, `pf_trade_t`, `pf_report_t`, `pf_security_diag_t`, `pf_trace_entry_t`, `pf_version_t`, `pf_trade_stats_t`, `pf_equity_stats_t`, `pf_metrics_t`, `pf_equity_point_t` and the `pf_magnifier_distribution_t` enum complete the surface. ABI v2 added computed trading metrics and a per-bar equity curve; ABI v3 added `pf_trade_t::open_at_end`, TradingView's range-end close of a position still open after the last bar. Check `pf_abi_version()` before running: the report struct is caller-allocated.
230+
| `pf_version_get` / `pf_version_string` / `pf_abi_version` | Runtime version, version string, struct-layout version (`PF_ABI_VERSION == 4`) |
231+
| `strategy_request_abort` / `strategy_last_run_status` | Cooperative abort of a run in progress; `0`=completed, `1`=aborted |
232+
| `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 |
234+
| `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 |
235+
| `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 |
236+
| `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 |
238+
| `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 |
239+
| `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` |
240+
| `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 |
241+
242+
POD types `pf_bar_t`, `pf_trade_tick_t`, `pf_trade_t`, `pf_report_t`, `pf_security_diag_t`, `pf_trace_entry_t`, `pf_version_t`, `pf_trade_stats_t`, `pf_equity_stats_t`, `pf_metrics_t`, `pf_equity_point_t`, `pf_pending_order_v1_t`, `pf_field_desc_t` and the `pf_magnifier_distribution_t` enum complete the surface. ABI v2 added computed trading metrics and a per-bar equity curve; ABI v3 added `pf_trade_t::open_at_end`, TradingView's range-end close of a position still open after the last bar; ABI v4 added the live-runtime accessors above plus `pf_report_t::broker_state_hash` / `broker_state_hash_len` (a per-script-bar broker-state hash array, appended after `equity_curve_len`, NULL/0-length unless `strategy_set_broker_state_hash_recording` is on) and the `pf_pending_order_v1_t` generated POD mirror of the engine's resting-order record. Check `pf_abi_version()` before running: the report struct is caller-allocated.
243+
244+
Full flag semantics, string lifetimes and the three L0 evidence lanes behind the ABI v4 live surface: [`docs/pages/live-surface.md`](docs/pages/live-surface.md).
233245

234246
**Stability guarantee.** Within a major version, struct layouts and `extern "C"` signatures are append-only — fields and functions are added, never reordered, removed or retyped; `static_assert`s in `src/c_abi.cpp` pin the layouts. Semantic versioning at the ABI level: PATCH never touches the ABI, MINOR appends, MAJOR breaks. A `.so` built against `0.X.Y` keeps working on any later `0.X.Z`.
235247

@@ -261,6 +273,7 @@ Documentation: [C ABI reference](https://cdocs.pineforge.dev) · [Getting starte
261273

262274
## Releases
263275

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.
264277
- **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.
265278
- **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).
266279
- **v0.6.0** — performance sprint: cached static inputs, thread-local timestamp caching, lazy timezone caching; up to 6.7M bars/s.

‎docs/Doxyfile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ INPUT = ../include/pineforge/pineforge.h \
9191
pages/integration-cmake.md \
9292
pages/lifecycle.md \
9393
pages/streaming.md \
94+
pages/live-surface.md \
9495
pages/report-schema.md \
9596
pages/metrics.md \
9697
pages/configuration.md \

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

Lines changed: 33 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -343,11 +343,18 @@ Audited gaps a forward/real-time executor must know (beyond per-order fills).
343343
placement gate, and deferred-flip carry; closes-only into an opposite position
344344
(no re-entry); same pyramiding bypasses as ENTRY; OCA-cancel fires on any fill
345345
for NaN-qty siblings.
346-
- **Trail caveats:** `trail_price` param is **accepted but ignored**;
347-
`trail_points`/`trail_offset` are `ceil`-ed to whole ticks before computing
348-
the activation level; **no-offset trail** (`exits_at_activation`) fires at the
349-
activation level itself; `trail_best_price_` resets to `close` on the first
350-
`strategy.exit` for an id (preserved on re-issue).
346+
- **Trail caveats:** `trail_price` **is read by the fill path**, not ignored:
347+
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;
355+
**no-offset trail** (`exits_at_activation`) fires at the activation level
356+
itself; `trail_best_price_` resets to `close` on the first `strategy.exit`
357+
for an id (preserved on re-issue).
351358
- **Entry-bar wrong-side exit:** non-magnifier, an exit whose stop is on the
352359
wrong side of entry is **silently skipped** on the entry bar (na-stop guard);
353360
magnifier evaluates it (gap-fills at sub-bar open).
@@ -412,9 +419,19 @@ Audited gaps a forward/real-time executor must know (beyond per-order fills).
412419
## 3.9 Report surface (C ABI)
413420

414421
- `pf_report_t`/`pf_trade_t` expose `entry/exit time/price`, `pnl`, `pnl_pct`,
415-
`is_long`, `qty`, `max_runup/drawdown` + run diagnostics. **No equity curve**
416-
and **no `entry_id`/`exit_id`/comments/`bar_index`** over the C ABI — those
417-
are C++-accessor-only. Derive equity/profit-factor/Sharpe from the trades.
422+
`is_long`, `qty`, `max_runup/drawdown`, `entry_bar_index`/`exit_bar_index`,
423+
`open_at_end` (ABI v3) + run diagnostics. **The equity curve exists since
424+
ABI v2** (`pf_report_t::equity_curve`/`equity_curve_len`, per-script-bar).
425+
**ABI v4 adds**: `strategy_closed_trade_entry_id`/`_exit_id`/`_exit_comment`
426+
(per-trade id/comment strings, C-accessor-only — not struct fields),
427+
`strategy_closed_trade_close_cause` (an enum: `SCRIPT`/`BRACKET`/
428+
`MARGIN_CALL`/`INTRADAY_LOSS_CAP`/`INTRADAY_FILL_CAP`/`RANGE_END`), and
429+
`strategy_script_bars_processed`. Still **not** available over the C ABI:
430+
a per-trade `bar_index` beyond `entry_bar_index`/`exit_bar_index` (e.g. no
431+
per-fill-leg or per-bracket-order bar index), the pending-order book's own
432+
history (only the live snapshot via `strategy_pending_order_get`), and
433+
per-bar Pine variable/series values outside `// @pf-trace` tracing. Derive
434+
profit-factor/Sharpe from `pf_metrics_t` or the trades.
418435
- `pf_version_get()` / `pf_version_string()` for ABI gating.
419436

420437
## 3.10 Multi-run state and streams
@@ -439,6 +456,11 @@ Audited gaps a forward/real-time executor must know (beyond per-order fills).
439456

440457
`close_opposite_then_enter` (`engine_orders.cpp:539`) calls `apply_slippage`,
441458
then `execute_partial_exit_qty` (`engine_orders.cpp:154-155`) applies it
442-
**again** → the bracket close-then-enter exit may be **double-slipped**. Masked
443-
in the corpus because all probes run `slippage=0` (double-rounding is
444-
idempotent there). Worth a targeted test before trusting slippage on that path.
459+
**again** → the bracket close-then-enter exit may be **double-slipped**. The
460+
public corpus is **not** uniformly `slippage=0`: 252/312 probes declare no
461+
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+
idempotent-zero argument does not apply, and whether any of them actually
465+
exercises `close_opposite_then_enter` is unverified. Worth a targeted test
466+
before trusting slippage on that path.

‎docs/pages/index.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,10 @@ consumption.
4444
- <b class="tab-title">I'm connecting a realtime feed</b>
4545
Start with **[Historical to realtime streaming](@ref streaming)** for
4646
the warmup, ordered-trade, clock, and report lifecycle, then run
47-
`tutorial/run_stream.py` against the bundled MACD strategy.
47+
`tutorial/run_stream.py` against the bundled MACD strategy. Building the
48+
`pineforge-live` recompute runtime instead? Read
49+
**[ABI v4 live surface](@ref live_surface)** — streaming's lifecycle is
50+
not what it uses.
4851

4952
- <b class="tab-title">I'm analysing backtest results</b>
5053
Read the **[Trading metrics reference](@ref metrics)** — every

0 commit comments

Comments
 (0)