You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 074f648
Browse filesBrowse the repository at this point in the historyBrowse files
ADR-0001 records the C surface's routes and rulings (R5 lane F4, items 4 and 7)
A new `##` section, "The C surface: routes and rulings (R5 lane F4)",
beside the feature-gate rulings and outside the residual-vocabulary
tables (so neither gate reads it):
- The six generic hooks the Pine adapter uses without a C route (AUDIT3
§3.1 4) are all ROUTED, each row naming its C spelling and its witness:
first_match / scope, native_sized_units, the terms price half,
validate_execution_precommit, resolve_anchored_level,
hash_host_extension. None is left as "no POD yet".
- E12 finding 7, ruled: cancel_all / cancel_where answering a count --
retained (each withdrawn request is its own CancelledEvent in the
history); cohort_add / cohort_remove answering void -- retained, the
typed CohortReceipt (already folded into the continuation) named as a
follow-up that needs NativeStrategyHost::cohort_add_result first;
native_sized_units / native_liquidation_price answering optional --
retained (observation queries whose every empty is a documented,
host-checkable precondition).
- E13 finding 4, ruled: carried (the working row's relation tail).
- Restated or new C++-only rows with their reasons: hash_source_extension
(deprecated spelling), KernelRecordedAtHostMarks (E22), the
strategy_set_path_order clamp (a void ABI v4 setter), and the enumerated
int32 fields of pf_pending_order_v1_t (generator-owned: names belong in
scripts/gen_pending_order_mirror.py, never hand-written beside the
mirror).
Every anchor in the section names its symbol on this tree
(check_doc_anchors: 0 findings in the section). Ruling rows only; no code.
ADR-0001 rule 2: the section rules the C transport of generic kernel
capabilities; nothing TradingView-specific enters the kernel.
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
(cherry picked from commit e2f695832161ff2b41da1c5c097e705578b651f5)
Copy file name to clipboardExpand all lines: docs/adr/0001-kernel-adapter-boundary.md
+34Lines changed: 34 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -517,6 +517,40 @@ calls (`Sized`, `ScopeFraction`, `native_open_lots()`, …). Their rulings live
517
517
(design §4.1 E3 for `Sized`; the C header's COVERAGE block for the host surface), and the audit scoped
518
518
this section to what a run *declares*.
519
519
520
+
## The C surface: routes and rulings (R5 lane F4)
521
+
522
+
A C host drives the same kernel a C++ host does, so every generic capability a C++ host reaches owes a
523
+
C host either a route or a ruling that says why not — and "no size-prefixed POD yet" is a to-do, not a
524
+
ruling. The census of `NativeStrategyHost` is the COVERAGE block of `include/pineforge/native_c_api.h`,
525
+
held by `scripts/check_native_c_api_surface.py`, which since this lane also classifies every C
526
+
enumeration against its kernel twin value by value. This section records the lane's decisions on the
527
+
surfaces the third audit named (AUDIT3 §3.1 "What breaks G1" 4, findings E12 f7 and E13 f4). Every line
528
+
number names its symbol on this tree.
529
+
530
+
**The six generic hooks the Pine adapter uses: all routed.**
531
+
532
+
| C++ hook | C route | witness in `tests/test_native_c_api.c`|
533
+
|---|---|---|
534
+
|`WaitForApplied::first_match` / `WaitForApplied::scope`|`arm_first_match` (`native_c_api.h:2040`), `pf_native_request_v1`'s fifth published layout; a Book-scoped child may be the host-sized close `on_close_units` sizes | the arm-relation scenario |
535
+
|`native_sized_units`|`strategy_native_sized_units_v1` (`native_c_api.h:2822`), reading a SIZED request's own sizing block | the sizing-query scenario |
536
+
|`resolve_execution_terms`, price half |`on_execution_terms` (`native_c_api.h:2390`): price, opening shape, grid policy, beside the units half `on_close_units`| the terms-hook scenario |
537
+
|`validate_execution_precommit`|`on_precommit` (`native_c_api.h:2399`): the plan, the inspection and the projected account, the closed rows' P&L borrowed for the call | the precommit scenario |
538
+
|`resolve_anchored_level`|`on_anchored_level` (`native_c_api.h:2406`) | the anchored-level scenario |
539
+
|`hash_host_extension`|`on_hash_extension` (`native_c_api.h:2417`): a 64-bit digest folded after the kernel's own bytes | the hash-extension scenario |
540
+
541
+
**What stays as it is, and why.**
542
+
543
+
| surface | ruling | reason |
544
+
|---|---|---|
545
+
|`cancel_all` (`native_host.hpp:1203`) / `cancel_where` answer a count, not a `CancelResult` per request (E12 f7) |**retained**| A bulk cancel is many commands in one call, and each withdrawn request records its own `CancelledEvent` with its own `CancelReason` — dependants of a cancelled owner included — in the history a host already polls (`strategy_native_events_v1`). That is the per-request answer; the count is the call's summary. A result vector would restate the history in a second, allocating shape that C could not take without a caller-sized array. The C spellings answer the same count (`strategy_native_cancel_all_v1``native_c_api.h:2560`). |
546
+
|`cohort_add` (`native_host.hpp:1221`) / `cohort_remove` answer `void` (E12 f7) |**retained; the typed receipt is a named follow-up**| The kernel judges every enrolment into a `CohortReceipt` (Applied, InvalidHandle, UnknownOrigin, TerminalOrigin) and folds it into the continuation (`receipts``native_execution_consumer.cpp:769`), so a replay that diverges there diverges in the hash. Nothing that matches or settles reads it: a roster is a relation the close reads at its match, and a refused enrolment is a member the close does not take. A host that needs the receipt AT the call needs `NativeStrategyHost::cohort_add_result` first, a kernel-header change outside this lane; its C spelling would then be an `_ext_v1` with a receipt word. Until then `strategy_native_cohort_add_v1`'s `PF_NATIVE_OK` means the enrolment was issued. |
547
+
|`native_sized_units` (`native_host.hpp:1250`) / `native_liquidation_price` answer `std::optional<double>` (E12 f7) |**retained**| Observation queries, not commands: each empty is documented cause by cause in its own comment (unconfigured, non-positive money or denominator, a below-one-step quotient; no margin model, no maintenance fraction for the side, a flat book, no finite solution), and every cause is a fact the host can read itself. A typed reason would name what the caller already knows. C answers `PF_NATIVE_ABSENT` and NaN (`strategy_native_liquidation_price_v1``native_c_api.h:2797`). |
548
+
|`pf_native_working_v1` without the leg's anchor or owner relation (E13 f4) |**carried**| The C++ host reads them off `NativeWorkingRequest::definition`, so the C readout's relation tail carries them: `anchor` (`native_c_api.h:1556`) through `arm_scope`, the request as the kernel holds it now (an armed leg reads ABSOLUTE with its installed level). |
549
+
|`hash_source_extension` (`engine.hpp:401`) |**C++-only**| The deprecated spelling of `hash_host_extension`, kept so an existing C++ subclass compiles and folds unchanged. A C host has only ever had the current spelling, `on_hash_extension`. |
550
+
|`NativeReportPolicy::KernelRecordedAtHostMarks` (`native_run_spec.hpp:63`) |**C++-only** (lane E22's ruling, restated) | Under it the host names each report point from inside its own callbacks, and the C table has no call that marks one: a C host could only declare a series nobody records. `pf_native_report_policy_e` (`native_c_api.h:630`) leaves its value unnamed, and the enum guard holds that exclusion. |
551
+
|`strategy_set_path_order` (`pineforge.h:898`) clamps an out-of-range mode to AUTO |**retained**| A `void` ABI v4 setter cannot answer a refusal. Its values are now documented as `pf_native_path_order_e`'s (`native_c_api.h:838`); a C host that wants an unknown word refused declares `path_order` in `pf_native_run_spec_ext_v1`, which answers `PF_NATIVE_E_TAG`. |
552
+
| the enumerated `int32` fields of `pf_pending_order_v1_t` (`strategy_pending_order_get``pineforge.h:992`) |**no C names in the header; generator-owned**| The mirror is generated from the Pine source host's resting-order record by `scripts/gen_pending_order_mirror.py` (held by its `--check` source guard) and self-described at run time by `strategy_pending_order_layout`. Its enumerated fields are the source layer's order vocabulary, not a kernel enumeration. A C name for them belongs in that generator, which owns the struct, so that it cannot drift from the mirror — never hand-written beside it. |
553
+
520
554
## TradingView-calibrated kernel mechanisms (rule 2's own account)
521
555
522
556
Rule 2's amended test asks two things of a kernel site whose comment names TradingView:
0 commit comments