Skip to content

Commit c619f5f

Browse files
luisleo526claude
andcommitted
Docs: a replace that keeps its handle or carries a binding, its ADR-0001 ruling, and the citations re-anchored (R5 lane V19-D, step 8)
docs/pages/native-engine.md: keep_handle and keep_binding beside retain_trigger_state -- what each keeps, the priority number, the unrecorded bind taking the event's ordinal, no C spelling, and why the Pine adapter takes keep_binding alone. docs/pages/pine-to-native.md names them where it lists ReplaceOptions. docs/adr/0001-kernel-adapter-boundary.md: a kernel state row ruling the options generic and opt-in (rule 2 (a) and (b)), with their witnesses. Every citation re-anchored to this tree (check_doc_anchors.py --fix, then reanchor_doc_citations.py --ref 6c081f5 and --ref HEAD for the one this page's own edit moved); 1,629 anchors resolve, doc lint clean. INT23 takes this commit's three content blocks only (the ADR-0001 row for keep_handle / keep_binding, native-engine.md's paragraph on them, the pine-to-native.md line naming them); its citation digit moves are left to the one re-anchor at the end of the integration. The ADR row lands where the lane put it, above the ema_na_warmup_flag row, whose wording D2-C's docs content (a8b0787) changed -- a 3-way merge conflict on adjacent lines, resolved as both rows. (cherry picked from commit 5518a9768a4022e64e0de717f51135a46c6ab169, content only) Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 9906e1c commit c619f5f

3 files changed

Lines changed: 19 additions & 1 deletion

File tree

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -441,6 +441,7 @@ see a mechanism, so these rows are held by reading, not by the checker):
441441

442442
| kernel state | who writes it | ruling |
443443
|---|---|---|
444+
| a replacement that keeps its handle or carries a book binding -- `ReplaceOptions::keep_handle` / `keep_binding`, and the definition's `priority` and `kept_binding` beside them (`include/pineforge/native_order.hpp`); the book held in priority order with a re-priced row's alias (`WorkingRequestCore`, `src/native_order.cpp`) | any C++ host, per replace command (`NativeStrategyHost::replace(handle, request, options)`); the Pine adapter sets `keep_binding` on every re-issue (`PineExecutionAdapter::submit_or_replace`) and never `keep_handle`; no C spelling | **generic, opt-in** (R5 lane V19-D). Rule 2 (a), mechanism: re-pricing a working order in place and keeping a close bound to an unchanged position are venue-neutral order-management facts, spelled with no platform word. `keep_handle` keeps the predecessor's handle, lineage, dependents and a trail's arm ordinal, and ranks the request by a priority number taken from the incarnation counter (the number a plain successor would have taken), so ties order a re-priced request newest and `issued()` never sees an incarnation twice; `keep_binding` binds at the next point, unrecorded, to the very book close the `CloseBoundEvent` would have installed and takes that event's ordinal, and binds as a plain successor when the book moved. Rule 2 (b), knob: none -- a host names the option per command; a replace without options is the plain replace, value for value. Pinned by `tests/test_native_handle_stable_replace.cpp` (kernel-only: plain vs each option set over randomized scripts, direct and staged paths) and `tests/test_adapter_live_state_equivalence.cpp` (`--reissue-binding`: the Pine battery carrying vs plain). |
444445
| `ta::ema_na_warmup_flag()` — the calling thread's ambient default for `ta::EmaSeeding`, `false` = `FirstValue`, `true` = `SimpleAverage` (`include/pineforge/ta.hpp`, `src/ta_moving_averages.cpp`; held in the thread's runtime block, `src/runtime_ambient.hpp` -- the thread's own, or the running pump's while one runs, R5 lane D2-C) | three source-layer RAII scopes (`PineStrategyHost` chart dispatch, `pine_security_eval.cpp`, `pine_aux_security.cpp`) raise it around one evaluation context under the opt-in `chart_ema_na_warmup` / `security_range_start_na_warmup` run flags; nothing in the kernel raises it | **retained as a generic ambient indicator option** (R5 lane P2). An EMA seeds from its first finite input or from the simple average of its first `length` inputs; both are textbook, and the kernel names them per instance (`EMA(length, EmaSeeding)`), which is a bare host's spelling and touches no global. The ambient default is what an instance that names no seeding latches on its first `compute()`: a per-thread default for a per-computation option, the shape of a floating-point rounding mode, and the only zero-wiring way to seed every instance of one evaluation context when the generated strategy constructs its own `ta::EMA` members (so relocating it into the source layer would take a codegen change). The adapter uses it the way any host may; the kernel's spelling and comments carry no TradingView vocabulary. The accessor's name is kept: `na` is the kernel's own NaN spelling and eight twin-parity-frozen CHECK texts of `test_chart_ema_na_warmup` spell it. **Ruled non-state (R5 lane F6), so no identity folds it.** Nothing that identifies a run reads the flag -- not the broker-state hash, not the continuation digest, not a per-bar record -- and outside the three scopes it is always the process default `false`, because each scope restores the previous value on exit, unwinding included: between two host calls, where a stream continues, there is no value to carry. Its one reader, `EMA::compute()`, copies it once into the instance's own `na_warmup_` (`warmup_latched_`), which is state of that indicator instance, owned by the script that constructed it exactly as the recursion's running value is, and which a continued stream keeps -- already latched. What selects the value is configuration, not state: the two run flags that raise it, `chart_ema_na_warmup_` and `security_range_start_na_warmup_`, are `PineStrategyHost` configuration, waived as such in `scripts/broker_state_hash_waivers.txt`; folding them into the Pine run identity would be the adapter's decision, and folding the latch itself would fold a constant. Pinned by the ambient-default cases of `tests/test_ta_na_source_rules.cpp` (G7, kernel-only) and by `test_chart_ema_na_warmup_l4d`. |
445446
| `skip_entry_bar_high` / `skip_entry_bar_low` — one physical lot's entry-bar excursion mask (`PyramidEntry`, `include/pineforge/engine.hpp`): the end of the lot's entry bar the modeled path had already reached before that lot's own opening fill, folded into the run hash (`src/engine_state_hash.cpp`) and handed back to the excursion owner on the closing row's `ClosedLotExcursionFacts` | **no host, since R5 lane E6.** The owner of the lot's excursion (RULING A48, `owns_lot_excursions`) declares where its fill sat — `declare_opened_lot_entry_bar_mask` with `OpenedLotFillPoint::OnPath` or `::AfterPath` — and the kernel derives both flags from the bar's own path, walked in the leg order the run declares (`NativeExecutionConsumer::path_high_first`, `first_touch_position`; the next row). A C host declares through `strategy_native_declare_opened_lot_entry_bar_mask_v1` (R5 lane E11), legal inside `on_applied` alone. The source adapter's two former writer sites in `PineStrategyHost::on_native_applied` are two calls; nothing outside the kernel assigns a lot's flags | **retained as the entry-side half of RULING A48** (R5 lane E6). It is generic under rule 2: what the declaration carries is where a fill sat on a bar, which any venue's host can answer, and the platform-specific half — which of ITS orders is a priced entry — stays in the adapter that knows it. It is not a knob under rule 2b: the leg order and the first-touch position are decisions the run has already made, in the matcher and in the closing row, and a host that wants the leg order stated says so once through `NativeRunSpec::path_order`, and since R5 lane E15 the seam derives the mask under exactly that declared order (until then it read the open-proximity rule whatever the run declared). Pinned by `tests/test_e6_entry_bar_mask_declaration.cpp` (kernel-only) and `tests/test_l10d_entry_bar_excursion_masks.cpp` (the adapter's rows). **Removable at the next epoch, and only then:** the two booleans are durable lot state folded into the run hash, inside a POD the settlement ABI freezes, so dropping them moves the hash stream and a layout. The mechanism that replaces them needs no kernel storage — the excursion owner already keys its own tables by `entry_incarnation`, so it can keep the mask beside them and pass it in the facts it receives — and the kernel's own second reader of the pair is gone: the fold behind `preceding_exit_path_prefix` had no writer anywhere in the tree, so R5 lane E10 deleted the branch and the member (`tests/test_e10_dead_path_prefix.cpp`). The pair is now read only where it is handed to the excursion owner. |
446447
| the leg order under which `declare_opened_lot_entry_bar_mask` derives a lot's entry-bar mask | nothing new: the run's `NativeRunSpec::path_order`, declared once before the run, by a C++ host in the spec, by a C host in the spec extension's feed-policy block, and by the Pine adapter from its embedder's `set_path_order` / `strategy_set_path_order` (`PineStrategyHost` projects it at begin) | **the order the matcher walks** (R5 lane E15, rule 2). The seam asks the consumer (`NativeExecutionConsumer::path_high_first`: the declared order, the open-proximity rule under `Auto`, the resolution `deliver_confirmed_script` walks) and finds the fill's first touch on that same walk. Until E15 it read `internal::bar_path_uses_high_first`, whose thread-local override only `NativePathOrderScope` installed (both deleted in R5 lane D2-A), around the intrabar sampler alone and never around a host callback, so every declared order got the open-proximity mask: the low-first bar O100 H110 L99 C105 with an `OnPath` fill at 105 gave (high, low) = (0, 1) under all three orders, where the HIGH_FIRST walk reaches 105 on its first leg and masks nothing. The ruling: the mask is derived from the same path order the matcher walks. The run already made that decision through `path_order`, so this is not a knob; it is the existing choice applied consistently. Consequence: a run under a forced order now gets different masks, and so different owner excursions. Codegen declares no order, and the adapter declares one only when its embedder calls `set_path_order` (in this repository only `scripts/run_strategy.py --path-order`, which `run_corpus.sh` never passes and no `runtime_overrides` key carries), so the corpus runs `Auto` and stays byte-identical by construction, and the wave-D population sweep judges any forced-order probe. Pinned by the forced-order rows of `tests/test_e6_entry_bar_mask_declaration.cpp` and of the entry-bar mask scenario of `tests/test_native_c_api.c`. |

‎docs/pages/native-engine.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -921,6 +921,22 @@ trigger alternative, and a retained best must still produce a representable
921921
level for the successor's offset; otherwise the replacement is rejected and
922922
the predecessor stays live.
923923
924+
Two more options change what a replacement consumes, never what it matches.
925+
`keep_handle` re-prices the request in place: the successor keeps the
926+
predecessor's handle, its place in the chain (no chain-root pair is folded
927+
again), its children and cohort members, and a trail's arm ordinal, and takes
928+
the number a plain successor would have taken as its priority -- queue ties
929+
still rank a re-priced request newest, and the next request is numbered as
930+
after a plain replace. `keep_binding` carries a close's book binding: at its
931+
next point the successor binds, with no `CloseBoundEvent`, to exactly the book
932+
close the event would have installed when the position has not moved (taking
933+
the timeline ordinal the event would have taken, so every later ordinal is the
934+
plain replace's), and binds as a plain successor does when it has. Either may
935+
be set alone; neither has a C spelling. The Pine adapter sets `keep_binding`
936+
on every re-issue: its placement table, bracket families and pending-order
937+
rows name each placement by the incarnation its command was issued, so it
938+
keeps plain handles.
939+
924940
What the Pine adapter takes from this set is the tick spelling and the
925941
anchored child. A source `trail_offset` is a tick count, so `exit()` hands the
926942
kernel a `TrailTicks` and the acceptance path resolves it against the run's

‎docs/pages/pine-to-native.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -202,7 +202,8 @@ reversal; and `PointBudget` native_order.hpp:353 caps how much of a request may
202202
fill at a single matching point, where Pine only ever uses the whole remaining
203203
quantity. Amending a live order is `replace` native_host.hpp:1185, which emits
204204
`ReplacedEvent` native_order.hpp:949 and can carry the predecessor's live
205-
trigger state forward through `ReplaceOptions` native_order.hpp:343. Its C
205+
trigger state forward through `ReplaceOptions` native_order.hpp:367 -- or keep
206+
its handle, or carry a close's book binding, from C++ only. Its C
206207
spelling is `strategy_native_replace_v1`, or `strategy_native_replace_ext_v1`
207208
when a rejection's `RequestRejectReason` native_order.hpp:773 matters.
208209

0 commit comments

Comments
 (0)