Skip to content

Commit 2fcbb52

Browse files
luisleo526claude
andcommitted
Docs: the migration page, the guide and the front doors say what the tree does (R5 lane F2, item 5)
Each statement below contradicted the tree; each now states the code's behaviour, re-read in the tree (and probed where noted): pine-to-native.md * closedtrades.entry_comment(): no C accessor exists (strategy_closed_trade _entry_id answers the id; pf_trade_t carries no strings) -> C column "--", with the open-lot route. * "Four members ... have no C spelling": the COVERAGE block excludes eleven members and two seams; the four named are the ones a port meets first, the rest are named by kind; the COVERAGE anchor is :48, not :45. * `time`/`bar_index`/"session facts" -> pf_native_decision_v1: the C decision carries no interval and no session fact; C++ adds script_interval / input_interval; neither has session-day flags. * close cause: BRACKET (2) is written only by the Pine adapter (pine_strategy_host.cpp exit_from_bracket); a native bracket leg closes as SCRIPT (1) (audit probe_bracket_cause), so the page says so. native-engine.md * native_continuation_hash(): portable since E23 (timezone by content), not "local to this machine". * subscription delivery: a session-clipped bucket completes Confirmed on its own last bar; LazyComplete is a hole over its last slot (probe: NY 0930-1600 "60" and "D" buckets, batch and stream); `interval` is the bucket's own period (deliver_timeframe_bar: interval_containing over the subscription's timeframe). * the OrderFill recalculation of a kernel liquidation runs after on_native_margin_call (invoke_applied_callback: applied, margin call; then the drain's recalculation), not "immediately after on_native_applied". * presented-clock queries: native_open_lots(mark) and native_marked_equity (mark) convert at active_account_currency_fx() too, beside native_liquidation_price(). * pf_native_run_spec_ext_v1 has four published lengths (the stale "now has three" / "now has two" sentences are history now), README likewise. * sizing: the fill-time "own terms" branches of the adapter's resolve_execution_terms restate the cash/percent quotient and fee reserve inline (pine_adapter.cpp), so "the arithmetic exists once" is dropped. docs/ci.md: six documentation guards -- four source-only preflight stages (doc-anchors, doc-lint, design-inventory, doc-pine-coverage; it named three), the executed-page CTest row, and the documentation build, which runs after a merge only (docs.yml: push to main, v* tags, dispatch). "0.1.1" literals (VERSION is 0.14.0): sample transcripts say <version>/<sha>; version.h, the pinned find_package, the pkg-config example and install.md name 0.14.0; integration-cmake.md states the package's SameMajorVersion compatibility. check_doc_anchors.py 1570/1570, check_doc_lint.py 0. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> (cherry picked from commit d9e972fc8005b553403048da8dfa62f687ba2825)
1 parent 516de3c commit 2fcbb52

11 files changed

Lines changed: 103 additions & 60 deletions

‎README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -496,10 +496,11 @@ declare all fail CI.
496496

497497
Every struct is tagged and size-prefixed (`struct_size`, `version`); an unknown
498498
size, version or enumerator is refused with a documented negative status and
499-
mutates nothing. `pf_native_run_spec_ext_v1` has three published lengths — the
499+
mutates nothing. `pf_native_run_spec_ext_v1` has four published lengths — the
500500
layout the lane first shipped (`PF_NATIVE_RUN_SPEC_EXT_V1_BASE_SIZE`), the same
501-
struct with L9's appended risk tail (`PF_NATIVE_RUN_SPEC_EXT_V1_RISK_SIZE`) and
502-
the current one with the auxiliary-feed tail behind it; `pf_native_callbacks_v1`
501+
struct with L9's appended risk tail (`PF_NATIVE_RUN_SPEC_EXT_V1_RISK_SIZE`), that
502+
plus N8's intrabar / policy tail (`PF_NATIVE_RUN_SPEC_EXT_V1_POLICY_SIZE`) and the
503+
current one with the auxiliary-feed tail behind it; `pf_native_callbacks_v1`
503504
has two — the layout the lane first shipped (`PF_NATIVE_CALLBACKS_V1_BASE_SIZE`)
504505
and the same struct with its appended tail. The runtime accepts each, so a host
505506
compiled against an earlier one keeps working unchanged. An **observation**

‎docs/ci.md‎

Lines changed: 29 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -368,9 +368,13 @@ drifted".
368368

369369
## Documentation guards
370370

371-
Four guards hold the published documentation to the tree. Three of them run
372-
from the source alone — no build, no corpus — and are `ci_preflight` stages;
373-
the fourth is the documentation build.
371+
Six guards hold the published documentation to the tree. Four of them run
372+
from the source alone — no build, no corpus — and are `ci_preflight` stages:
373+
`doc-anchors`, `doc-lint`, `design-inventory` and `doc-pine-coverage`. The
374+
fifth is a CTest row that compiles and runs the migration page's worked
375+
example, and the sixth is the documentation build, which runs after a merge
376+
(`.github/workflows/docs.yml` triggers on a push to `main`, a `v*` tag or a
377+
manual dispatch), never on a pull request.
374378

375379
`scripts/check_doc_anchors.py` checks every `file:line` citation the pages
376380
make: the file must resolve, the line must exist, and when a backticked symbol
@@ -394,7 +398,12 @@ python3 scripts/check_doc_anchors.py --fix # re-anchor what is provable
394398
`scripts/check_doc_lint.py` reads the prose instead: a `lane L<n>` roadmap
395399
label on a published page, a `there is no … yet / in this slice / today` claim <!-- verified HEAD -->
396400
whose line carries no `<!-- verified HEAD -->` marker, a stale epoch or hash
397-
domain, and a relative markdown link whose file or `#anchor` is missing. The
401+
domain, a relative markdown link whose file or `#anchor` is missing, a cited
402+
`tests/…`, `examples/…` or `scripts/…` path that does not exist, a count the
403+
tree derives stated wrong (the `PF_API` declarations of the two C headers,
404+
`KERNEL_MIN_TESTS` / `RELEASE_MIN_TESTS`, the example manifest of
405+
`check_native_include_independence.py`), and the marker itself sitting on a
406+
sentence that states a non-live epoch as today's. The
398407
marker on the line above is the escape hatch itself: this sentence names the
399408
pattern rather than claiming it, and the guard has no way to tell those apart,
400409
so somebody has to say so where the diff will show it. The
@@ -432,7 +441,22 @@ profile compiles, and fails when an inventory row's closure marker does not
432441
match what the tests actually drive. `--ctest-list` cross-checks its transliteration
433442
against real `ctest -N` output in both directions.
434443

435-
The fourth guard is the documentation build. `docs/build.sh` runs Doxygen over
444+
The fourth is `scripts/check_pine_to_native_coverage.py` (`doc-pine-coverage`),
445+
fail-closed from the day it landed as well: it derives the offered Pine set
446+
from `docs/pine_v6_coverage_detail.md` and the covered set from the migration
447+
page's own first table column, and fails when a `strategy.*`, `request.*` or
448+
`barmerge.*` name has no row.
449+
450+
The fifth guard is the CTest row `test_pine_to_native_worked`. At build time
451+
`tests/extract_pine_to_native_worked.py` copies the six C++ blocks of the
452+
migration page's worked example out of the page verbatim (and fails the build
453+
when the page stops holding them); `tests/test_pine_to_native_worked.cpp`
454+
compiles them against `PineForge::kernel`, runs them, and checks the outcomes
455+
the page states — `configure_native` applies, no request is refused, the
456+
take-profit closes the entry, and the units and the commission are the ones
457+
the page's own Pine declaration computes. The row registers in every profile.
458+
459+
The sixth guard is the documentation build. `docs/build.sh` runs Doxygen over
436460
the whole public surface — every header under `include/pineforge`, the C API
437461
and C ABI headers, the fifteen native examples, the adapter units, the pages,
438462
the front-door documents, the design document and the ADR — and then reads `docs/site/doxygen-warnings.log`.

‎docs/pages/abi-stability.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -274,15 +274,16 @@ lift the missing surface into the public ABI.
274274

275275
## Version macros
276276

277-
The generated `<pineforge/version.h>` exposes:
277+
The generated `<pineforge/version.h>` exposes, for this tree's `VERSION`
278+
(0.14.0):
278279

279280
```c
280281
#define PINEFORGE_VERSION_MAJOR 0
281-
#define PINEFORGE_VERSION_MINOR 1
282-
#define PINEFORGE_VERSION_PATCH 1
283-
#define PINEFORGE_VERSION_STRING "0.1.1"
284-
#define PINEFORGE_VERSION_FULL "0.1.1" /* or "0.1.1-3-gabc1234-dirty" */
285-
#define PINEFORGE_GIT_SHA "97c93d3"
282+
#define PINEFORGE_VERSION_MINOR 14
283+
#define PINEFORGE_VERSION_PATCH 0
284+
#define PINEFORGE_VERSION_STRING "0.14.0"
285+
#define PINEFORGE_VERSION_FULL "0.14.0" /* or "0.14.0-3-gabc1234-dirty" */
286+
#define PINEFORGE_GIT_SHA "<sha>"
286287
```
287288
288289
Use these for compile-time gating of features added in later minors:

‎docs/pages/examples-c.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ No Python, no scripting, no extra deps beyond `libc`. Total: ~120 lines.
1212

1313
```
1414
$ ./macd_runner ./strategy.so btcusdt_15m_7d.csv
15-
PineForge 0.1.1 (97c93d3) — 672 bars
15+
PineForge <version> (<sha>) — 672 bars
1616
trades: 49 net pnl: -190.85
1717
L 0.000000 -> 0.000000 pnl=+12.40 qty=10.0
1818
S 0.000000 -> 0.000000 pnl=-22.10 qty=10.0

‎docs/pages/examples-magnifier.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ hourly strategy) makes the magnifier sample intra-hour fills from the
2222

2323
```
2424
$ python3 magnifier_ab.py
25-
PineForge 0.1.1 — 672 input bars → 168 hourly script bars (ratio 4:1)
25+
PineForge <version> — 672 input bars → 168 hourly script bars (ratio 4:1)
2626
2727
without magnifier:
2828
trades: 19 net pnl: -5096.73 sub_bars: 0 ticks: 0

‎docs/pages/examples-rust.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ the report.
1010

1111
```
1212
$ cargo run --release -- path/to/strategy.so path/to/ohlcv.csv
13-
PineForge 0.1.1 (97c93d3) — 672 bars
13+
PineForge <version> (<sha>) — 672 bars
1414
49 trades, net pnl: -190.85
1515
L pnl= +12.40 qty=10.0
1616
S pnl= -22.10 qty=10.0

‎docs/pages/getting-started.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ Compile and run:
6363
```bash
6464
cc hello.c -lpineforge -lstdc++ -lm -o hello
6565
./hello
66-
# PineForge 0.1.1 (97c93d3)
66+
# PineForge <version> (<sha>)
6767
```
6868

6969
That's it — you have a working install. Next steps:

‎docs/pages/install.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,4 +84,5 @@ cmake --build build-smoke
8484
./build-smoke/smoke_consumer # prints the runtime version
8585
```
8686

87-
If this prints `0.1.1` (or whatever you installed) you're done.
87+
If this prints the version you installed (`0.14.0` for this tree's `VERSION`)
88+
you're done.

‎docs/pages/integration-cmake.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,13 +37,14 @@ Or set `CMAKE_PREFIX_PATH=/opt/pineforge`.
3737
## Version selection
3838

3939
```cmake
40-
find_package(PineForge 0.1 REQUIRED) # any 0.1.x
41-
find_package(PineForge 0.1.1 EXACT REQUIRED) # pinned
40+
find_package(PineForge 0.14 REQUIRED) # 0.14.0 or any later 0.x.y
41+
find_package(PineForge 0.14.0 EXACT REQUIRED) # pinned to this tree's VERSION
4242
```
4343

44-
Within a major version PineForge guarantees C ABI back-compat — see
45-
[ABI stability](@ref abi_stability) — so `0.1` (any compatible
46-
0.x.y) is the recommended pin.
44+
The package config is `SameMajorVersion`, and within a major version
45+
PineForge guarantees C ABI back-compat — see
46+
[ABI stability](@ref abi_stability) — so a minimum `0.x` (any compatible
47+
later 0.x.y) is the recommended pin.
4748

4849
## Linking from a hand-written Makefile
4950

@@ -73,7 +74,7 @@ libdir=${prefix}/lib
7374

7475
Name: pineforge
7576
Description: Deterministic PineScript v6 backtest runtime
76-
Version: 0.1.1
77+
Version: 0.14.0
7778
Cflags: -I${includedir}
7879
Libs: -L${libdir} -lpineforge -lstdc++ -lm
7980
```

‎docs/pages/native-engine.md‎

Lines changed: 34 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1175,9 +1175,10 @@ stands on the opening print it filled on — and converting there calls a margin
11751175
the account never owed (`tests/test_native_margin_fx_clock.cpp`). The rest of
11761176
the kernel already converts at the cursor: a `Sized` request freezes its units
11771177
at the acceptance coordinate's rate, and an execution term records its
1178-
`active_fx` at its own cursor. `native_liquidation_price()` is the one
1179-
exception, and it is the rule restated: a host query has no cursor of its own,
1180-
so it answers at the instant the engine is presenting.
1178+
`active_fx` at its own cursor. The host queries are the exception, and they
1179+
are the rule restated: `native_liquidation_price()`, `native_open_lots(mark)`
1180+
and `native_marked_equity(mark)` have no cursor of their own, so they answer at
1181+
the rate of the instant the engine is presenting.
11811182

11821183
Both sides are affine in `P`, so `L` is unique unless the slopes coincide —
11831184
`maintenance == 1.0` on a LONG, where equity and requirement move together and
@@ -1549,8 +1550,9 @@ At **one** point, in this order and no other:
15491550
2. `on_native_applied` for each applied event, FIFO, through the existing
15501551
notification drain under its re-entrancy guard.
15511552
3. With `BarCloseAndFills` or `EveryModeledPoint`, one `OrderFill`
1552-
recalculation at that event's own cursor, immediately after its
1553-
`on_native_applied`, driven from the same drain. It is bounded by
1553+
recalculation at that event's own cursor, right after its
1554+
`on_native_applied` — and, for a kernel liquidation, after the
1555+
`on_native_margin_call` that follows it — driven from the same drain. It is bounded by
15541556
`max_recalculations_per_point` (default 8) **per matching point**:
15551557
executions a callback drives through `execute_current` land at the same
15561558
cursor and spend the same budget, so a host that refills on its own fill
@@ -1754,7 +1756,7 @@ says otherwise, and the C spellings are in
17541756
| `native_recalculation_count()` / `native_recalculations_skipped()` | the calculations the cadence drove and the ones its per-point bound dropped | `strategy_native_recalculations_v1` |
17551757
| `native_decision_floor()` (`native_host.hpp:1267`) | the run's monotonic decision floor in epoch ms — the same value `NativeStateView::decision_floor_ms` carries, and the lower bound every request's birth is compared against | `pf_native_state_v1::decision_floor_ms` |
17561758
| `native_consumed_high_water()` (`native_host.hpp:1272`) | the highest `run_number` this host has consumed. It lives **outside** per-run reset, so the next configure on the same host needs a strictly larger number; a fresh host reads 0 | `pf_native_state_v1::consumed_high_water` |
1757-
| `native_continuation_hash()` | the consumer's continuation identity, local to this machine | `strategy_native_continuation_hash_v1` |
1759+
| `native_continuation_hash()` | the consumer's continuation identity: the timezone folded by its content, so the same spec over the same bars and zone rules answers the same value on every host | `strategy_native_continuation_hash_v1` |
17581760
| `native_sized_units(sized, price, equity, fx)` | the kernel's own `Sized` resolution as a pure query | none — see *Previewing a basis* |
17591761
| `inspect_current_execution(cmd)` | `NativeCurrentExecutionPreview`, with a `NativeCurrentRefusal` `native_host.hpp:685` when the command cannot be consumed here | none — `strategy_native_execute_current_v1` answers the same verdicts |
17601762

@@ -2143,10 +2145,11 @@ and the input's `on_native_bar` follows it.
21432145

21442146
- `lookahead = false` (Pine's `barmerge.lookahead_off`): the bucket is
21452147
delivered on the input bar that completes it, never earlier — its **last**
2146-
contributing input bar when that bar closes it (`Confirmed`), or, for a
2147-
bucket only a later input reveals as complete (a session-clipped bucket, a
2148-
hole over its last slot), the next period's **first** input bar
2149-
(`LazyComplete`), which contributes nothing to it.
2148+
contributing input bar when that bar closes it (`Confirmed`, a bucket the
2149+
session close clips short of its nominal end included: the calendar knows
2150+
that bar is the session's last), or, for a bucket only a later input reveals
2151+
as complete (a hole over its last slot), the next period's **first** input
2152+
bar (`LazyComplete`), which contributes nothing to it.
21502153
- `lookahead = true` (`barmerge.lookahead_on`): the completed bucket's final
21512154
OHLCV is delivered at its **first** contributing input bar, and
21522155
`native_series_bar` answers with it from then on.
@@ -2165,9 +2168,9 @@ and the input's `on_native_bar` follows it.
21652168

21662169
`NativeTimeframeBarContext::completion` is `Confirmed` when the bucket closed
21672170
on its own last contributing bar and `LazyComplete` when the next period's
2168-
first input closed it. `interval` is the calendar span of the bucket's first
2169-
contributing input bar; `delivered_at_ms` is the input bar the delivery rides
2170-
on. A bucket still open at the end of the input is never delivered.
2171+
first input closed it. `interval` is the bucket's own calendar interval — its
2172+
period at the subscription's timeframe, located by its first contributing bar;
2173+
`delivered_at_ms` is the input bar the delivery rides on. A bucket still open at the end of the input is never delivered.
21712174

21722175
**Chronology against the script interval.** The pump is ordered against the
21732176
*script* interval, not the raw input. With `script_tf` coarser than
@@ -2973,16 +2976,20 @@ and affordability gates, which consume a quantity before any request exists and
29732976
so cannot be a kernel decision. The percentage fee reserve is the kernel's
29742977
(`reserve_percent_fee`), and so is the conversion itself — including the
29752978
placement-time number those gates consume: the adapter reads it through
2976-
`native_sized_units()` and floors it, so the arithmetic exists once
2977-
(`tests/test_adapter_sizing_relower.cpp`, "the conversion exists once"). The two
2979+
`native_sized_units()` and floors it (`tests/test_adapter_sizing_relower.cpp`,
2980+
"the conversion exists once"). The two
29782981
lot floors stay the adapter's because neither is the kernel's `SnapToGrid` on
29792982
every input — the cash floor keeps a quotient a millionth of a lot under a
29802983
boundary raw, and the percent floor has no on-grid tolerance, so an exact lot
29812984
multiple such as `0.0392` on a `0.0001` grid comes out `0.0391` — both measured
29822985
in the same test ("the source lot floors are not the kernel floor"). Paths whose
29832986
sizing price is not the signal rule — a fill-time resize, a pure-stop entry
2984-
sized at its trigger level — keep `HostSized{Open}` and their own terms branch
2985-
(same test, "pure-stop default entry keeps its own branch"), and so do the
2987+
sized at its trigger level, a typed percentage reversal sized from the
2988+
hypothetical flatten's balance — keep `HostSized{Open}` and their own terms
2989+
branch (same test, "pure-stop default entry keeps its own branch"), and that
2990+
branch restates the same `cash / (price × point_value × fx)` quotient and
2991+
percent fee reserve inline in the adapter's `resolve_execution_terms` override
2992+
rather than calling `native_sized_units()`; so do the
29862993
percentage exits: the kernel resolves a `ScopeFraction` as `scope * fraction`,
29872994
which is not `scope * percent / 100`, and no field reconciles the association.
29882995
@@ -3463,11 +3470,11 @@ has no call that marks one, so its integer, 2, is refused like any other.
34633470
base-spec words: the kernel's validation judges them, and a bad one answers
34643471
-1 and leaves the host failed.
34653472
3466-
`pf_native_run_spec_ext_v1` now has **three** published lengths and the
3467-
runtime accepts any of them: the layout this header first shipped
3468-
(`PF_NATIVE_RUN_SPEC_EXT_V1_BASE_SIZE`), that plus the risk tail
3469-
(`PF_NATIVE_RUN_SPEC_EXT_V1_RISK_SIZE`), and the current one, which appends
3470-
what the header used to list as unrepresentable — the retained intrabar path
3473+
`pf_native_run_spec_ext_v1`'s third published length,
3474+
`PF_NATIVE_RUN_SPEC_EXT_V1_POLICY_SIZE`, ends the tail after the base layout
3475+
(`PF_NATIVE_RUN_SPEC_EXT_V1_BASE_SIZE`) and the risk tail
3476+
(`PF_NATIVE_RUN_SPEC_EXT_V1_RISK_SIZE`); the runtime accepts it and the other
3477+
three. That tail appends what the header used to list as unrepresentable — the retained intrabar path
34713478
(`PF_NATIVE_SPEC_EXT_INTRABAR`), the four feed-shape and presentation
34723479
policies (`PF_NATIVE_SPEC_EXT_FEED_POLICY`: slot labels, feed tolerance, the
34733480
forced path order, abort reporting), and the margin model's remaining knobs
@@ -3501,11 +3508,11 @@ past it, and any other length is `PF_NATIVE_E_STRUCT`.
35013508
The risk block (`PF_NATIVE_SPEC_EXT_RISK`) was the first **additive tail** in
35023509
this header. It appends `risk_*` fields — the two loss limits as a value plus
35033510
a percent flag, the two counts, the day basis and the breach action, each
3504-
limit opt-in through its own `has_` flag — past `reserved0`, so
3505-
`pf_native_run_spec_ext_v1` now has two published lengths and the runtime
3506-
accepts either: `PF_NATIVE_RUN_SPEC_EXT_V1_BASE_SIZE` (the layout this header
3507-
first shipped, defined as the offset of the first appended field rather than
3508-
as a literal, so it stays right on every target) and the current `sizeof`.
3511+
limit opt-in through its own `has_` flag — past `reserved0`, which gave
3512+
`pf_native_run_spec_ext_v1` its second published length — beside
3513+
`PF_NATIVE_RUN_SPEC_EXT_V1_BASE_SIZE` (the layout this header first shipped,
3514+
defined as the offset of the first appended field rather than as a literal, so
3515+
it stays right on every target) — ending at `PF_NATIVE_RUN_SPEC_EXT_V1_RISK_SIZE`.
35093516
Each subscription row (`pf_native_subscription_v1`) carries `lookahead` and
35103517
`gaps` as `uint32_t` words holding a `pf_native_lookahead_e`
35113518
(`PF_NATIVE_LOOKAHEAD_AT_COMPLETION` / `_AT_FIRST_INPUT`) and a

0 commit comments

Comments
 (0)