Skip to content

Commit c5c611a

Browse files
committed
Docs+Gates: every kernel seam and every kernel member the source layer writes gets an ADR-0001 row, the account of TradingView-justified comments is complete, and a gate holds the inventory (R5 lane H-DOCGATES, X10)
AUDIT4-opus X10 found the ADR contradicting itself and the tree. Each sentence was re-derived on this tree: - The examples sentence claimed every C++ host includes only native_host.hpp. Three include native_toolkit.hpp or native_module.hpp (both include native_host.hpp) and the two C hosts include pineforge.h; "each including only `<pineforge/native_host.hpp>` (or `native_c_api.h`)" is rewritten to say so. - The build_close_trade_with_costs row still said "One question stays open, recorded at the site: the net basis is applied to a host-owned excursion's magnitudes too (RULING A48's hook)". R5 lane F3 closed it in 684800b; the row now says so and scopes the net basis to the kernel's own sampled excursions. - The neutral-spellings row said map.hpp and drawing.hpp are neutral names with deprecated pine_* aliases, "already ruled: "Neutral spellings" above" -- a section that does not exist, contradicting the residual table's PineMap row (primaries with no neutral alias). The row now names both cases and cites the two residual rows. - "They do not yet account for the whole population" (the paragraph ending "until each gets a row or moves") and the Consequences bullet "Not yet fully accounted for" contradicted rule 2's "no site left unruled". Four Section B rows close the eighteen unruled lines the audit's closure grep found (the chart-day partition, the bar-time accessors, the offset sign, the grid and lot helpers); the paragraph now records the re-taken census (369 comment lines in 44 of 92 files, none unruled) and the bullet says the count is held by reading, not by a gate. Rule 2 pointed at "the section below"; the section is above. - Rule 1 now names the generated-code language runtime and its admission test, which the three category rows apply. - The subscriptions row listed four exclusions ("the sites the predicate leaves out (lower timeframe, lookahead, auxiliary, streams) keep the source evaluator"); declare_security_sites_to_kernel has fifteen and declares every site or none. The row lists them. - Fourteen new rows in "Kernel state the adapter sets" cover every seam and member the new gate finds, including the two whole-struct current_bar_ writes (E21 check e), broker_fill_event_seq_, the dead source_stream_entry_comment (scheduled for the next script-ABI epoch in docs/native-refactor-progress.md), fold_exit_trail_peak_, NativeHostCache and the rows AG1/AG2 re-date. The dust sweep is recorded OPEN for lane H-THIN (A4-DUST); the position_entry_count_ overwrite is recorded OPEN. - Design row RP5 said the short-seed swaps are "measured in §3.7 part 2"; no row there measures them, and it now says so. The second "### 3.8" (lane F9) is §3.9, and RP9's "§3.8 records the old quadratic adapter fold" now points at it. - Two engine.hpp comments were false: "Generated code reads them for Pine's bare ``hour``" (the transpiler emits pine_hour(..., syminfo_.timezone); no corpus strategy names a _bar_* accessor) and script_tf_'s writers "(both sites live in engine_run.cpp)" (the one writer is the Pine host). Comment-only, line-count preserving: all 86 library objects are byte-identical with and without the edit. scripts/check_kernel_seam_rows.py (a binding ci_preflight stage, with its must-fail suite as ci_preflight stage and CTest row test_kernel_seam_rows) fails when a kernel `virtual source_*` seam, a BacktestEngine member the source layer writes, or a Trade / PyramidEntry field written through the kernel's rows has no ADR-0001 row naming it in its first cell. Over this commit's parent it reports 43 without a row; here 0. It reads class bodies itself: check_broker_state_hash_coverage.py loses a member declared right after an inline function body (current_bar_, bar_magnifier_enabled_, trace_buffer_). KERNEL_MIN_TESTS 274 -> 275, RELEASE_MIN_TESTS 675 -> 676. Sentences deleted or rewritten, by the commit that wrote them: ca0aac5 (INT16's examples sentence), 2757095 (P2's lead-in of the mechanism table), 5691220 (L14-C's neutral-spellings row), 2dd9834 (F2's "The rows above account" paragraph and its "Not yet fully accounted for" bullet) and d3cca9e (the gates paragraph's closing sentence, now naming the seam-row gate beside the review record). Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> (cherry picked from commit 4cbc6ab6c1d8925d2d9353fc030ab511665252f9) INT26 pick note: the merged pages keep both sides. - ADR-0001 inventory: INT25's K-ULP4 and K-ULP5 rows stay after the journal window row (its V19-FIX wording kept), then this commit's fourteen rows. - ADR `subscriptions` row: this commit's all-or-nothing predicate list, plus the one clause it left out (`declare_security_sites_to_kernel` also refuses a registry whose `sec_id`s are not dense from 0), then H-MEASURE's measured sentence on what each reachable clause changes (c77ee9f9). - ADR close-trade row: this commit's closed A48 question and H-MEASURE's report-only excursion columns (word merge). - ADR rule-2 paragraph: this commit's gate list, then INT25's C-SURFACE-1.0 transport ruling section unchanged. - design RP5: H-MEASURE's measured short-seed sentence stays; this commit's "unmeasured: §3.7 has no row for them" was true only before H-MEASURE's `tests/test_short_seed_report_swap.cpp` (37090e1). - floors: this commit's seam-row self-test adds one row to the merged values (KERNEL 280 -> 281, RELEASE 692 -> 693). check_kernel_seam_rows on the merged tree: 3 seams, 44 written members, 0 without a row.
1 parent daae552 commit c5c611a

14 files changed

Lines changed: 657 additions & 43 deletions

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,7 @@ What each gate refuses:
138138
| `check_native_c_api_surface.py` | a public `NativeStrategyHost` member with no C spelling and no recorded reason |
139139
| `check_native_feature_rulings.py` | a `NativeRunSpec` field the adapter does not declare and the ADR does not rule |
140140
| `check_kernel_residuals.py` | a TradingView-shaped name reaching the kernel archive or its installed headers without an ADR 0001 row |
141+
| `check_kernel_seam_rows.py` | a kernel `virtual source_*` seam, or a kernel member or row field the source layer writes, that no ADR 0001 row names in its first cell |
141142
| `check_native_cpp_versions.py`, `check_aggregate_cpp_versions.py` | an internal C++ epoch moved without its consumers |
142143
| `check_adapter_spec_shadowing.py` | the adapter setting a kernel field it is ruled not to set |
143144
| `check_twin_parity.py` | a frozen test assertion rewritten instead of a behaviour change being argued |

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -393,6 +393,7 @@ The gates a pull request passes, one line each:
393393
| TradingView parity | `./scripts/check_corpus_parity.sh --subset` | A trade that moved: 54 probes re-run and hashed against `scripts/corpus_parity_baseline.txt`. The full 312-probe sweep (`--subset` dropped) runs nightly. |
394394
| CTest row floors | `ci_verify.py release` / `kernel` | A test row that vanished: each profile counts the rows that actually ran against a floor. |
395395
| Kernel residuals | `scripts/check_kernel_residuals.py` | A TradingView-shaped name reaching the kernel archive or its installed headers without an ADR 0001 row. |
396+
| Kernel seams | `scripts/check_kernel_seam_rows.py` | A kernel `source_*` seam, or a kernel member or row field the source layer writes, with no ADR 0001 row. |
396397
| Feature rulings | `scripts/check_native_feature_rulings.py` | A `NativeRunSpec` field the adapter does not declare and the ADR does not rule. |
397398
| C surface | `scripts/check_c_abi_runtime.py`, `scripts/check_native_c_api_surface.py` | A `PF_API` export added without its inventory row; a public host member with no C spelling and no recorded reason. |
398399
| Twin parity | `scripts/check_twin_parity.py` | A frozen assertion quietly rewritten instead of a behaviour change being argued. |

‎docs/adr/0001-kernel-adapter-boundary.md‎

Lines changed: 72 additions & 28 deletions
Large diffs are not rendered by default.

‎docs/ci.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -511,6 +511,23 @@ The kernel-residual gate's ruled counts have floors beside the CTest floors
511511
(`ADR_RULED_IDENTIFIERS_MIN`, `ADR_RULED_TEXTS_MIN` in `scripts/ci_verify.py`), so
512512
a ruling that leaves ADR-0001 together with its name is an edit of that file too.
513513

514+
`scripts/check_kernel_seam_rows.py` (`kernel-seam-rows`, with
515+
`kernel-seam-rows-tests`) holds the boundary the residual gate cannot name. A
516+
kernel seam the source layer implements, or a kernel member it writes, is the
517+
boundary itself, and its name need not hold a TradingView word. The gate reads
518+
every `virtual source_*` a kernel header declares, and every `BacktestEngine`
519+
member and `Trade` / `PyramidEntry` field that code under `src/source/`,
520+
`src/compat/` and their include trees assigns, increments or mutates. It fails
521+
when ADR-0001 has no table row naming one in its first cell; a row field counts
522+
only spelled qualified (`Trade::exit_time`). It reads the class body itself,
523+
because `scripts/check_broker_state_hash_coverage.py` splits a class at `;`
524+
alone and loses the member declared right after an inline function body. `--list`
525+
prints the inventory with each write site.
526+
527+
```sh
528+
python3 scripts/check_kernel_seam_rows.py --list
529+
```
530+
514531
The third source-only guard is `scripts/check_design_inventory.py`
515532
(`design-inventory`, with its own `design-inventory-tests` suite). It was
516533
fail-closed from the day it landed: it reads `docs/design/native-feature-parity.md`

‎docs/design/native-feature-parity.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -163,7 +163,7 @@ Columns: **Feature** (adapter mechanism, cited) · **Native today** (`yes` / `pa
163163
| RP6 | Per-trade accessors | **partial** — `get_trade` is public; the `closed_trade_*` family is protected engine.hpp:1391 **Closed:** `closed_trade_count()` / `closed_trade(i)` and `report_trade_count()` / `get_report_trade(i)` are public, and `closed_trade_close_cause(i)` engine.hpp:1833 answers the typed `execution::CloseCause` the closer recorded (`tests/test_native_report_truth.cpp`). | K | L2 | F:H6 | (single-source) |
164164
| RP7 | Live order-action stream (runner ledger / webhook) | **yes** — `stream_observe_actions_` engine_execution.cpp:1293, enabled `stream_observe_actions_` native_execution_consumer.cpp:9280, C ABI `strategy_stream_order_actions_len` c_abi.cpp:663-680 | K | — | F:H5 | (single-source) |
165165
| RP8 | Continuation hash | **yes** — `native_continuation_hash` native_host.hpp:1358, native_execution_consumer.cpp:10682; the spec is folded by `hash_spec` native_execution_consumer.cpp:238-260 | K | — | F:I1 O:J2 S:X3 | — |
166-
| RP9 | Broker-state hash: scalar + per-bar recording | **partial** — scalar `broker_state_hash` engine_state_hash.cpp:22-118, C ABI `strategy_broker_state_hash` c_abi.cpp:538; per-bar rows are appended only by the source scheduler `scheduler_record_broker_hash` pine_strategy_host.cpp:1931 **Closed:** under `KernelRecorded` with `set_broker_state_hash_recording(true)` the consumer appends one `broker_state_hash()` row after each report point, so `broker_state_hash_len == equity_curve_len == script_bars_processed` on a completed run in batch and across a stream's warmup and realtime legs. A Failed or Aborted run can expose a shorter prefix. A row is the run's continuation identity at that bar, per driving mode — the broker half alone is mode-invariant (`tests/test_native_report_truth.cpp`). | K | L2 | F:I2 O:J1 S:X3 | O's "yes" covers the scalar only. §3.8 records the old quadratic adapter fold and closed-row kernel walk as history; V19-E and V19-A replaced them with running digests. |
166+
| RP9 | Broker-state hash: scalar + per-bar recording | **partial** — scalar `broker_state_hash` engine_state_hash.cpp:22-118, C ABI `strategy_broker_state_hash` c_abi.cpp:538; per-bar rows are appended only by the source scheduler `scheduler_record_broker_hash` pine_strategy_host.cpp:1931 **Closed:** under `KernelRecorded` with `set_broker_state_hash_recording(true)` the consumer appends one `broker_state_hash()` row after each report point, so `broker_state_hash_len == equity_curve_len == script_bars_processed` on a completed run in batch and across a stream's warmup and realtime legs. A Failed or Aborted run can expose a shorter prefix. A row is the run's continuation identity at that bar, per driving mode — the broker half alone is mode-invariant (`tests/test_native_report_truth.cpp`). | K | L2 | F:I2 O:J1 S:X3 | O's "yes" covers the scalar only. §3.9 records the old quadratic adapter fold and closed-row kernel walk as history; V19-E and V19-A replaced them with running digests. |
167167
| RP10 | Fold the host's own durable state into the hash | **partial** — the protected virtual `hash_source_extension` engine.hpp:411 is overridable but source-named; the kernel default folds `"source:none"` engine_state_hash.cpp:19-21 **Closed:** `hash_host_extension(BrokerStateHashSink&)` engine.hpp:405 is the generic seam — protected virtual on `BacktestEngine`, called once per hash, last — and `hash_source_extension` engine.hpp:411 is its deprecated spelling, which the generic default forwards to (`tests/test_native_host_hash_extension.cpp`). | K | L2 (the virtual rides the shared bump) | F:I3 O:J1 S:X3 | — |
168168

169169
### 1.9 Other runtime surface
@@ -934,7 +934,7 @@ this lane re-pins the affected v19 witnesses once.
934934
935935
---
936936
937-
### 3.8 Audit lane F9 — recording and continuation costs (E24's STOP bucket)
937+
### 3.9 Audit lane F9 — recording and continuation costs (E24's STOP bucket)
938938
939939
Per-bar recording (`set_broker_state_hash_recording(true)`, §1.8 RP9) appends
940940
one `broker_state_hash()` per script bar, and every row is a whole fold: the

‎docs/native-refactor-progress.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,6 +247,12 @@ Mac's 489 and 412 and 1003 of 1249, and no Mac output moved.
247247
`PineStrategyHost`'s and so of the generated script's ABI. They go at the next
248248
`engine_script_run` epoch, with their two rows in
249249
`scripts/broker_state_hash_waivers.txt`, which say so.
250+
- **The dead stream seam.** `BacktestEngine::source_stream_entry_comment`
251+
(`include/pineforge/engine.hpp`) has two implementations, the kernel's
252+
default and the Pine host's override, and both do nothing. It is a virtual
253+
of the class every generated strategy derives from, so deleting it moves the
254+
vtable of every generated script. It goes at the next `engine_script_run`
255+
epoch (ADR-0001, the row "`source_stream_entry_comment`").
250256

251257
## Publication and acceptance
252258

‎docs/pages/contributing-llm.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,12 @@ finding to report, not a step to take.
5555
`nm` over the built `libpineforge_kernel.a`, reads the headers the kernel
5656
profile installs and the string literals of the kernel's own translation
5757
units, and fails on a TradingView-shaped name with no row in ADR 0001's
58-
residual table.
58+
residual table. `scripts/check_kernel_seam_rows.py` fails on a kernel
59+
`source_*` seam, or a kernel member or row field the source layer writes,
60+
that no ADR 0001 row names in its first cell. The generated-code language
61+
runtime (the indicator, formatting and calendar libraries and the
62+
header-only runtime) implements Pine built-ins by definition; ADR 0001
63+
rule 1 gives the admission test a new built-in must pass to enter it.
5964

6065
2. **A kernel capability is opt-in.** A new `NativeRunSpec` field, a new
6166
request kind, or a new virtual with an empty default — never a changed

‎include/pineforge/engine.hpp‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1044,13 +1044,13 @@ class BacktestEngine {
10441044

10451045
// --- Time/date extraction from bar timestamp ---
10461046
// The current bar's time components in UTC, the engine's storage
1047-
// timezone. Generated code reads them for Pine's bare ``hour`` /
1048-
// ``minute`` / ``dayofweek`` (the variable form), which the language
1049-
// defines on the symbol's exchange timezone -- UTC for the crypto symbols
1050-
// that are most of the corpus, so the cheap ``gmtime_r`` path is exact
1051-
// there. The 1-arg function form ``hour(time)`` is the codegen's own
1052-
// (codegen/visit_call.py) and honours ``syminfo_.timezone`` (set via
1053-
// ``strategy_set_chart_timezone``).
1047+
// timezone, memoized per stamp. Protected, so generated code could call
1048+
// them, but the codegen transpiler does not: it spells Pine's bare
1049+
// ``hour`` / ``minute`` / ``dayofweek`` ... as pine_hour(current_bar_.
1050+
// timestamp, syminfo_.timezone) and its siblings (session_time.hpp), on
1051+
// the symbol's exchange timezone, and no generated corpus strategy names
1052+
// one of these. Their callers are the tests that pin the UTC reading
1053+
// (test_chart_timezone, test_intraday_rollover_chart_tz_l4a).
10541054
struct BarTime {
10551055
int year, month, dayofmonth, hour, minute, second, dayofweek, weekofyear;
10561056
};
@@ -1122,8 +1122,8 @@ class BacktestEngine {
11221122
std::string input_tf_;
11231123
std::string script_tf_;
11241124
// Cached tf_to_seconds(script_tf_). MUST be refreshed immediately after
1125-
// every assignment to script_tf_ (both sites live in engine_run.cpp).
1126-
// Avoids a string parse per strategy.* call.
1125+
// every assignment to script_tf_ (the one writer is the Pine host's
1126+
// scheduler_prepare_script_run). Avoids a string parse per read.
11271127
int script_tf_seconds_ = 0;
11281128
TimeframeAggregator script_tf_agg_;
11291129
int64_t prev_bar_timestamp_ = 0;

0 commit comments

Comments
 (0)