Skip to content

Commit 074f648

Browse files
luisleo526claude
andcommitted
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)
1 parent 0a46b45 commit 074f648

1 file changed

Lines changed: 34 additions & 0 deletions

File tree

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -517,6 +517,40 @@ calls (`Sized`, `ScopeFraction`, `native_open_lots()`, …). Their rulings live
517517
(design §4.1 E3 for `Sized`; the C header's COVERAGE block for the host surface), and the audit scoped
518518
this section to what a run *declares*.
519519

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+
520554
## TradingView-calibrated kernel mechanisms (rule 2's own account)
521555

522556
Rule 2's amended test asks two things of a kernel site whose comment names TradingView:

0 commit comments

Comments
 (0)