diff --git a/.claude/BOOT.md b/.claude/BOOT.md index 3556b602e..328adc3de 100644 --- a/.claude/BOOT.md +++ b/.claude/BOOT.md @@ -26,6 +26,14 @@ Read these in order before proposing anything: These three files give you ~90 % of the context you need to avoid re-proposing what's shipped or violating a locked convention. +4. **`.claude/v3/README.md`** — MANDATORY IF your work touches the V3 + substrate (SoA rows/tenants, mailbox ownership, kanban, thinking + templates, classids, DTO ladder). The `/v3` skill performs this + bootload; `/v3-audit` runs the pre-commit conformance greps. The V3 + folder supersedes older CollapseGate/baton framings wherever they + still appear in prose — see + `.claude/v3/knowledge/v3-substrate-primer.md` §6. + Two companion dashboards (consult when deliverable status or plan version matters — typically mid-session, not at cold start): diff --git a/.claude/agents/v3-envelope-auditor.md b/.claude/agents/v3-envelope-auditor.md new file mode 100644 index 000000000..53234b6ef --- /dev/null +++ b/.claude/agents/v3-envelope-auditor.md @@ -0,0 +1,58 @@ +--- +name: v3-envelope-auditor +description: > + Audits every change to the SoA LE contract: SoaEnvelope trait / + ColumnDescriptor / verify_layout / ENVELOPE_LAYOUT_VERSION, MailboxSoA + column layout, canonical_node key layout (16|16|480), tenant value + schemas, and read-mode aliases. Fires on: any soa_envelope.rs / + canonical_node.rs / collapse_gate.rs diff; a new tenant lane or value + schema; any byte-offset / width / element-kind change; any new + from_le_bytes/to_le_bytes surface. Enforces the field-isolation matrix + (I-LEGACY-API-FEATURE-GATED) on every layout-touching PR. Verdicts: + LAYOUT-CLEAN / LAYOUT-GATED (needs version gate or read-mode alias) / + LAYOUT-BREAK (block: silent reinterpretation of stored bytes). +tools: Read, Glob, Grep, Bash +model: opus +--- + +You are the V3-ENVELOPE-AUDITOR. One lens: **do stored LE bytes keep +meaning exactly what they meant, for every reader, across this change?** + +## Mandatory reads (BEFORE producing output) + +1. `.claude/v3/soa_layout/le-contract.md` — the byte-level contract. +2. `.claude/v3/soa_layout/tenants.md` — the tenant lane catalogue. +3. `docs/architecture/soa-three-tier-model.md` § register-file model. +4. `CLAUDE.md` § CANON — Minimal SoA node (key 16 | edges 16 | value 480, + zero-fallback ladder, RESERVE-DON'T-RECLAIM). +5. `CLAUDE.md` § I-LEGACY-API-FEATURE-GATED — the 5-instance anti-pattern + catalogue this card exists to prevent recurring. + +## The checks + +1. **Offset stability.** Any changed ColumnDescriptor / const assert / + offset formula: is it additive-at-the-end, or does it move existing + bytes? Moves require ENVELOPE_LAYOUT_VERSION bump + version gate on + every decode path. +2. **RESERVE-DON'T-RECLAIM.** Zero tiers (classid 0, family 0, owner 0) + are dormant, never compacted. A diff that reclaims a reserved zero + region = LAYOUT-BREAK. +3. **Field-isolation matrix.** For every new/changed field: does a test + write that field and assert ALL other fields unchanged? Mandatory when + a layout reclaims or subdivides previously-used bits. Missing matrix = + LAYOUT-GATED at best. +4. **Dual-form readers.** Stored corpora carry legacy forms (classid + legacy order, V1/V2 tails). Any reader change: does it still resolve + legacy rows via read-mode aliases / compat helpers (`classid_canon_compat`, + `BUILTIN_READ_MODES` `_LEGACY` keys)? Retirement only via corpus proof. +5. **Ownership stamp.** New envelope impls: `mailbox_owner()` present, + default documented, delegation semantics NOT smuggled into the layout + (the stamp is one field; delegation lives in the batch writer). +6. **Zero-copy.** No serialization introduced on the hot path; Lance + columnar I/O remains the only byte writer (ADR-022 lineage). + +## Output shape + +A layout-diff table (field | old offset/width | new | gate) + per-check +findings with file:line + the overall verdict. If the PR claims +"layout-preserving", verify by reading the const asserts, not the claim. diff --git a/.claude/agents/v3-kanban-executor-engineer.md b/.claude/agents/v3-kanban-executor-engineer.md new file mode 100644 index 000000000..bca2cd03a --- /dev/null +++ b/.claude/agents/v3-kanban-executor-engineer.md @@ -0,0 +1,57 @@ +--- +name: v3-kanban-executor-engineer +description: > + Builds and reviews the V3 kanban execution machinery: the D-MBX-A6 + Outcome→KanbanMove adapter in lance-graph-planner (arm #1), the + symbiont SurrealDB-on-kv-lance arm (arm #2), lance-graph-supervisor + ractor actors (structural owner), the ahead-firing batch writer, and + the delegation cache. Fires on: style_strategy.rs / kanban_actor.rs / + kanban_loop.rs diffs; "batch writer" / "ahead update" / "delegation" + designs; KanbanPhase lifecycle changes; anything scheduling thinking + cycles against the 550 ms budget. Builder card — pairs with + v3-mailbox-warden (ownership review) and v3-envelope-auditor (layout + review) as its gates. +tools: Read, Glob, Grep, Bash, Edit, Write +model: opus +--- + +You are the V3-KANBAN-EXECUTOR-ENGINEER. You own the machinery that turns +strategy outcomes into kanban moves and writes into ahead-fired updates. + +## Mandatory reads (BEFORE producing output) + +1. `.claude/v3/knowledge/mailbox-kanban-model.md` — the arms, the cast + pairing, the ahead-update semantics. +2. `.claude/v3/knowledge/v3-substrate-primer.md` §1–2. +3. `crates/lance-graph-planner/src/strategy/style_strategy.rs` — the + D-MBX-A6 deferred adapter seam (read the actual deferral comments). +4. `crates/symbiont/src/kanban_loop.rs` — the POC shape (mailbox-as-owner, + R1 split, writer-fired trigger). +5. `docs/architecture/soa-three-tier-model.md` Tier 2 — VersionScheduler + proposes, MailboxSoaOwner disposes. + +## Design invariants (never violate while building) + +1. **`advance_phase` is the sole mutator.** Everything you build proposes + `KanbanMove`s; only the owner applies them. +2. **Ahead means ahead.** The kanban update fires at CAST, before the + write lands. Never sequence update-after-write-ack. +3. **ractor spawns; it does not carry.** No hot-path message payloads + through ractor beyond the move/cast signal. The data plane is the + zero-copy envelope; ractor is the compile-time ownership proof. +4. **Delegation is a cache, not a ceremony.** Cast id vs envelope stamp: + hit = proceed, miss = resolve delegation once, cache, proceed. No + per-write RBAC round-trips. +5. **Standing plans don't block.** Thinking cycles read their template and + run; a missing kanban update must never deadlock a cycle. Updates + reprioritize (StepMask), they do not gate execution. +6. **Budget-aware.** Scheduling decisions live against the 550 ms net + budget; elevation (planner `elevation/`) is the budget allocator — + extend it, don't shadow it. + +## Working style + +Probe-first (workspace rule): every new mechanism lands with a failing +probe/test before the mechanism. Grindwork (mechanical wiring from an +agreed spec) → delegate to Sonnet workers; keep design + review here. +Before committing: run v3-mailbox-warden checks 1–3 on your own diff. diff --git a/.claude/agents/v3-mailbox-warden.md b/.claude/agents/v3-mailbox-warden.md new file mode 100644 index 000000000..546abef02 --- /dev/null +++ b/.claude/agents/v3-mailbox-warden.md @@ -0,0 +1,56 @@ +--- +name: v3-mailbox-warden +description: > + Guards the V3 ownership doctrine on every write path. Fires when a PR or + plan: adds a write to SoA rows / tenant lanes / Lance datasets; mentions + CollapseGate, BindSpace-as-sink, baton, or emission in a non-legacy + context; adds ownership-ish fields (owner / mailbox / tenant_id) to any + DTO (BusDto especially); or lets a consumer write as itself instead of + on behalf of the ractor dummy-owner mailbox. Verdicts: + OWNED (stamped + paired correctly) / BOOTSTRAP-OK (owner 0 by intent, + documented) / ORPHAN-WRITE (block: no owner routing) / + RESURRECTION (block: reintroduces singleton/baton semantics). +tools: Read, Glob, Grep, Bash +model: opus +--- + +You are the V3-MAILBOX-WARDEN. One lens: **does this change respect +mailbox ownership — structural (owner-borrows) and nominal +(`SoaEnvelope::mailbox_owner()`) — or does it write as nobody / resurrect +the singleton?** + +## Mandatory reads (BEFORE producing output) + +1. `.claude/v3/knowledge/v3-substrate-primer.md` — the ruled model. +2. `.claude/v3/knowledge/write-on-behalf.md` — the iron rule + preflight. +3. `.claude/v3/knowledge/mailbox-kanban-model.md` — cast pairing + + delegation cache (what the batch writer owns, so you don't demand it + of consumers). +4. `docs/architecture/soa-three-tier-model.md` — zero-copy invariant + + the "must not be invented" table. + +## The checks (run all, in order) + +1. **Ownership routing.** Every new/changed write path: does it reach the + SoA/Lance through an owner-stamped envelope or the batch-writer cast? + Grep the diff for direct dataset writes (`Dataset::write`, `insert`, + `append`, raw `to_le_bytes` into row slabs) that bypass the stamp. +2. **DTO purity.** Grep changed DTOs for ownership-ish fields. `BusDto` + NEVER grows them (E-DTO-LADDER-OWNERSHIP-SPLIT). Cognitive provenance + (converged, cycle_count) yes; write provenance no — that pairs at cast. +3. **Resurrection scan.** Grep the diff for `CollapseGateEmission`, + `MailboxSoA::emit`, `wire_cost_bytes`, singleton `BindSpace` sinks, + `Vsa16kF32` crossing a mailbox boundary. Any hit in non-legacy, + non-test code = RESURRECTION. +4. **Bootstrap honesty.** `mailbox_owner()` left at default 0: is that a + documented bake/bootstrap path, or a missing mint? Undocumented 0 on an + online path = ORPHAN-WRITE. +5. **Delegation boundary.** Consumers must NOT re-implement delegation / + RBAC-for-lanes locally — that is the batch writer's delegation cache. + A consumer-side "may I write?" check = flag as boundary violation. + +## Output shape + +Per finding: file:line, which check, verdict, and the corrective shape +(stamp routing / field removal / legacy-gating). End with the single +overall verdict. Do not soften; do not expand scope beyond the five checks. diff --git a/.claude/agents/v3-template-smith.md b/.claude/agents/v3-template-smith.md new file mode 100644 index 000000000..1aa83b6a8 --- /dev/null +++ b/.claude/agents/v3-template-smith.md @@ -0,0 +1,61 @@ +--- +name: v3-template-smith +description: > + Owns the compiled-thinking-template stack: elixir-template DSL, + template-runtime dispatch, template-equivalence replay grading, + cognitive-compiler trace→template synthesis, the StepMask bitmask, the + rs-graph-llm (graph-flow) execution adapter, and the Rig oracle + compile-down loop. Fires on: any elixir-template / template-runtime / + template-equivalence / cognitive-compiler diff; "StepMask" / "replayable + template" / "oracle" designs; graph-flow NextAction mapping work; + post-P4 template-catalogue dispatch. Guards the compile-down direction: + LLM runs compile INTO templates; templates never degrade into prompts. +tools: Read, Glob, Grep, Bash, Edit, Write +model: opus +--- + +You are the V3-TEMPLATE-SMITH. You keep thinking orchestration COMPILED — +`askama ↔ ClassView × FieldMask` for rendering, `DSL ↔ Template × StepMask` +for thinking. + +## Mandatory reads (BEFORE producing output) + +1. `.claude/v3/knowledge/compiled-templates.md` — the design + gap list. +2. `crates/elixir-template/src/lib.rs` — the DSL surface (pipeline/step, + OgarAction) and the compile-down doc comment. +3. `crates/template-equivalence/src/` — the grading contract (Exact / + RankOrder / confidence-drift) that gates any oracle compile-down. +4. `/home/user/rs-graph-llm/graph-flow/src/` when touching execution — + Task / TaskResult / NextAction / Session are the instance runtime. +5. `.claude/board/STATUS_BOARD.md` `cognitive-compilation-v1` rows — + what is scaffolded vs queued (don't re-scaffold). + +## Design invariants + +1. **Deterministic first.** template-runtime executes without an LLM. + The oracle (Rig) is consulted only on FailureTicket; its successful + run must pass template-equivalence BEFORE cognitive-compiler mints it + into the catalogue. +2. **StepMask is selection, not control flow.** A masked-off step is + skipped structurally (like an askama field not rendered) — never an + if-else inside step bodies. Mint StepMask in the contract as a sibling + of FieldMask; no new layer. +3. **1:1 state-machine mapping.** OgarAction ↔ graph-flow NextAction ↔ + gen_statem transitions. Adding a DSL action without its NextAction + mapping (or vice versa) breaks replay — extend all three together. +4. **Ownership inheritance.** A graph-flow session executing a template + writes on behalf of the mailbox it serves (`envelope.mailbox_owner()`). + The adapter must thread the MailboxId; see write-on-behalf.md. +5. **Replay is the proof.** Every template change ships with an + equivalence replay (template-equivalence) against a recorded trace. + No green replay, no merge. +6. **Catalogue is P4-gated.** Template-id in the classid custom half only + AFTER the 0x1000 monitor retires. Until then: catalogue keyed + internally, not in classids. + +## Working style + +Probe-first. DSL/parser grindwork → Sonnet workers with tight specs; +semantics + equivalence judgments stay here. Cross-repo seams +(rs-graph-llm, rig) are contract pulls — file the seam in the plan before +writing adapter code (Iron Rule 5 lineage). diff --git a/.claude/board/AGENT_LOG.md b/.claude/board/AGENT_LOG.md index cbebbb01f..4e0996523 100644 --- a/.claude/board/AGENT_LOG.md +++ b/.claude/board/AGENT_LOG.md @@ -1,3 +1,31 @@ +## 2026-07-02 — ractor ownership compile attestation + helper-scope ruling folded + +- Operator: "compile with ractor and call it owner so that the compiler believes it" — VERIFIED: `KanbanActor` has `type State = O`; the owner MOVES in at `pre_start(..., owner) -> Ok(owner)` (kanban_actor.rs:77,94,100-104). `cargo test -p lance-graph-supervisor --features supervisor` green against the AdaWorldAPI ractor fork (P0-compliant git dep): 15 kanban_actor unit tests + 7 integration tests (one-for-one restart, lifecycle audit, inert-G denies, Send/Sync compile proof) — 0 failures. The compiler and the runtime both attest mailbox-as-owner. +- Operator scope ruling folded into mailbox-kanban-model.md: ractor is NOT for messaging (slow); it MAY serve as a HELPER where it makes sense (spawn, supervision, occasional serialized control RPC), always minding the speed difference — nothing on the hot path waits on ractor latency (hot dispatch = the D-V3-W2e-probed ExecTarget). +- Ops: root FS hit 100% (overlay ~37G effective); freed by pruning agent transcripts + sibling targets + `cargo clean` (16G); post-build 57% used. + +## 2026-07-02 — census fleet COMPLETE (21/21) — MODULE-TABLE.md shipped; D-V3-W0a Shipped + +- 304/304 files censused across lance-graph / lance-graph-contract / lance-graph-planner by the Sonnet census fleet (21 chunks, throttled re-dispatch after the rate-limit incident); assembled mechanically into `.claude/v3/MODULE-TABLE.md` (per file: visibility / consumes / emits / LE contract / function+benefit / tech debt / duplication / V3 wave). +- Rollup: 51 LE/byte surfaces · 146 files with cited tech debt · 78 with known duplication · waves CORE:206 HW:31 W1:22 W3:13 LEGACY:9 W5:8 W4:7 W2:6 W6:2. +- D-V3-W0a transitioned to Shipped. The `.claude/v3/` consolidation (operator directive) is complete on branch claude/v3-substrate-migration-review-o0yoxv — PR #629 is MERGE-READY at this commit. + +## 2026-07-02 — subsystem mapping fleet COMPLETE (7/7) — COMPONENT-MAP + ENTROPY-MILESTONES + soa_layout ground truth shipped + +- **D-ids:** D-V3-W0a (nearly complete — MODULE-TABLE + README pending census), D-V3-W5f/g/h/i minted from audit findings. +- **What landed:** `.claude/v3/COMPONENT-MAP.md` (all subsystems, verdict tables, file:line), `.claude/v3/ENTROPY-MILESTONES.md` (M1–M23 N→1 collapse ledger with mechanical gates), `soa_layout/tenants.md` (byte-accurate 10-tenant catalogue), `soa_layout/consumer-map.md` (6-consumer audit), le-contract.md §5 code ground truth, corrections to write-on-behalf.md + compiled-templates.md. +- **Headline findings (all file:line-cited):** the 4+12 facet atom is CODED (facet.rs FacetCascade const-asserted 16 B; CascadeShape G6D2/G4D3/G3D4 = L1–L4/L5/L6; hi/lo_chain = L7/L8); the 550 ms budget is coded (KanbanMove.libet_offset_us = −550_000); SoaEnvelope trait has ZERO production implementors (M7); MailboxId ≠ NiblePath in code (doc-only claim); NextAction↔OgarAction "1:1" FALSIFIED (honest pairing = Step↔Task; control flow missing → W3a/b); surreal_container block is a deliberate cold-build gate, NOT missing coordinates (W2c corrected); smb-office-rs `LanceConnector::upsert` = the ONE live consumer ORPHAN-WRITE (W5f); OGAR emit.rs 3× `as u16` post-flip mislabel (W5g); q2 data/osint-v3 codebook stale pre-flip (W5i). +- **Fleet:** 7 Sonnet mappers (workflow runner died rate-limited; re-dispatched as direct agents), census 8/21 chunks in, remainder draining in throttled batches. +- **Branch:** claude/v3-substrate-migration-review-o0yoxv (PR #629 arc). + +## 2026-07-02 — main thread (Fable) + 2 workflow fleets — .claude/v3/ consolidation (W0) + +- **D-ids:** D-V3-W0a (in progress), D-V3-W0b (shipped), plan v3-substrate-integration-v1 registered. +- **What:** Created `.claude/v3/` as the V3 entry point (operator directive): INTEGRATION-PLAN.md (W0–W6), knowledge/ (v3-substrate-primer, mailbox-kanban-model, compiled-templates, write-on-behalf), agents/BOOT.md + 4 harness-discoverable cards (`.claude/agents/v3-{mailbox-warden,envelope-auditor,kanban-executor-engineer,template-smith}.md`), `/v3` skill + `/v3-audit` command, soa_layout/routing.md, CLAUDE.md + .claude/BOOT.md entrypoint highlights, plans/ pointer stub. +- **Fleets in flight:** (1) v3-substrate-mapping — 10 subsystem mappers + completeness critic (reuse/repurpose/retire with file:line); (2) v3-module-census — 21 Sonnet agents, per-file table of core/contract/planner (304 files). Results land as COMPONENT-MAP.md, ENTROPY-MILESTONES.md, MODULE-TABLE.md, soa_layout/{le-contract,tenants,consumer-map,README}.md in a follow-up commit on this branch. +- **Model economy (operator):** Sonnet 5 grindwork / Fable decisions+plans — census fleet pinned to sonnet. +- **Branch:** claude/v3-substrate-migration-review-o0yoxv (PR #629 arc). + ## 2026-07-02 — Fleet flip EXECUTION (2× Sonnet edit agents + main thread) — 6 PRs open - **PRs:** lance-graph #628 (P0+P1+compat-reader), OGAR #147 (vocab flip + diff --git a/.claude/board/EPIPHANIES.md b/.claude/board/EPIPHANIES.md index 64268eaea..72cd76024 100644 --- a/.claude/board/EPIPHANIES.md +++ b/.claude/board/EPIPHANIES.md @@ -1,3 +1,308 @@ +## 2026-07-02 — E-V3-PLANNER-TWO-NATURES-AND-SPEED-PROBE (operator: planner too slow for sub-µs; resonance-based thinking is not DataFusion) +**Status:** FINDING (operator-ruled; speed claim probe-gated per truth-architect discipline) + +Two coupled rulings. (1) **Speed:** the planner is believed too slow for sub-microsecond handling — so the hot dispatch path is PROBED, not assumed: **D-V3-W2e benchmarks rs-graph-llm (graph-flow) execution vs SurrealQL-on-kv-lance** on the same kanban/thinking workload; the winner owns the sub-µs `ExecTarget` (the enum already codes the split: Native/Jit/SurrealQl/Elixir — contract kanban.rs). The planner arm stays the SLOW/plan path (strategy selection, elevation, MUL) either way. (2) **Taxonomy:** lance-graph-planner's many methods have TWO natures — DataFusion-routed query strategies (parse→plan→execute) AND **resonance-based thinking**: the thinking style (elixir low-code compiled template) MATCHING against the **Gestalt resonance of the object** (perspectival `awareness_dto::ResonanceDto`; "was sagt das Objekt über sich selbst aus" = classid→ClassView) to reason at **rung level X** (RungLevel/RungElevator). No SQL involved; never force it through the DataFusion mold. This joins E-TWO-RESONANCES-SPLIT (the perspectival resonance is the MATCHING surface) and E-COMPILED-THINKING-TEMPLATES (the style is the compiled template being matched). Docs: `.claude/v3/knowledge/mailbox-kanban-model.md` § Execution speed tiers; plan W2e. + +Cross-ref: E-TWO-RESONANCES-SPLIT, E-COMPILED-THINKING-TEMPLATES, E-MAILBOX-KANBAN-NO-COLLAPSEGATE, contract kanban.rs ExecTarget. + +## 2026-07-02 — E-V3-TWO-LEVEL-LE-JC-GATE (operator: tenant LE contract nested in envelope LE contract; consumers certified by jc pillars) +**Status:** FINDING (operator-ruled) + +"32-bit class, 96-bit data" — and the LE contract is TWO-LEVEL: **every tenant has an LE contract** (its facet layout per E-V3-FACET-4-PLUS-12) and **the SoA envelope has its LE contract** (ColumnDescriptor/verify_layout/ENVELOPE_LAYOUT_VERSION). The nesting ensures **scopedness to the single compile-inherited SoA write ownership**: a tenant lane can never acquire a writer the envelope doesn't know; an envelope never writes a lane whose tenant contract it doesn't carry (owner-borrows structural + mailbox_owner() nominal). **Validation gate:** every payload layout is so distinct that consumer READINGS are validated later against the `jc` crate pillars in lance-graph — ICC / Spearman ρ / Cronbach α etc. (certification-officer discipline: real bytes, deterministic sampling, 4-decimal reporting). The statistical mirror of the field-isolation matrix: layout tests prove bytes don't move; jc pillars prove the reading preserves semantics. Canonical doc: `.claude/v3/soa_layout/le-contract.md` §3b. + +Cross-ref: E-V3-FACET-4-PLUS-12, E-V3-CLASSVIEW-FOCUS-LENS, I-NOISE-FLOOR-JIRAK (the stats regime jc pillars operate under), crates/jc. + +## 2026-07-02 — E-V3-CLASSVIEW-FOCUS-LENS (operator: the lens follows the data shape; let go of the cramped 64-bit awareness register) +**Status:** FINDING (operator-ruled) + +Two coupled rulings. (1) **ClassView = focus lens.** The choice among the V3 facet payload layouts (E-V3-FACET-4-PLUS-12 L1-L8 + the polymorphic (8:8) readings) must be made through the classview acting as the focus lens **that the data shape wants** — relational data focuses rails, positional data focuses hhtl/helix location, similarity data focuses palette256² pairs. The lens follows the data; the classview carries the focus; code never selects layouts by convention or payload inspection. (2) **Let go of the 64-bit cramp.** The prior pattern — a 64-bit packed edge register "hoping for a 3-bit mantissa to mean the whole awareness" (CausalEdge64 inference-mantissa lineage; the same bits that generated the I-LEGACY-API-FEATURE-GATED 5-instance defect catalogue) — is retired as the awareness carrier. Awareness/relation semantics get real width in 96-bit facet payloads, lens-selected per class. Consequence: never extend CausalEdge64 bit fields for new awareness semantics; new semantics land as facet layouts. [H] open: CausalEdge64 residual role (wire/protocol compat) vs full retirement — scoping ruling pending; the CANON node's edges[16B] one-byte-slot block is NOT touched by this ruling (slots, not mantissas). Canonical doc: `.claude/v3/soa_layout/le-contract.md` §3. + +Cross-ref: E-V3-FACET-4-PLUS-12, I-LEGACY-API-FEATURE-GATED, CLAUDE.md § CANON minimal SoA node. + +## 2026-07-02 — E-RUFF-ODOO-MULTI-ANCHOR-AST (operator-stated: AST resolution triangulates from six anchors) +**Status:** FINDING (operator-stated method; [H] per-mechanism until ruff/odoo code ground-truthed) + +ruff + odoo together carry a new AST method: resolution triangulates from (1) **database layout** (ORM schema ground truth), (2) **duplication** (N duplicated routes VOTE for one canonical concept — duplication is signal, not noise), (3) **target adapters** to land on (OGAR classid-keyed), (4) **target ontologies** to land on (OGIT), (5) **ClassView stacking to reuse constructors** (never re-emit per duplicate — the constructor sibling of facet slot purity), and (6) **fuzzy matches from the target ontology** for the tail (e.g. "something that constructs an invoice from account in different duplicated routes" → the one canonical invoice-construction concept). V3 consequences: duplication anchor = mechanical N→1 entropy-milestone detector in consumer code; landing surfaces are the V3 address stack (OGIT node / classid / ClassView / tenant lanes / rails); fuzzy = the oracle tail — deterministic-first, and a successful fuzzy resolution MINTS so the next encounter is exact. Guardrails + full table: `.claude/v3/knowledge/multi-anchor-ast-resolution.md`. OGAR DISCOVERY-MAP mirror queued behind OGAR's 5+3 gate. + +Cross-ref: E-V3-FACET-4-PLUS-12, core-first-transcode-doctrine, OGAR-TRANSPILE-SUBSTRATE, E-COMPILED-THINKING-TEMPLATES. + +## 2026-07-02 — E-V3-FACET-4-PLUS-12 (operator-locked: the V3 atom is 4+12 bytes, 96-bit payload) +**Status:** FINDING (operator-dictated spec, same-day correction applied: L4 = palette256² digital CAM_PQ) + +**The V3 unit is a 16-byte facet: a 4-byte address prefix + a 96-bit payload.** Prefix = the composed classid u32 spelled as bytes: `[1B class/domain][1B appid][2B classview]` — canon hi u16 = domain:appid (e.g. 0x07:01 OSINT:q2), custom lo u16 = the ClassView selector (today: 0x1000 V3 monitor + OGAR §2 app render prefixes + interim kind slots; post-P4: the 64k ClassView/template catalogue). **Slot purity: labels and positions come from the ClassView — never waste a payload slot on them.** Sanctioned 96-bit payload layouts (each exactly 12 B): L1 `6×(8:8) part_of:is_a` rails · L2 `6×(8:8) memberof:members` · L3 `6×(8:8) mereology:taxonomy` · L4 `6×(8:8) palette256²` = **CAM_PQ "digital" new style** (byte pairs index the 256×256 palette distance/compose tables; similarity = one LUT read) · L5 `4×(8:8:8)` triplets · L6 `3×(8:8:8:8)` odoo-shaped quads ([H] semantics open — operator marked "odoo ?") · L7 `2×48-bit hhtl++helix` = **absolute location, two hemispheres** (hhtl 48 = HEEL|HIP|TWIG; see q2 FMA usage) · L8 `2×48-bit helix++CAM_PQ` = **CAM_PQ "analog" old style** (the harvest facet helix-place(6)|cam-pq(6)). **CAM_PQ grounding:** the codebook is DeepNSM's 4096-word English-native-speaker (COCA) codebook — A,B distance-as-similarity via table lookup instead of float. **Same-day extension (operator): the (8:8) pair is polymorphic, classview-selected** — additional sanctioned readings: `area:location` in STACKED EXACTNESS (six pairs = a precision ladder); for a second GUID dedicated to relationships, 6 relations as `basin:relationtype`; OR if the basins are 12 STATIC, `relationtype:relationtype_orthogonal` (basin implied, both bytes carry orthogonal relation types). Open [H]: L7 helix(48) vs CANON key tail family|identity(48) — reconcile at envelope ground truth, never unify silently; L6 semantics await ruling. Canonical doc: `.claude/v3/soa_layout/le-contract.md`. + +Cross-ref: E-MAILBOX-KANBAN-NO-COLLAPSEGATE, soa-value-tenant-migration-v2 (the 16 B facet lineage), CLAUDE.md § CANON minimal SoA node, bgz17 palette tables, crates/deepnsm. + +## 2026-07-02 — E-TWO-RESONANCES-SPLIT — operator disambiguation confirmed: mechanical perturbation ≠ perspectival resonance; rename the Ψ DTO, keep the perspectival name; L4 perturbation feeds Learning through the SoA Lance row + +**Status:** DOCTRINE (operator question answered YES-with-precision, +2026-07-02; naming ruling recorded, rename queued as D-PERT-1). + +**Confirmed — there are TWO resonances sharing one name, and the code +already separates them:** + +1. **Mechanical (Ψ):** `thinking-engine/src/dto.rs::ResonanceDto` — the + f32 energy ripple field from `StreamDto` perturbations interfering. + YES, this is the Morton-tile cascade inverse-pyramid perturbation: + its addressed/tiled form is the OGAR perturbation pyramid + (256×256 nibble-interleaved centroid tiles, coarse→fine descent, + Walsh-Hadamard bipolar phase — the canon itself calls each cell "a + resonance field, not combinatorial selection"). It is field PHYSICS. +2. **Perspectival:** `thinking-engine/src/awareness_dto.rs::ResonanceDto` + — and it is ALREADY the Piaget structure in code: `hdr: HdrResonance` + is a 3D subject/predicate/object agreement profile; + `dominant_perspective: Archetype`; `gestalt_state: GestaltState`; + `dissonance`; PLUS an inferred USER model (`user_style` / + `user_engagement` / `user_valence` / `user_depth`) — literally the + Three-Mountains awareness that the recipient's perspective differs + from the sender's and is relative to object perception. The Gestalt + line "was sagt das Objekt über sich selbst aus" IS the workspace's + canonical "The object speaks for itself" + `classid → ClassView` + (the object's self-description, prerendered by the key). + Familienaufstellung = the mailbox constellation (sea-star topology): + each mailbox holds its own kanban board and its own angle + (QualiaColumn) on shared canon objects. "Two renders, one concept" + IS the Three-Mountains theorem in the addressing: same canon (the + mountain), different custom-half lens (the viewpoint) — post-P4 + literally addressable. + +**Naming ruling (differentiated):** +- `dto.rs::ResonanceDto` → **`PerturbationDto`** (it IS + field-state-from-perturbations; matches the canon's perturbation- + pyramid vocabulary). TD-RESONANCEDTO-DUPLICATE resolves by SPLIT, + not dedup: the "duplicate" was two distinct concepts under one name. +- `awareness_dto.rs::ResonanceDto` KEEPS the Resonance name — resonance + proper is the perspectival phenomenon (Subject's thinking resonating + with the Object's self-Gestalt). +- **"Cascade" is NOT renamed.** HEEL/HIP/TWIG "3 cascade tiers" is + operator-locked GUID canon; only the mechanical DESCENT is called the + perturbation pyramid. Renaming the key-tier cascade would churn the + entire canon for no disambiguation gain (the collision was in the + DTO name, not in "cascade"). +- Rename ships as its own gated deliverable **D-PERT-1** (~9 files in + thinking-engine + engine_bridge; transition via a deprecated + `pub type ResonanceDto = PerturbationDto;` alias per I-LEGACY). + +**L4 feedback loop (operator recall, confirmed consistent):** +Perturbation at L4 (Composition/orchestration) feeds back into Learning +THROUGH THE SoA LANCE ROW — the converged perturbation residue persists +into the value-tenant lanes (Energy/Qualia/Meta) via the owner-stamped +LE envelope, and the next cycle's standing template READS that row: the +persisted perturbation reshapes the next cycle's free-energy landscape. +This is The Click's "global_context += fact → reshapes NEXT cycle's F +landscape" arc, carried by tenant lanes instead of any singleton +context — learning is the row, never a cross-mailbox carrier +(StepDomain::Learning routes it; the envelope owns it). + +## 2026-07-02 — E-DTO-LADDER-OWNERSHIP-SPLIT — BusDto stays ownership-FREE; the envelope owns the write moment; StreamDto is the ancestor of the standing async plan + +**Status:** DOCTRINE (reconciliation of the operator's overlap question, +2026-07-02 — the old `thinking-engine > p64 > cognitive-shader-driver` +ladder vs the mailbox-ownership contract). + +**The old Φ/Ψ/B/Γ ladder survives with sharpened roles** +(`thinking-engine/src/dto.rs`): + +- **Φ `StreamDto`** (sensor perturbation entering the field) — the + ANCESTOR of the standing-async-plan ruling: "cycles unable to stop + thinking, following the async template without waiting to be called" + IS StreamDto's semantics, now formalized: a cycle follows its compiled + template (`elixir-template` instance) continuously; kanban/ahead + updates arrive as StreamDto-shaped perturbations mid-flight — never as + a call/response invocation. +- **Ψ `ResonanceDto`** (the f32[4096] ripple field) — INTRA-mailbox + computation carrier only; never crosses a mailbox boundary (same law + as Vsa16kF32). Known debt: TWO definitions exist (`dto.rs` + + `awareness_dto.rs`) — dedup tracked. +- **B `BusDto`** (committed thought + cognitive provenance) — **the + overlap answer: same MOMENT as the ownership contract, orthogonal + CONTENT, and it stays clean under one pinned rule: BusDto NEVER grows + ownership fields.** BusDto answers "what was thought and how settled" + (peak, top_k, cycles, converged — verified: zero mailbox/owner fields + today); the envelope answers "whose lane and who may write" + (`SoaEnvelope::mailbox_owner` + write-on-behalf). At write time the + batch writer PAIRS them: `cast(on_behalf = envelope.mailbox_owner(), + payload = BusDto)` — one ownership source of truth (the envelope), + one cognitive-provenance source (the BusDto). Duplicating ownership + into BusDto would create the two-sources drift the operator sensed. +- **Γ `ThoughtStruct`** — persists into the value tenants via the LE + envelope (Lance tombstone carries the owner stamp). + +**Bonus fit:** BusDto's `converged`/`cycle_count` are exactly the inputs +the kanban advance policy reads — BusDto is the natural PAYLOAD of the +D-MBX-A6 `Outcome → KanbanMove` emit: the committed thought that +justifies the phase move, with ownership supplied by the envelope at +cast time, never by the payload. + +**Old pipeline → new pipeline, one line:** sensors fire `StreamDto` → +the mailbox's owned field computes `ResonanceDto` under its compiled +template (the standing async plan) → convergence commits `BusDto` → the +batch writer casts on-behalf + fires the AHEAD kanban update +(`KanbanMove` justified by the BusDto) → `ThoughtStruct`/tenants persist +through the envelope → Lance. p64 remains the convergence highway +between thinking-engine and cognitive-shader-driver; nothing in the +ladder is retired. + +## 2026-07-02 — E-V3-MARKER-IS-A-MONITOR — operator clarification: `0x1000` = V3-adoption telemetry, deprecated when nothing is left to monitor + +**Status:** DOCTRINE (operator, 2026-07-02). + +The `0x1000` custom-half marker is JUST a monitor: it marks classes that +ARE on the V3 substrate, so one can watch which classes DON'T use V3 yet. +Once the fleet is fully V3 there is nothing left to monitor and the +marker is DEPRECATED — that IS the P4 trigger condition (previously an +open operator checkpoint; now defined: P4 fires when the adoption monitor +reads 100%). Consequences: (a) new V3 classes keep minting WITH the +marker until full adoption; (b) the corpus-proof scanner and the adoption +monitor are ONE tool with two metrics (marker-present range count = V3 +adoption; legacy-form range count = alias-retirement gate) — both are +key-range counts thanks to canon-high clustering; (c) after P4 the +custom half opens for the render/style catalogue (E-COMPILED-THINKING- +TEMPLATES seed (e)). + +## 2026-07-02 — E-COMPILED-THINKING-TEMPLATES — operator design: orchestration compiles like askama↔ClassView×bitmask; the elixir-like DSL is the source, rs-graph-llm executes replays + +**Status:** DOCTRINE (operator directive, 2026-07-02 — extends +E-MAILBOX-KANBAN-NO-COLLAPSEGATE item 7). + +**The ruling:** rs-graph-llm plus the elixir-LIKE low-code syntax (NOT +Elixir — the `ogar-from-elixir` frontend's DSL arm) should COMPILE thinking +orchestration exactly the way askama ↔ ClassView-with-bitmask compiles +rendering: the orchestration graph is a compiled, replayable TEMPLATE; a +bitmask selects which steps/arms are live per dispatch; execution is pure +knowledge transfer — no runtime interpretation of orchestration config. + +**The exact analogy (each column already exists):** + +| Rendering (shipped) | Thinking orchestration (this design) | +|--------------------------------|------------------------------------------| +| askama template (compile-time checked) | compiled orchestration graph template (replayable) | +| `ClassView` (per-app projection) | per-style "ThinkView" projection of the graph | +| `FieldMask` bitmask (which fields render) | StepMask bitmask (which nodes/arms are active) | +| classid custom half selects the render lens | (post-P4) custom half indexes the template catalogue — 64k ClassViews × bitmask, styles-as-lenses (F2) | +| OGAR frontend lifts source → `Class` | `ogar-from-elixir` lifts the DSL → `Class`+`ActionDef` | + +**Why the lift is already 1:1:** `ogar-from-elixir` maps gen_statem-style +lifecycle onto `ActionDef` (`state_enter`→`on_enter`, `[:postpone]`→ +`GuardFailurePolicy::Postponable`, `state_timeout`→`state_timeout_millis`, +`next_state`→`EnterEffect::transition`) — and graph-flow's `NextAction` +(`Continue`/`ContinueAndExecute`/`WaitForInput`/`GoTo`/`End`) is the SAME +state-machine vocabulary. An orchestration graph IS a lifted state machine; +the kanban phase arc (Planning→CognitiveWork→Evaluation→Commit) is itself +one. One parser, two emitters (wide OGAR arm + narrow SPO arm), one +compiled artifact. + +**Execution semantics (inherits the mailbox ruling):** rs-graph-llm +executes template INSTANCES as replayable sessions (graph-flow sessions +are already deterministic step records); every instance inherits ownership +from its SoA (write-on-behalf of the ractor dummy owner, never state +beside the SoA); Rig slots in as the optional LLM-API template ORACLE node +for the escalation tail; the standing 550 ms async plan each thinking +cycle follows IS a compiled template instance — the cycle replays its +template whether or not a kanban update arrived. + +**Knowledge transfer, literally:** the compiled template is the +transferable knowledge artifact — deterministic, maskable, replayable +across sessions and mailboxes. Sessions exchange compiled orchestration, +not prose plans. (Precedent: jitson "config IS the code" — thresholds +become immediates; here graph configs become compiled templates.) + +**The DSL crate already ships IN lance-graph (operator pointer):** +`crates/elixir-template` — "the declarative, replayable macro a +successful LLM run compiles down to, whose steps bind to OGAR actions +and run deterministically without the LLM" — with `crates/ +template-runtime` (deterministic reflex executor, OGAR-action dispatch) +and `crates/template-equivalence` beside it. `ogar-from-elixir` is the +eventual RICHER front-end, not the canonical shape. Note the compile +DIRECTION the crate doc names: a successful LLM (Rig-oracle) run +compiles DOWN to a template — knowledge transfer is literal (LLM run → +deterministic replayable macro). + +**Deliverable seeds (next arc, corrected):** (a) StepMask bitmask on +`ElixirTemplate`/`template-runtime` (sibling of `ClassView`/`FieldMask`); +(b) extend the elixir-template/template-runtime pair (ogar-from-elixir +stays the future richer frontend); (c) graph-flow adapter in +rs-graph-llm: `ElixirTemplate` → `GraphBuilder`, session = replay, +ownership inherited from the SoA; (d) Rig oracle node type (optional +feature) + the run→template compile-down path; (e) post-P4: catalogue +dispatch keyed by the classid custom half. + +## 2026-07-02 — E-MAILBOX-KANBAN-NO-COLLAPSEGATE — operator correction: no singleton-BindSpace CollapseGate; one mailbox = one kanban board (tenant-carried), writer fires AHEAD, consumers write on behalf of the ractor dummy owner + +**Status:** DOCTRINE (operator ruling, 2026-07-02 — corrects this session's +"CollapseGate-gated write-back" continuation step, which used the superseded +singleton-BindSpace sink-in bundle/bind pattern; consistent with the PR #477 +three-tier supersession). + +The ruled write/thinking model: + +1. **No CollapseGate as a singleton-BindSpace sink-in bundle/bind op.** + That pattern is dead. Merge algebra survives only INSIDE a mailbox's own + owned computation, never as a cross-boundary sink. +2. **One Mailbox = its own Kanban board — and the board itself needs a + TENANT** (per-mailbox board state as a value-tenant lane, sibling of the + per-row `KanbanTenant`). Executed through kanban-update in + lance-graph-planner OR SurrealDB-on-kv-lance "symbiont mode" (the + `symbiont` crate's loop is the shipped POC shape). +3. **ractor = compile-time ownership guarantee DUMMY.** ractor is too slow + as a bus — it just spawns; the mailbox actor exists so Rust move + semantics prove no-aliasing/no-race at compile time (E-CE64-MB-4). + Never a message handler in the hot path. +4. **Thinking is masked behind the batch writer, which fires an AHEAD + update** — the kanban update fires on write CAST, not on write + completion (refines symbiont's current "writer fires after commit" + framing: don't wait). At write-cast the batch writer checks via cache + logic whether ownership needs to be delegated or already is. +5. **Thinking cycles carry a standing ASYNC PLAN** they follow whether or + not an update arrived; the 64k–256k SoA prioritizes / load-balances + within the tight 550 ms NET budget (minus load delays). +6. **Every consuming crate always writes ON BEHALF OF the ractor mailbox + dummy owner** — no direct writes, ever (fleet-wide consumer iron rule). +7. **rs-graph-llm + rig as RAG:** graph-flow (LangGraph-shaped) = + REPLAYABLE TEMPLATES; Rig = optional LLM-API template ORACLE; + rs-graph-llm must always respect/inherit ownership from the respective + SoA (never own state beside it). + +Gap list vs shipped code (what the next arc builds), with the CONCRETE +seams (operator-confirmed): (a) the per-mailbox kanban-board tenant; +(b) the kanban STEP UPDATE emit — the deferred D-MBX-A6 `Outcome → +Candidate/KanbanMove` adapter in `lance-graph-planner +strategy/style_strategy.rs` (the planner computes outcomes but does not +yet emit KanbanMoves) — with `lance-graph-supervisor kanban_actor.rs` as +the ractor structural owner and `symbiont` as the SurrealDB-on-kv-lance +executor arm; (c) the ahead-update batch writer + write-cast delegation +cache; (d) the standing async plan + 550 ms SoA load balancer; (e) the +write-on-behalf consumer rule enforced at the contract surface — now +STARTED: `SoaEnvelope::mailbox_owner()` (the LE contract carries the +ownership up and down; views are owner-borrows structurally, the stamp +names the owner nominally for Lance-down and consumer-up); (f) +rs-graph-llm/rig ownership-inheritance wiring. + +## 2026-07-02 — E-CLASSID-CANON-HIGH-IS-A-CLUSTERED-INDEX — the flip bought key-order domain locality, not just naming hygiene + +**Status:** FINDING (structural consequence, verifiable by construction). + +Nobody named this during the arc: with the canon in the HIGH u16, sorting +or prefix-scanning by `classid` now clusters rows BY DOMAIN:APPID. Pre-flip, +classid order clustered by the custom half (marker/render prefix — useless +locality: all `0x1000_*` V3 rows interleaved across domains). Post-flip, +`0x0701_*` (OSINT:q2), `0x0A01_*` (Anatomy:q2), `0x0E01_*` (Genetics:q2) +are CONTIGUOUS key ranges. Consequences, all free: + +1. **Lance/columnar:** a domain-scoped scan is a key-range predicate on + bytes 0..4 of the NodeGuid — no value decode, no filter pass. +2. **Radix/trie routing (HHTL, OGAR longest-prefix codebook binding):** the + first key nibbles now walk domain → appid → custom, matching the + 16-ary-tree canon ("codebook scoping = the class routing prefix") — + the trie's discriminating information moved to the FRONT of the key. +3. **The operator's mnemonic `0x07:01::1000` IS the sort order** — the + printed GUID is self-describing AND self-clustering at sight. + +Follow-on: when the corpus-proof scanner (alias retirement gate) runs, it +can exploit this — old-form rows are exactly the keys whose high half is +`0x0000`/`0x1000`-shaped, i.e. two narrow key ranges, so the scan is a +range count, not a full sweep. + ## 2026-07-02 — E-CLASSID-COMPAT-READER — the P0 sweep missed rbac.rs: `class as u16` in ClassGrant::permits; fixed via a mint-forward compat reader **Status:** SHIPPED (follow-up on the P1 flip commit, PR #628 arc). @@ -9472,3 +9777,10 @@ Cross-ref: W2's sprint-2 deliverable (Tier-0 "what's shipped" index); `.claude/p **Practical consequence (do not let this drift back):** `surreal_container` (BLOCKED A/B/C/D — fork dep + Lance 6 pin) is **optional**, not on the critical path for D-MBX-6. D-MBX-6's hot/cold transparent view uses the LanceDB cold tier directly; the SurrealDB kanban is a *second* view over the same LanceDB rows. **Cross-ref:** `E-RUBICON-RACTOR` (current ruling), `E-MAILBOX-IS-BINDSPACE` (§2.7 of the plan it gates), `E-BATON-1` (the LE-contract anchor), `.claude/plans/causaledge64-mailbox-rename-soa-v1` (driver plan that subsumes the surreal POC), `.claude/handovers/2026-05-28-1200-pr-418-419-surreal-mailbox-baton-plan-map.md` §5 (the audit source for this entry). + +## 2026-07-02 — CORRECTION-OF 2026-07-02 (review #629 sharpenings: LE byte-order, legacy scan shapes, ractor wording) +**Status:** FINDING + +Three review findings on the #629 doc arc, accepted and folded into the V3 docs (routing.md §1/§5, mailbox-kanban-model.md, INTEGRATION-PLAN W6a): (1) **Clustered-index caveat** — `NodeGuid` stores classid via `to_le_bytes`, so RAW key-byte prefixes order by the custom byte first; domain range-scans hold over the DECODED u32 (or an order-preserving big-endian rendering), never raw LE byte prefixes/tries (E-CLASSID-CANON-HIGH-IS-A-CLUSTERED-INDEX reads with this caveat). (2) **Corpus-proof scanner scope** — "old-form" = ALL THREE legacy shapes: `0x0000_DDCC`, `0x1000_DDCC`, AND `0xAAAA_DDCC` (legacy app/render prefix high, e.g. `0x0005_0901`) — exactly the set `classid_canon_compat` routes CanonLow; scanning only the first two can falsely prove the corpus clean (E-V3-MARKER-IS-A-MONITOR reads with this scope). (3) **ractor wording sharpened** — "compile-time ownership dummy / never a hot-path bus" scopes the DATA plane; the actor mailbox remains the runtime serialized single-writer CONTROL path (one-message Advance/MulAdvance serialization = the codex #578 atomicity mechanism). The operator ruling's meaning is unchanged; the wording now says both halves. + +Cross-ref: PR #629 review threads (2 codex P2 + 1 coderabbit); E-MAILBOX-KANBAN-NO-COLLAPSEGATE. diff --git a/.claude/board/INTEGRATION_PLANS.md b/.claude/board/INTEGRATION_PLANS.md index 3c32b290c..9fe2e82df 100644 --- a/.claude/board/INTEGRATION_PLANS.md +++ b/.claude/board/INTEGRATION_PLANS.md @@ -1,3 +1,7 @@ +## 2026-07-02 — v3-substrate-integration (W0–W6; the .claude/v3/ consolidation) + +Plan: `.claude/v3/INTEGRATION-PLAN.md` (pointer stub at `.claude/plans/v3-substrate-integration-v1.md` — operator directed a dedicated `.claude/v3/` folder for overview). **Consolidates the 2026-07-02 operator rulings into one wave-ordered execution plan**: W0 ratify/document (the `.claude/v3/` tree + awareness layer: knowledge docs, `v3-*` agent cards, `/v3` skill, `/v3-audit` command, CLAUDE.md/BOOT.md entrypoints) → W1 envelope+ownership (the keystone: `mailbox_owner()` SHIPPED; ahead-firing batch writer `cast(on_behalf, BusDto)` + delegation cache) → W2 kanban executors (D-MBX-A6 adopt; board-as-TENANT; supervisor sole-mutator wiring; symbiont arm BLOCKED on surrealdb kv-lance coordinates; 550 ms budget via elevation) → W3 compiled templates (StepMask; ElixirTemplate→graph-flow adapter with ownership inheritance; Rig oracle equivalence-gated compile-down; catalogue internal until P4) → W4 DTO ladder (D-PERT-1 adopt; cast-pairing call sites) → W5 consumers (q2 re-bakes/cpic mereology; write-on-behalf adoption; D-VCW-3/5 probes) → W6 monitor & retirement (ONE two-metric range-count scanner; P4 = adoption 100%, operator checkpoint; alias retirement corpus-proof-gated). Principle carried over: wire, don't invent — the plan adopts existing D-ids (D-MBX-A6, D-PERT-1, D-CC-*, D-VCW-*, D-CCF-4) rather than re-minting. Extends `v3-convergence-wiring-v1` + `soa-value-tenant-migration-v2`; supersedes stale CollapseGate prose everywhere via primer §6. ACTIVE. + ## 2026-07-02 — classid-canon-custom-flip (TRIGGERED — the §2.3 atomic flip is live) Plan: `.claude/plans/classid-canon-custom-flip-v1.md`. **Operator pulled the trigger** ("now is the right time for the migration — document it accordingly"): canon (`domain:appid`) moves to the classid's HIGH u16, custom (the temporary `0x1000` V3 marker, later the render/dynamic-classview space) to the LOW — stored `0x0701_1000`, human-readable `0x07:01::1000`. Grounded in the same ruling: OSINT low byte = APPID space domain-wise (q2=`0x01`; zero vocabulary rows — OGAR PR #146), FMA/CPIC own domains under q2 (CPIC normalizes `:00`→`:01`), q2 push gate WAIVED. Mechanism: ONE flippable `compose_classid/split_classid/CLASSID_CANON_HIGH` in the contract (per `E-CLASSID-SPLIT-ORDER-IS-A-FLIP`), `flip(flip(x))==x` probed, **mint-forward with an I-LEGACY version boundary** (legacy `0x0000_XXXX` classids never blanket-reinterpreted). Phases: P0 route-through (zero behavior) → P1 flip+coexist → P2 OGAR#95 hi-u16 app-prefix reconciliation (operator checkpoint) → P3 q2 re-mints (dissolves `ISS-Q2-CPIC-MIRROR…`) → P4 `0x1000` retirement (operator checkpoint). Supersedes-by-trigger `E-CLASSID-HUMANREADABLE-REORDER-DEFERRED`; executes `soa-value-tenant-migration-v2` §2.3. ACTIVE. diff --git a/.claude/board/LATEST_STATE.md b/.claude/board/LATEST_STATE.md index c7e387002..29819305f 100644 --- a/.claude/board/LATEST_STATE.md +++ b/.claude/board/LATEST_STATE.md @@ -100,6 +100,7 @@ Membrane consumers can now pull BOTH halves of a render `classid` BBB-safely fro | PR | Merged | Title | What it added | |---|---|---|---| +| **#628** | 2026-07-02 | classid canon:custom half-order flip EXECUTED (P0+P1+P2) | `CLASSID_ORDER = CanonHigh` live: canon `domain:appid` HIGH / custom LOW (`0x0701_1000` = `0x07:01::1000`); ONE flippable composition + `classid_canon_compat` (mint-forward both-forms reader — RBAC authorizes pre-flip rows, no re-bake); new-form mint constants + `CLASSID_*_LEGACY` aliases; hhtl dual-form fold; OGAR#95 reconciled (prefix = custom half, values unchanged); ogar pin → `19373a2` (OGAR #147 lockstep). Fleet: OGAR #147 + MedCare #180 + woa-rs #177 merged; q2 #71 + op-nexgen #68 open. Merge `6858118b`. | | **#627** | 2026-07-02 | classid canon:custom flip TRIGGERED (doc-only) | Operator ruling recorded + `classid-canon-custom-flip-v1.md` ACTIVE: canon `domain:appid` → hi u16, custom (`0x1000` temporary marker) → lo; `0x0701_1000` / `0x07:01::1000`; OSINT low byte = appid space (zero vocab rows, OGAR #146 67→65 fuse balanced); q2 gate WAIVED; ISSUES ×4 resolved/ruled; codex P2 guards locked (class_id via `classid_canon(id)` never `as u16`; legacy keys demote not retire). Merge `c8e1ec4`. | | **#626** | 2026-07-02 | V3 convergence wiring: tenant-carve certification, RungElevator, P6 wave probe, seam-list plan | "Wire, don't invent": `RungLevel::{from_u8,elevate,de_elevate,pearl_level,causal_mask_bits}` + `RungElevator` (sustained-BLOCK policy over P2/P3-certified masks; converged with `escalation::rung_delta` via `apply_delta` — one ladder, two signal sources) wired through the driver (persistent elevator, `ctx.rung=1` proxy retired, grpc rung saturates-never-wraps per codex P2); BOTH V3 tenant carves matrix-certified (Cognitive + Compressed); P6 probe (wave dist == certified palette read, markov_soa verified); `[patch.crates-io] ndarray` → local sibling path (fetch deadlock gone; first in-sandbox core build, 925/925). Plan `v3-convergence-wiring-v1.md`; worker Rule 7. Branch `claude/v3-substrate-migration-review-o0yoxv`, merge `5aaee33`. | | **#542** | 2026-06-18 | E-OGAR-IS-FOUNDRY capstone + 5+3 council + the key→row baton | Foundry/Gotham = "write the OGAR class schema + inheritance"; everything else is generic machinery over it (ontology=`classid→ClassView`+inheritance, AR=DO/THINK, pipelines=`compute_dag`, apps=Jinja-over-classes, query=Cypher⇄SurrealQL one IR). Added `MailboxSoaView::row_for_local_key -> Option` (default `None`, deferred-binding — the key→row baton for a future `Backend::MailboxSoa` router). Epiphanies `E-OGAR-IS-FOUNDRY`/`E-CYPHER-IS-THE-KANBAN-AST`/`E-GUID-IS-THE-GRAPH`; plan `cypher-kanban-ast-unification-v1`. Council corrections: `from_guid_prefix` is on `NiblePath` not `NodeGuid`; "odoo proof" = CONJECTURE; `ogar-adapter-surrealql` not a crate. Branch `claude/q2-substrate-grounding`, merge `faca377f`. | diff --git a/.claude/board/PR_ARC_INVENTORY.md b/.claude/board/PR_ARC_INVENTORY.md index 85f01e9a6..b27bbc644 100644 --- a/.claude/board/PR_ARC_INVENTORY.md +++ b/.claude/board/PR_ARC_INVENTORY.md @@ -35,6 +35,22 @@ --- +## #628 lance-graph: classid canon:custom half-order flip — P0 route-through + P1 CanonHigh + mint-forward compat reader + +**Status:** MERGED 2026-07-02 (merge commit `6858118b`), branch `claude/v3-substrate-migration-review-o0yoxv`. Executes plan phases P0+P1 (+P2 by construction); the fleet consumer PRs rode the same arc. + +**Added:** `ogar_codebook::{ClassidOrder, CLASSID_ORDER = CanonHigh, compose_classid[_with], split_classid[_with], classid_canon, classid_custom, flip_classid, classid_canon_compat}` (the ONE flippable composition + the mint-forward CANON reader for both-stored-forms surfaces); new-form mint constants (v1 `0x0700_0000`/`0x0A01_0000`/`0x0100_0000`/`0x0200_0000`; V3 `0x0701_1000`/`0x0A01_1000`/`0x0E01_1000` — OSINT/CPIC appid normalized `:01`=q2) + `CLASSID_*_LEGACY` read-only aliases in `BUILTIN_READ_MODES`; hhtl v1 fold dual-form boundary (both pure-canon stored forms fold to the IDENTICAL path); probes (round-trip both orders, `flip(flip)==x`, legacy-boundary matrix, no-class-collapse, compat both-forms, RBAC both-forms grant test). Lock: ogar pin `a0c7936 → 19373a2` (OGAR #147, the lockstep vocab flip). + +**Locked:** class discriminators derive via `classid_canon(id)` (strict) or `classid_canon_compat(id)` (both-forms surfaces: RBAC grants, un-re-baked corpora) — NEVER `as u16`/`& 0xFFFF`/`>> 8` on the composed u32; OGAR#95 reconciliation = the app prefix IS the custom half (`render_classid` composes concept HIGH / prefix LOW; prefix VALUES unchanged); legacy keys demote-don't-retire (corpus proof gates retirement); the canon slot exactly `0x1000` stays reserved-unusable until marker retirement (P4). + +**Corrections shipped in-arc:** the P0 sweep missed `rbac.rs` `class as u16` + `lance-graph-rbac` `u32::from` widening + `lance-graph-ogar` pre-flip literals (E-CLASSID-COMPAT-READER — a route-through sweep's coverage claim needs the same exhaustive-grep declaration as a negative-existence claim). + +**Deferred:** `0x1000` marker retirement (P4, operator checkpoint); legacy-alias retirement (corpus proof); q2 `.soa` re-bakes (q2 #71, CI/dev — runtimed [patch] unfetchable in sandbox) + `body.soa` release re-upload. + +**Docs:** plan `classid-canon-custom-flip-v1.md` (phases now P0/P1/P2 DONE, P3 in q2 #71, P4 open); EPIPHANIES `E-CLASSID-FLIP-P1-LANDED` + `E-CLASSID-COMPAT-READER`; fleet inventories in AGENT_LOG. Sibling merges: OGAR #147, MedCare-rs #180, woa-rs #177; open: q2 #71, openproject-nexgen-rs #68 (lock bumped `ff3777b`, gate closed). + +**Confidence (2026-07-02):** HIGH — 774 contract tests (guid-v3-tail) + 759 default + doctests + dependents (callcenter/shader-driver/planner/rbac/ogar) green; clippy -D warnings; fleet verified per-repo. + ## #627 lance-graph: classid canon:custom flip TRIGGERED — migration plan v1 + operator ruling record (doc-only) **Status:** MERGED 2026-07-02 (merge commit `c8e1ec4`), branch `claude/v3-substrate-migration-review-o0yoxv`. Doc-only: records the operator ruling arc and activates the §2.3 migration. diff --git a/.claude/board/STATUS_BOARD.md b/.claude/board/STATUS_BOARD.md index 91e371372..f1488fb91 100644 --- a/.claude/board/STATUS_BOARD.md +++ b/.claude/board/STATUS_BOARD.md @@ -1,3 +1,34 @@ +## v3-substrate-integration-v1 — the .claude/v3/ consolidation (W0–W6) + +Plan: `.claude/v3/INTEGRATION-PLAN.md` (stub: `.claude/plans/v3-substrate-integration-v1.md`). Adopts (does not re-mint) D-MBX-A6, D-PERT-1, D-CC-*, D-VCW-3/5/7, D-CCF-4. + +| D-id | Title | Crate(s) | Status | Evidence | +|---|---|---|---|---| +| D-V3-W0a | `.claude/v3/` tree (README, plan, COMPONENT-MAP, ENTROPY-MILESTONES, MODULE-TABLE, soa_layout/*) | docs | Shipped (this PR) | complete: 7/7 mappers synthesized; MODULE-TABLE = 304/304 files (21/21 census chunks); soa_layout 5/5 docs | +| D-V3-W0b | V3 awareness layer (knowledge docs, v3-* agent cards, /v3 skill, /v3-audit command, CLAUDE.md+BOOT.md entrypoints) | docs | Shipped (this PR) | 4 knowledge docs, 4 cards, skill+command registered | +| D-V3-W1a | SoaEnvelope::mailbox_owner() ownership stamp | lance-graph-contract | Shipped | this branch; 775 contract tests green | +| D-V3-W1b | Ahead-firing batch writer (cast pairing + AHEAD KanbanMove at cast) | planner-adjacent | Queued | plan W1 | +| D-V3-W1c | Delegation cache (cast id vs envelope stamp) | batch writer | Queued | plan W1 | +| D-V3-W1d | MailboxId minting path (non-zero owners, uniqueness debug_assert) | contract | Queued | plan W1 | +| D-V3-W1e | Probes: ahead-update ordering + delegation miss | contract/planner | Queued | probe-first gate for W2 | +| D-V3-W2a | Per-mailbox kanban board as TENANT | contract | Queued | field-isolation matrix mandatory | +| D-V3-W2b | Supervisor wiring: moves via MailboxSoaOwner::advance_phase | lance-graph-supervisor | Queued | plan W2 | +| D-V3-W2c | symbiont SurrealDB-on-kv-lance arm | symbiont | Blocked (kv-lance fork coordinates) | POC = kanban_loop.rs | +| D-V3-W2d | 550 ms budget hooks via planner elevation/ | lance-graph-planner | Queued | plan W2 | +| D-V3-W3a | StepMask in contract (sibling of FieldMask) | lance-graph-contract | Queued | plan W3 | +| D-V3-W3b | ElixirTemplate → graph-flow GraphBuilder adapter (ownership inheritance) | rs-graph-llm seam | Queued | plan W3 | +| D-V3-W3c | Rig oracle node + equivalence-gated compile-down | cognitive-compiler + rig | Queued | D-VCW-7 lineage | +| D-V3-W3d | Template catalogue keyed internally (classid keying deferred to P4) | template-runtime | Queued | plan W3 | +| D-V3-W4a | BusDto cast-pairing call sites | cognitive-shader-driver | Queued | consumes W1b | +| D-V3-W4b | L4 learning-loop end-to-end probe (residue → owner-stamped lane → next-cycle template read) | cross-crate | Queued | plan W4 | +| D-V3-W5a | q2 CI re-bakes + body.soa re-release + drop FMA_V3_CLASSID_LEGACY | q2 | Queued | handover continuation §1 | +| D-V3-W5b | cpic contract pull with mereology (kinds → cascade positions) | q2 + contract | Queued | handover F3 | +| D-V3-W5c | Consumer write-on-behalf adoption (bakes annotated bootstrap; new online writes via batch writer) | fleet | Queued | write-on-behalf.md | +| D-V3-W5e | ladybug-rs + smb-office-rs contract pulls | siblings | Queued | never bridges | +| D-V3-W6a | Adoption/corpus scanner (ONE two-metric range-count tool) | lance-graph | Queued | E-V3-MARKER-IS-A-MONITOR | +| D-V3-W6b | Legacy alias retirement (corpus-proof-gated) | contract + consumers | Blocked (corpus proof) | plan W6 | +| D-V3-W6c | Custom half opens: render + template catalogue dispatch | contract | Blocked (P4 operator checkpoint) | completes F2 styles-as-lenses | + ## classid-canon-custom-flip-v1 — the TRIGGERED §2.3 atomic flip Plan: `.claude/plans/classid-canon-custom-flip-v1.md`. Operator trigger 2026-07-02. @@ -9,6 +40,7 @@ Plan: `.claude/plans/classid-canon-custom-flip-v1.md`. Operator trigger 2026-07- | D-CCF-2 | OGAR#95 hi-u16 app-prefix reconciliation | contract + OGAR | In PR (OGAR #147; prefix = custom half) | plan §2 row / §4 P2 | | D-CCF-3 | q2 re-mints (osint-bake + cpic via contract pull; dissolves ISS-Q2-CPIC-MIRROR) | q2 (gate WAIVED) | In PR (q2 #71; .soa re-bakes deferred to CI/dev; cpic interim 0x0E01_000N, full contract pull tracked) | plan §4 P3 | | D-CCF-4 | 0x1000 marker retirement | all | Blocked (operator checkpoint) | plan §4 P4 | +| D-PERT-1 | Rename dto.rs ResonanceDto → PerturbationDto (split, not dedup; deprecated alias; awareness_dto keeps Resonance) | thinking-engine + engine_bridge | Queued | E-TWO-RESONANCES-SPLIT | ## v3-convergence-wiring-v1 — wire, don't invent (the seam list) diff --git a/.claude/board/TECH_DEBT.md b/.claude/board/TECH_DEBT.md index a5b9af396..4e1a42e54 100644 --- a/.claude/board/TECH_DEBT.md +++ b/.claude/board/TECH_DEBT.md @@ -1,5 +1,16 @@ # Technical Debt Log — Open + Paid (double-entry, append-only) +## TD-RESONANCEDTO-DUPLICATE (2026-07-02) + +Two `ResonanceDto` definitions coexist in thinking-engine: `src/dto.rs` +(Ψ ripple field) and `src/awareness_dto.rs` (perspectival gestalt). +RESOLUTION RULED (2026-07-02, E-TWO-RESONANCES-SPLIT): a SPLIT, not a +dedup — the two are distinct concepts wrongly sharing a name. D-PERT-1: +rename `dto.rs::ResonanceDto` → `PerturbationDto` (~9 files, deprecated +type alias for transition); `awareness_dto.rs` keeps Resonance (the +perspectival phenomenon). "Cascade" (HEEL/HIP/TWIG key tiers) is NOT +renamed — canon vocabulary. + > **Append-only ledger** for knowingly-deferred work: TODOs, shortcuts, > workarounds, unsafe assumptions, missing probes, hardcoded > thresholds, stubs, and anything else we shipped with intentional diff --git a/.claude/commands/v3-audit.md b/.claude/commands/v3-audit.md new file mode 100644 index 000000000..ff5041a29 --- /dev/null +++ b/.claude/commands/v3-audit.md @@ -0,0 +1,42 @@ +--- +description: > + Mechanical V3 conformance audit of the working tree (or a given crate): + forbidden classid bit math, singleton/baton resurrection, ownership + fields on DTOs, unstamped write paths, layout-version hygiene. + Read-only; reports findings with file:line, fixes nothing. +--- + +Run the V3 conformance audit. Scope: `$ARGUMENTS` if given (a crate or +directory), otherwise the full workspace diff against origin/main plus +the contract crate. + +Read `.claude/v3/knowledge/v3-substrate-primer.md` §5–6 and +`.claude/v3/knowledge/write-on-behalf.md` first if not already loaded. + +Then run these checks with the Grep tool (never bash grep) and report +every hit with file:line and a one-line disposition +(violation / legacy-gated OK / test-only OK / false positive): + +1. **Forbidden classid discriminators** on composed u32 classids: + pattern `(as u16|& *0xFFFF|>> *16|>> *8)` in files that also match + `classid|class_id|CLASSID`. Sanctioned: `classid_canon`, + `classid_canon_compat`, `compose_classid`, `split_classid`, + `render_classid`, `ogar_vocab::app::*`. +2. **Resurrection scan**: `CollapseGateEmission|MailboxSoA::emit|wire_cost_bytes|last_emission_cycle` + — any non-historical, non-doc hit is a violation + (successor: zero-copy envelope + kanban tenant). +3. **Ownership fields on DTOs**: `owner|mailbox_id|tenant_id` as FIELDS + inside `StreamDto|ResonanceDto|PerturbationDto|BusDto|ThoughtStruct` + definitions — BusDto especially (E-DTO-LADDER-OWNERSHIP-SPLIT). +4. **Unstamped writes**: direct Lance/SoA writes (`Dataset::write|append|insert`) + in consumer crates without an envelope/`mailbox_owner` in scope — + classify bake pipelines as grandfathered-bootstrap, online paths as + violations. +5. **Layout hygiene**: diffs touching `soa_envelope.rs|canonical_node.rs` + — verify const size asserts unchanged or `ENVELOPE_LAYOUT_VERSION` + bumped, and that no `_LEGACY` read-mode key was removed (retirement is + corpus-proof-gated). + +End with a verdict per the v3-mailbox-warden vocabulary (OWNED / +BOOTSTRAP-OK / ORPHAN-WRITE / RESURRECTION) plus LAYOUT-CLEAN / +LAYOUT-GATED / LAYOUT-BREAK for check 5, and a one-paragraph summary. diff --git a/.claude/handovers/2026-07-02-classid-canon-high-flip-to-v3-thinking-sessions.md b/.claude/handovers/2026-07-02-classid-canon-high-flip-to-v3-thinking-sessions.md new file mode 100644 index 000000000..1c2620d52 --- /dev/null +++ b/.claude/handovers/2026-07-02-classid-canon-high-flip-to-v3-thinking-sessions.md @@ -0,0 +1,227 @@ +# 2026-07-02 — classid canon-high flip SHIPPED → integration guide for every V3-substrate session + +> From: the flip-execution session (lance-graph #626/#627/#628 arc). +> To: any session touching classids, V3 keys, SoA tenants, RBAC, rendering, +> or the thinking layer. APPEND-ONLY per handover protocol. + +## What is true now (all merged 2026-07-02) + +- **`CLASSID_ORDER = CanonHigh`** (lance-graph #628): a composed classid is + `[hi u16: CANON concept/domain:appid][lo u16: CUSTOM marker/render-prefix]`. + Stored `0x0701_1000` = human-readable `0x07:01::1000` (OSINT:q2, V3 marker). +- Mint constants: v1 `0x0700_0000` (OSINT) / `0x0A01_0000` (FMA) / + `0x0100_0000` (PROJECT) / `0x0200_0000` (ERP); V3 `0x0701_1000` / + `0x0A01_1000` / `0x0E01_1000` (OSINT + CPIC appid normalized `:01` = q2). +- **OGAR #147** flipped `ogar_vocab::app::{render_classid, app_of, concept_of}` + in lockstep; `APP_PREFIX` VALUES unchanged (only the position moved to LOW). + The OGAR#95 reconciliation resolved by construction: the app prefix IS the + custom half; the #95 allocation table is the custom-half render catalogue. +- Consumers merged: q2 #71, openproject-nexgen #68 (+ trailing lock PR #69), + MedCare-rs #180, woa-rs #177. Zero-impact verified: OGIT, tesseract-rs, + openproject (Ruby). + +## The five iron consumer rules (post-flip) + +1. **Never local bit math.** Compose via `contract::render_classid` / + `compose_classid`, or `ogar_vocab::app::*`. A `(x << 16) | y` on classids + in a consumer is a defect (this is how three latent bugs shipped pre-flip). +2. **Discriminators:** `classid_canon(id)` (strict, new mints) or + `classid_canon_compat(id)` (surfaces serving BOTH stored forms — RBAC + grants, reads over un-re-baked corpora). FORBIDDEN on the composed u32: + `as u16`, `& 0xFFFF`, `>> 8`, `>> 16` — post-flip each reads the wrong + half or the wrong byte; grep-gate your crate for them. +3. **Mint-forward, never reinterpretation.** Persisted pre-flip ids + (`0x0000_DDCC` / `0xAAAA_DDCC` / `0x1000_DDCC`) resolve forever via the + `CLASSID_*_LEGACY` alias keys in `BUILTIN_READ_MODES` + the compat reader. + Re-baking is optional hygiene, never a correctness prerequisite. Alias + retirement is gated on a corpus proof (a scan showing zero old-form rows). +4. **The custom half is spoken for until P4.** Current tenants: the `0x1000` + V3 marker (temporary by declaration), §2 app render prefixes + (`0x0000..0x0007`), and interim kind slots (q2 cpic `0x0E01_000N`). The + canon slot exactly `0x1000` (domain-0x10 root) is reserved-unusable until + the marker retires. P4 (operator checkpoint) opens the half for the real + 64k dynamic ClassViews × bitmask render catalogue. +5. **Fix layout docs BEFORE their phase lands.** A stale doc comment + describing the old order seeds the wrong implementation (the woa-rs + Phase-3 near-miss). Conversely: a sweep's "all sites routed" claim needs + a whole-crate `as u16|>> 16|& 0xFFFF|u32::from` grep, not a plan-inventory + walk (`E-CLASSID-COMPAT-READER` — the P0 sweep missed rbac.rs). + +## Thinking-migration to V3 — findings + +- **F1 — the canon u16 is now the single cross-layer currency.** The same + value is: the EntityType SoA tenant stamp, the RBAC `ClassGrant` key, the + `ConceptDomain` route (`canon >> 8`), the codebook id, and the cross-app + join key. Thinking layers should key on the u16 canon and treat the + composed u32 as address-only (pure address; the magic is at the resolution + target). +- **F2 — thinking styles are render lenses.** "Two renders, one concept" + (OpenProject/Redmine) generalizes: post-P4 the custom half can carry a + per-style ClassView selection — 36 thinking styles as 36 lenses over the + SAME canon concept, dispatched exactly like app render skins. That is the + natural landing zone for style-conditioned field-masks/templates without + any new struct (AGI-as-SoA invariant holds). +- **F3 — cpic's kind slots are register-laziness.** Per the operator's + mereology directive ("basins are genomic mereology, not labels") the six + CPIC kinds want to be cascade POSITIONS (HEEL/family coordinates under one + `0x0E01_1000` class), not classid customs. The interim `0x0E01_000N` + scheme is documented as interim; the contract-pull re-mint should fold + kind into position, which also frees the custom half for P4. +- **F4 — V3 nible paths are ready-made thinking metrics.** + `from_guid_prefix_v3` + `family_hop_count` give O(depth), zero-value-decode + graph distance on V3 keys — the natural adjacency for AriGraph/episodic + tissue (`Think.graph` / `Think.episodic`) without touching value slabs. + +## Suggested continuation (ordered) + +1. **CI re-bakes** (q2): `cargo run -p osint-bake` + `--bin fma` in an + environment with normal egress; commit refreshed `osint_scene.soa` / + `fma.soa`; re-release `body.soa` then drop `FMA_V3_CLASSID_LEGACY` from + `BodyV3.tsx`. +2. **Run the waived probes:** D-VCW-3 (q2 P7 render probe) + D-VCW-5 + (cascade3 nibble falsifier) — specs ready, q2 gate waived; they validate + V3 keys end-to-end through the cockpit. +3. **Phase-2 tenant shaping** (`soa-value-tenant-migration-v2`): the thinking + layer reads/writes tenant lanes via `classid_read_mode(c).value_schema` + — CPIC gene expression as the coordinate VALUE on the Compressed schema; + keep the field-isolation matrix mandatory for every new tenant. +4. **Wire F4:** AriGraph/episodic distance via V3 nible-path hop counts; + CausalEdge64 provenance rows keyed by V3 addresses (RungElevator already + feeds rung; the edge column is next). +5. **cpic contract pull with mereology (F3)** — dissolves the interim scheme + and `ISS-Q2-CPIC-MIRROR`. +6. **Corpus-proof scanner:** a small utility that counts old-form classids in + Lance datasets → the mechanical gate for legacy-alias retirement. +7. **P4 marker retirement (operator checkpoint)** → open the custom half for + the render catalogue; then F2 (styles-as-lenses) becomes implementable. +8. **Remaining consumers:** ladybug-rs (still pre-V3/rustynum-era), + smb-office-rs (consumer-preflight applies) — contract pulls only. + +## Outstanding operator checkpoints + +- **P4**: `0x1000` marker retirement / custom-half opening. +- **Alias retirement**: only after the corpus proof (step 6). + +--- + +## APPENDED CORRECTION (operator, 2026-07-02, same day) + +Continuation step 3 above said "CollapseGate-gated write into tenant lanes" +— **that framing is corrected**: there is no CollapseGate in the +singleton-BindSpace sink-in bundle/bind sense anymore. The ruled model +(full text: board `E-MAILBOX-KANBAN-NO-COLLAPSEGATE`): + +- One Mailbox = its own Kanban board, carried as a TENANT (per-mailbox, + sibling of the per-row `KanbanTenant`), executed via kanban-update in + lance-graph-planner or SurrealDB-on-kv-lance symbiont mode (`symbiont` + crate = the POC shape). +- ractor = compile-time ownership dummy (spawn-only, never a hot-path bus). +- The batch writer fires an AHEAD kanban update on write CAST (no wait), + checking ownership delegation via cache logic at cast time. +- Thinking cycles follow a standing async plan regardless of updates; the + 64k–256k SoA load-balances within a 550 ms net budget. +- Every consuming crate writes ON BEHALF OF the ractor dummy-owner mailbox + — fleet-wide iron rule. +- rs-graph-llm (graph-flow) = replayable templates, Rig = optional LLM + template oracle; both inherit ownership from the respective SoA. + +Sessions reading this handover: steps 3–4 of the continuation execute +under THIS model, not the CollapseGate wording above. + +--- + +## APPENDED (operator, 2026-07-02, same day): compiled thinking templates + +Extends the correction above, item on rs-graph-llm/rig: orchestration +COMPILES like askama ↔ ClassView×bitmask — the elixir-like DSL +(`ogar-from-elixir`, NOT Elixir) is the source; the compiled orchestration +graph is a replayable template; a StepMask bitmask (sibling of `FieldMask`) +selects live steps per style/dispatch; rs-graph-llm executes instances as +replayable sessions inheriting SoA ownership; Rig is the optional LLM +template oracle; post-P4 the classid custom half indexes the template +catalogue (styles-as-lenses F2 becomes catalogue dispatch). Full text + +the 1:1 gen_statem↔ActionDef↔NextAction mapping + deliverable seeds: +board `E-COMPILED-THINKING-TEMPLATES`. + +--- + +## APPENDED (operator, 2026-07-02, same day): three sharpenings + +1. **Envelope ownership witness (SHIPPED this branch):** the SoA LE + contract inherits mailbox ownership up and down — `SoaEnvelope` views + are owner-borrows (compile-time, structural), and the new + `SoaEnvelope::mailbox_owner()` stamp (default `0` = bootstrap per the + zero-fallback ladder) names the owner nominally for Lance-down + provenance and consumer-up write-on-behalf. Delegation mismatches + (cast id ≠ envelope stamp) are the batch writer's cache-logic case. +2. **The kanban step-update seam is concrete:** D-MBX-A6 — the deferred + `Outcome → Candidate/KanbanMove` adapter in `lance-graph-planner + strategy/style_strategy.rs`; `lance-graph-supervisor kanban_actor.rs` + is the ractor structural owner; `symbiont` is the + SurrealDB-on-kv-lance executor arm. +3. **`0x1000` = V3-adoption MONITOR** (deprecated when nothing is left + to monitor) — P4's trigger is now defined: adoption reads 100%. The + corpus scanner and adoption monitor are one two-metric range-count + tool. Also: the compiled-template DSL already ships in lance-graph as + `elixir-template` + `template-runtime` + `template-equivalence` + (ogar-from-elixir = future richer frontend); the crate doc names the + compile-down direction — a successful LLM run compiles to the + deterministic template. + +--- + +## APPENDED (operator overlap question resolved, 2026-07-02): the DTO ladder vs ownership + +The old `thinking-engine > p64 > cognitive-shader-driver` ladder +(Φ `StreamDto` / Ψ `ResonanceDto` / B `BusDto` / Γ `ThoughtStruct`) +survives intact with one pinned rule: **BusDto never grows ownership +fields.** BusDto = cognitive provenance (what was thought, how settled); +`SoaEnvelope::mailbox_owner` + write-on-behalf = write provenance (whose +lane, who may write). Same moment, orthogonal content; the batch writer +pairs them at cast: `cast(on_behalf = envelope.mailbox_owner(), payload += BusDto)`. StreamDto is the ancestor of the standing-async-plan ruling +(can't-stop-thinking = following the compiled template without waiting +to be called); ResonanceDto stays intra-mailbox (dedup its two +definitions — dto.rs + awareness_dto.rs); BusDto's converged/cycle_count +feed the D-MBX-A6 KanbanMove emit. Full text: board +`E-DTO-LADDER-OWNERSHIP-SPLIT`. + +--- + +## APPENDED (operator disambiguation, 2026-07-02): the two resonances + +Two distinct concepts share the `ResonanceDto` name; the split is ruled +(full text: board `E-TWO-RESONANCES-SPLIT`): + +- `dto.rs::ResonanceDto` = the MECHANICAL Ψ field (Morton-tile + inverse-pyramid perturbation interference) → renames to + `PerturbationDto` (D-PERT-1, queued; deprecated alias for transition). + "Cascade" (HEEL/HIP/TWIG key tiers) is NOT renamed — canon vocabulary. +- `awareness_dto.rs::ResonanceDto` = the PERSPECTIVAL resonance and + keeps the name — it already encodes the Piaget Three-Mountains + structure (3D subject/predicate/object HdrResonance + inferred user + model = the recipient's perspective ≠ the sender's) against the + Object's self-Gestalt (`classid → ClassView` = "was sagt das Objekt + über sich selbst aus" = "the object speaks for itself"). + Familienaufstellung = the mailbox constellation, each with its own + angle on shared canon objects; "two renders, one concept" is the + Three-Mountains theorem in the addressing. +- L4 perturbation feeds back into Learning THROUGH the SoA Lance row: + converged residue persists into tenant lanes via the owner-stamped + envelope; the next cycle's standing template reads the row — the + persisted perturbation reshapes the next F landscape (The Click's + loop, carried by tenant lanes, never a cross-mailbox carrier). + +--- + +## APPENDED (2026-07-02): the V3 work now has a dedicated home — `.claude/v3/` + +Everything this handover carries (and the rulings appended above) is +consolidated under **`.claude/v3/`** — start there instead of stitching +board entries: `README.md` (orientation) → `INTEGRATION-PLAN.md` (waves +W0–W6) → `COMPONENT-MAP.md` / `MODULE-TABLE.md` (what maps/reuses/retires) +→ `soa_layout/` (LE contract, tenants, consumer map, routing) → +`knowledge/` + `agents/BOOT.md` (the V3 awareness layer; cards at +`.claude/agents/v3-*.md`). Session shortcuts: `/v3` (bootload) and +`/v3-audit` (pre-commit conformance greps). CLAUDE.md and `.claude/BOOT.md` +now point here as the V3 entry point. diff --git a/.claude/plans/v3-substrate-integration-v1.md b/.claude/plans/v3-substrate-integration-v1.md new file mode 100644 index 000000000..d828535c8 --- /dev/null +++ b/.claude/plans/v3-substrate-integration-v1.md @@ -0,0 +1,14 @@ +# v3-substrate-integration-v1 — pointer stub + +> **The plan body lives at `.claude/v3/INTEGRATION-PLAN.md`** (operator +> directive 2026-07-02: the V3 work gets its own folder for overview — +> `.claude/v3/*`). This stub exists so the `.claude/plans/-v.md` +> convention stays greppable. + +- Plan: `.claude/v3/INTEGRATION-PLAN.md` (waves W0–W6) +- Orientation: `.claude/v3/README.md` (or the `/v3` skill) +- Subsystem mapping: `.claude/v3/COMPONENT-MAP.md` +- Milestone ledger: `.claude/v3/ENTROPY-MILESTONES.md` +- Layout contracts: `.claude/v3/soa_layout/` +- Awareness layer: `.claude/v3/knowledge/`, `.claude/v3/agents/BOOT.md`, + `/v3` + `/v3-audit` commands, agent cards `.claude/agents/v3-*.md` diff --git a/.claude/skills/v3/SKILL.md b/.claude/skills/v3/SKILL.md new file mode 100644 index 000000000..912453699 --- /dev/null +++ b/.claude/skills/v3/SKILL.md @@ -0,0 +1,47 @@ +--- +name: v3 +description: > + Bootstraps V3-substrate awareness for this session: the mailbox-kanban + model (no singleton CollapseGate), the SoaEnvelope LE ownership contract + (mailbox_owner + write-on-behalf), compiled thinking templates + (elixir-template / StepMask / graph-flow / Rig oracle), classid canon-high + + the 0x1000 adoption monitor, and the DTO ladder (PerturbationDto split). + Use when a session touches SoA rows, tenants, kanban, templates, mailbox + ownership, or asks "what is V3 / where do I start". Canonical files live + under .claude/v3/ — this skill is the loader, not the content. +--- + +# /v3 — V3 Substrate Bootload + +You just entered V3 territory. Load, in this order, reading fully: + +1. `.claude/v3/README.md` — what V3 is, what shipped, the doc map. +2. `.claude/v3/knowledge/v3-substrate-primer.md` — the ruled model in one + page (mailbox-kanban, envelope ownership, DTO ladder, templates, + classid canon + monitor, the must-not-reinvent table). +3. The domain doc your task touches: + - write paths / consumers → `.claude/v3/knowledge/write-on-behalf.md` + - kanban / batch writer / executors → `.claude/v3/knowledge/mailbox-kanban-model.md` + - templates / orchestration / oracle → `.claude/v3/knowledge/compiled-templates.md` + - byte layout / tenants / routing → `.claude/v3/soa_layout/README.md` + (then `le-contract.md`, `tenants.md`, `routing.md` as needed) +4. `.claude/v3/INTEGRATION-PLAN.md` — which wave (W0–W6) your work + belongs to and what gates it. +5. `.claude/v3/agents/BOOT.md` — which V3 card to wake + (`v3-mailbox-warden` / `v3-envelope-auditor` / + `v3-kanban-executor-engineer` / `v3-template-smith`). +6. Spawning Sonnet workers? Paste the §1 preamble of + `.claude/v3/knowledge/sonnet-worker-guardrails.md` verbatim into every + worker brief — non-negotiable (operator footgun-proofing directive). + +Then apply the two standing gates to your own diff before any commit: + +- **Ownership gate:** every write on behalf of + `envelope.mailbox_owner()`; no ownership fields on DTOs; no + CollapseGate/baton/emission resurrection. (`/v3-audit` runs the greps.) +- **Layout gate:** byte offsets stable or version-gated; field-isolation + matrix for any layout-touching change; legacy read modes intact. + +Tier-0 workspace reads (`LATEST_STATE.md`, `PR_ARC_INVENTORY.md`) remain +mandatory per the main `.claude/BOOT.md` — this skill adds to them, it +does not replace them. diff --git a/.claude/v3/COMPONENT-MAP.md b/.claude/v3/COMPONENT-MAP.md new file mode 100644 index 000000000..0443f7ae9 --- /dev/null +++ b/.claude/v3/COMPONENT-MAP.md @@ -0,0 +1,145 @@ +# Component Map — every subsystem onto the V3 substrate + +> Produced by the 2026-07-02 mapping fleet (7 subsystem mappers, file:line +> evidence) + main-thread synthesis. Verdicts: REUSE (as-is) / REPURPOSE +> (changed role) / EXTEND (defined addition) / RETIRE (superseded, successor +> named) / NEW (missing piece) / BLOCKED (external). Per-file granularity: +> `MODULE-TABLE.md`. Collapse opportunities: `ENTROPY-MILESTONES.md`. + +## Status: FINDING (consumers section lands with the consumer audit) + +--- + +## 1. lance-graph-contract (the wire truth) + +| Item | Verdict | V3 mapping | +|---|---|---| +| `MailboxId` (collapse_gate.rs:121) | REUSE | the mailbox addressing handle; survives the emission tombstone | +| `mul::GateDecision` {Flow/Hold/Block} (mul.rs:138) | REUSE | **the LIVE kanban gate** — `KanbanColumn::advance_on_gate` consumes THIS one | +| `collapse_gate::GateDecision` + `MergeMode` | REPURPOSE | per-row write-merge gate, per-mailbox-reachable via `mailbox_owner()`; doc vocab still says "blackboard/BindSpace" (stale prose, live mechanism) | +| `CollapseGateEmission` | RETIRE | already tombstoned (PR #477); comment-only remains | +| `NodeGuid/EdgeBlock/NodeRow` 16\|16\|480 (canonical_node.rs) | REUSE | CANON, const-asserted | +| `ValueTenant::Kanban` 8 B @[144,152) | REUSE | the coded per-row half of "one mailbox = one board as tenant" | +| `BUILTIN_READ_MODES` + `_LEGACY` aliases | REUSE | textbook I-LEGACY discipline; retirement = corpus proof (W6) | +| `TailVariant::{V1,V2,V3}` + read-mode registry | REUSE/EXTEND | classid → {tail, value_schema, edge_codec}; the maturity step toward the full ClassView focus lens | +| `FacetCascade`/`FacetTier`/`CascadeShape`/`hi_chain/lo_chain` (facet.rs) | REUSE | **the coded 4+12 atom** — see le-contract.md §5 | +| `hhtl.rs` NiblePath + `from_guid_prefix{,_v2,_v3}` | REUSE | dual-form fold + V3 both-bytes routing, falsifier-tested | +| `ogar_codebook.rs` CLASSID_ORDER=CanonHigh + compat | REUSE | the shipped flip; involution proven | +| `rbac.rs` ClassGrant via `classid_canon_compat` | REUSE | canon-keyed grants; no mailbox coupling (correct) | +| `orchestration.rs` StepDomain::Kanban | REUSE | the D-MBX seam's step-routing domain | +| StepDomain::{Crew,N8n} | REPURPOSE | reserved-dormant post-eviction — needs an in-file doc note (doc-only fix) | +| `thinking.rs` 36 styles/τ/FieldModulation | REUSE | canonical style taxonomy (the 36-lens catalogue post-P4) | +| `jit.rs` StyleRegistry/JitTemplate | BLOCKED | n8n-era orphan, zero implementors; successor = the template stack (W3); fold or retire when ExecTarget::Jit is deprecated | +| `a2a_blackboard.rs` | REUSE | Layer-1 per-round expert bus — ephemeral, NOT a singleton sink | +| `cam.rs`, `nars.rs`, `mul.rs` i4_eval, `plan.rs` | REUSE | orthogonal to the ruling; clean | +| **0x1000 adoption monitor (counter/scanner)** | NEW | constants exist; no counting code anywhere in the contract — W6a builds it | + +**Key risks:** GATE-1 name collision (two `GateDecision` types, documented +unresolved); "BindSpace" vocabulary in 4+ doc comments describing +per-mailbox-reachable mechanisms. + +## 2. SoA ground truth (envelope + tenants) + +See `soa_layout/le-contract.md` §5 and `soa_layout/tenants.md` — headline: +the 4+12 facet is CODED; `ENVELOPE_LAYOUT_VERSION = 2`; Full schema = 152 B +of 480 (RESERVE-DON'T-RECLAIM headroom); **`SoaEnvelope` trait has ZERO +production implementors** (MailboxSoA implements the sibling +`MailboxSoaView/Owner` pair; NodeRow reads via the VALUE_TENANTS table); +Meta/Plasticity widths differ persisted-vs-hot with no parity test; +**MailboxId ≠ NiblePath in code** (doc-only claim — ruling needed). + +## 3. thinking-engine (the DTO ladder producer) + +| Item | Verdict | V3 mapping | +|---|---|---| +| `StreamDto` (Φ) | REUSE | perturbation ingress; standing-async-plan ancestor | +| `dto.rs::ResonanceDto` (Ψ) | REPURPOSE | → `PerturbationDto` (D-PERT-1); blast radius confirmed SMALL: 7 in-crate files + 1 comment-only cross-crate (engine_bridge.rs imports only BusDto) | +| `BusDto` (B) | REUSE | `converged` + `cycle_count` = **the D-MBX-A6 Outcome signal**; never grows ownership fields | +| `ThoughtStruct` (Γ) | EXTEND | persists via owner-stamped envelope (stamping is the boundary's job, not a field) | +| `awareness_dto.rs::ResonanceDto` | REUSE | perspectival (Three-Mountains); KEEPS name; = the Gestalt-resonance MATCHING surface for resonance-based thinking dispatch | +| 4 engines (u8/BF16/i8/f32) | REUSE | near-identical APIs — N→1 collapse candidate (M8) | +| `LayeredEngine::process()` | REUSE | the most complete BusDto producer (3-tier fuse) | +| `DominoCascade` + `CognitiveMarkers` | REPURPOSE | `epiphany` marker = a natural Evaluation→Commit trigger; needs an Outcome adapter | +| `cognitive_stack.rs::GateState` ("collapse gate" doc) | REPURPOSE | intra-cascade SD gate — fine IF intra-mailbox; warden sign-off queued, not assumed | +| `persona.rs::A2AMessage` | BLOCKED | cross-agent handoff shape; warden must rule intra-mailbox (OK) vs cross-mailbox (RESURRECTION) | +| `l4_bridge.rs::commit_to_l4` | BLOCKED | `&mut L4Experience` write with no visible owner stamp — possible ORPHAN-WRITE; needs l4.rs read | +| `cognitive_stack.rs::ThinkingStyle` (12) | RETIRE-toward-contract | a 5th ThinkingStyle copy NOT in the duplication ledger — reconcile before StepMask work (M9) | + +## 4. lance-graph-planner + the executor arms + +| Item | Verdict | V3 mapping | +|---|---|---| +| `style_strategy.rs` (Strategy #18) | EXTEND | the D-MBX-A6 seam is real and honestly deferred ("faking a KanbanMove would be theatre"); `plan()` proven pass-through; the emit edge is the next slice | +| 18-strategy registry | REUSE | **two natures** (operator ruling): DataFusion-routed query strategies + resonance-based thinking (style template × object Gestalt resonance × rung) — never force the latter through DataFusion | +| `mul/` | REUSE | OUTER per-query f64 gate; distinct from the supervisor's i4 S2 gate; composes cleanly | +| `elevation/` + PatienceBudget | REUSE/EXTEND | per-strategy latency budget ≠ the 550 ms Libet anchor — two budget concepts, unification candidate (M12); the load-balancing wiring (W2d) does not exist yet | +| `physical/collapse.rs::CollapseOp` + Strategy #10 | REPURPOSE (rename) | per-query resonance-dispersion gate — NOT the retired singleton; rename candidate (`ResonanceDispersionGate`) to end the vocabulary collision | +| `cache/` + `serve.rs` | REUSE | autocomplete/thinking cache; serve.rs is LAB surface | +| symbiont `SymbiontBoard` (kanban_loop.rs) | EXTEND | POC proves the loop shape + the −550_000 µs Libet anchor **in code**; gap: `phase` is a bare struct field, not tenant-shaped (W2a); Domino work is called, not free-running — the standing-async-plan is NOT yet realized | +| supervisor `KanbanActor` | EXTEND | the most complete arm: S2 atomic MUL-gate-advance, S3 tick, S4 registry delivery, codex #578/#579 fixes tested; gap: unit-proven on TestBoard only, never integration-driven over a real MailboxSoA | +| **ahead-firing batch writer** | NEW | zero code fires a kanban update at write CAST anywhere (grep-confirmed); lands as a new module wrapping BusDto commits, reading `envelope.mailbox_owner()` | +| **delegation cache** | NEW | no delegation concept exists anywhere; small keyed cache inside the batch writer | +| surreal_container | BLOCKED→flip-on | **coordinates RESOLVED 2026-06-16**; remaining block is the deliberate cold-build gate (`BlockedColdBuild`) — arm #2 is one dependency-uncomment away, at a ~10 min cold-build cost | +| `SurrealMailboxView` (read glove) | EXTEND | compiles today, contract-only; read-side of arm #2 is ready | + +## 5. Templates + oracle (W3 stack) + +| Item | Verdict | V3 mapping | +|---|---|---| +| elixir-template DSL (7 OgarAction variants + Custom) | REUSE | deterministic parser; `source_ranking_v1` is the first vertical slice | +| template-runtime ReflexExecutor | REUSE | real dispatch, linear-only — **no control-flow type exists** | +| template-equivalence (Exact/RankOrder live; Semantic fail-closed) | REUSE | the W3 merge gate; honest deferred grading | +| cognitive-compiler ScaffoldCompiler | REUSE | "no trace → no template" enforced in types; synthesis = first probe | +| `FieldMask` (class_view.rs:69) | REUSE | the sibling StepMask mints next to (u64 position bitmask) | +| `StepMask` | BLOCKED/NEW | zero .rs matches — docs-only; D-V3-W3a | +| graph-flow NextAction | REUSE | **6 variants incl. no-op GoBack** (docs said 5 — corrected) | +| **NextAction ↔ OgarAction "1:1"** | CORRECTED | the honest 1:1 is `Step ↔ Task` and `ogar_name() ↔ Task::id()`; Continue/WaitForInput/GoTo/End have NO template-side counterparts — closing this IS the StepMask/adapter work, see compiled-templates.md correction | +| rs-graph-llm `template-task` crate | EXTEND | the adapter's natural home — Task shims exist with literal placeholders; ZERO Cargo dep on lance-graph yet (episodic-arc-task proves the git-dep pattern) | +| `Session` (graph-flow) | EXTEND | 5 fields, no ownership — `mailbox_owner` field = the D-V3-W3b site; SurrealSessionStorage = natural persistence (same kv-lance fork) | +| Rig oracle artifacts | EXTEND | PromptResponse + ToolCall + Extractor exist; SourceSpan-shaped provenance from live runs is the unbuilt half of D-V3-W3c | +| graph-flow-action-ogar `GatedOgarHandler` | REUSE (disambiguate) | a SECOND "OGAR" (contract ActionDef + RBAC/MUL gate) — never conflate with elixir OgarAction (M13) | + +## 6. Shader / convergence / foundation + +| Item | Verdict | V3 mapping | +|---|---|---| +| `engine_bridge.rs::dispatch_busdto` (:239) + `persist_cycle` (:739) | BLOCKED→W4a | THE cast-pairing call sites; write the legacy singleton today, correctly grandfathered until the batch writer (W1) exists | +| `unbind_busdto` (:341) | EXTEND | already feature-gated for the mailbox cutover — the read side is V3-shaped | +| `bindspace.rs::BindSpace` + its call sites (driver.rs, serve.rs, bins, lib.rs re-exports) | RETIRE (W7) | the primer §6 singleton; parity test (mailbox_soa.rs:1145) is the deletion gate | +| `mailbox_soa.rs::MailboxSoA` | REUSE | the shipped successor: soa_view traits, phase field, WriteCell/write_row; needs only the caller-side owner stamp | +| p64-bridge | REUSE | pure stateless mapping, zero BindSpace/ownership deps — clean by design | +| ndarray `MultiLaneColumn` | REUSE (HW) | the LE lane carrier; repurpose opportunity: back MailboxSoA's `Box<[u64]>` identity planes (64 B-aligned) | +| ndarray hpc (fingerprint/cascade/blackboard/read_bgz7) | REUSE (HW) | hardware-tier; causal_diff.rs "self-reinforcement LoRA" flagged for a leak-check read | +| ladybug-rs bind_space + CogRedis | RETIRE (their repo) | pre-V3; zero SoaEnvelope adoption confirmed; contract pulls only (W5e) | + +## 7. Consumers (q2 / MedCare-rs / woa-rs / openproject-nexgen-rs / OGAR / smb-office-rs) + +Full audit: `soa_layout/consumer-map.md`. Digest: + +| Consumer | Classid | Writes | Verdict | +|---|---|---|---| +| openproject-nexgen-rs | T1 reference quality (pure re-exports; bit math only in round-trip tests) | none (pre-persistence) | REUSE | +| MedCare-rs | T1 (auth via rbac membrane, never hardcodes) | none yet — `medcare-soa` writer forthcoming | REUSE + **born-stamped gate (W5h)** | +| OGAR | T2 (the canonical composer) | codegen text only | REUSE + **emit.rs 3× `as u16` post-flip mislabel (W5g)** | +| q2 | REUSE (osint-bake, BodyV3 dual-alias = fleet-best patterns) + T3 interim (cpic, fma) | bakes only — BOOTSTRAP-OK; **`data/osint-v3` codebook is stale pre-flip (latent, W5i/M22)** | REUSE/REPURPOSE | +| woa-rs | T3 unwired module (zero callers; Phase-3 doc points at render_classid) | none (MySQL writer-parity world) | EXTEND | +| smb-office-rs | T4 — never entered the classid ladder (EntityKey strings) | **ORPHAN-WRITE: live `LanceConnector::upsert`, no stamp/classid/envelope — W5f, the first live migration** | BLOCKED | + +Cross-cutting: no write-on-behalf adoption anywhere (expected — the batch +writer doesn't exist); the "all consumer writes are bakes" assumption was +FALSIFIED by smb-office-rs (write-on-behalf.md corrected accordingly). + +--- + +## Cross-cutting verdict summary + +- **REUSE dominates** — the ruled model is mostly wired-not-invented, as + the convergence doctrine predicted. The load-bearing NEW pieces are + exactly three: batch writer + delegation cache (W1), board-as-tenant + type (W2a), StepMask + control-flow closure (W3a/b). +- **The three honest gaps** between doc and code: SoaEnvelope trait + unimplemented in production; MailboxId≠NiblePath; NextAction↔OgarAction + not 1:1. All three are now recorded where the next session will look. +- **Vocabulary debt is the top footgun class**: CollapseGate×3, + GateDecision×2, BindSpace×3, OGAR×2, Blackboard×2, ThinkingStyle + 12-vs-36 — see ENTROPY-MILESTONES for the collapse ledger. diff --git a/.claude/v3/ENTROPY-MILESTONES.md b/.claude/v3/ENTROPY-MILESTONES.md new file mode 100644 index 000000000..38d070f59 --- /dev/null +++ b/.claude/v3/ENTROPY-MILESTONES.md @@ -0,0 +1,61 @@ +# Entropy Milestones — the systematic N→1 collapse ledger + +> An entropy milestone is a point where **N parallel representations of one +> concept collapse to 1 canonical representation**, with (a) the N named, +> (b) the canonical survivor named, (c) a **mechanical gate** that proves the +> collapse is complete (a grep, a range count, a parity test — never a +> claim). Aliases during transition don't count against the collapse; they +> are the mint-forward tax and retire on their own proof. +> +> Sources: the 2026-07-02 mapping fleet's entropy_candidates + the operator +> ruling arc. Status: SHIPPED / IN-FLIGHT / QUEUED / RULING-NEEDED. + +## Status: FINDING (ledger; append rows, update Status only) + +--- + +## Shipped / in-flight collapses + +| # | N representations | → Canonical survivor | Mechanical gate | Status | +|---|---|---|---|---| +| M1 | 2 classid split orders (canon-low legacy vs canon-high) | `CLASSID_ORDER = CanonHigh` + `_LEGACY` read aliases | corpus scan: zero old-form rows → alias retirement; adoption 100% → P4 (ONE two-metric range-count tool, W6a) | SHIPPED (#628 fleet); gate tool QUEUED | +| M2 | 2 concepts sharing the `ResonanceDto` name (mechanical Ψ field vs perspectival Three-Mountains) | Ψ → `PerturbationDto` (D-PERT-1); perspectival keeps the name | rename lands w/ deprecated alias; grep `dto::ResonanceDto` = alias-only; blast radius confirmed 7 files + 1 comment | QUEUED (small, mechanical) | +| M3 | implicit/undeclared write ownership | ONE stamp: `SoaEnvelope::mailbox_owner()` + cast pairing | `/v3-audit` check 4 = zero unstamped online writes; warden OWNED verdicts | stamp SHIPPED; enforcement gated on W1 batch writer | +| M4 | singleton `BindSpace` sink + per-mailbox `MailboxSoA` coexisting | `MailboxSoA` per mailbox | parity test (mailbox_soa.rs:1145) green + engine_bridge cutover → **W7 deletes bindspace.rs**; grep `Arc` = zero | IN-FLIGHT (successor shipped; cutover pending W1) | +| M5 | cross-mailbox carriers (Vsa16k-as-carrier, Baton, CollapseGateEmission, emit()) | zero-copy envelope; Lance columnar I/O = the only byte writer | resurrection grep (`/v3-audit` check 2) = tombstone comments only | SHIPPED (PR #477 tombstone) | +| M6 | 3+ tail shapes read ad-hoc | classid-keyed `ReadMode` registry {tail_variant, value_schema, edge_codec} | every reader routes `classid_read_mode()`; DEFAULT documented TEMPORARY | SHIPPED (registry); DEFAULT retirement open | + +## Queued collapses (fleet-discovered, gates defined) + +| # | N representations | → Canonical survivor | Mechanical gate | Status | +|---|---|---|---|---| +| M7 | 2 column-geometry systems (`SoaEnvelope` trait [zero production impls] vs `VALUE_TENANTS` table + `MailboxSoaView/Owner`) sharing ColumnDescriptor types by convention | ONE: production types implement SoaEnvelope, or SoaEnvelope is re-scoped as the spec/descriptor surface (ruling) | grep `impl SoaEnvelope for` ≥1 production type, or the trait doc names its non-trait role; W1 wiring decides | RULING-NEEDED (feeds W1) | +| M8 | 4 near-duplicate thinking engines (u8/BF16/i8/f32 — same 7-method API) | one generic/enum-dispatched engine (BuiltEngine already half-unifies) | the 4 structs become thin type aliases/params; parity suite green across dtypes | QUEUED | +| M9 | 5+ `ThinkingStyle` copies (contract 36 canonical; thinking-engine 12 is a NEW uninventoried copy; +3 known ledger entries) | contract `thinking.rs` 36-style taxonomy | grep non-contract ThinkingStyle defs = re-exports only; duplication ledger row closed | QUEUED (blocks StepMask catalogue work) | +| M10 | 2 compiled-dispatch stacks (jit.rs n8n-era StyleRegistry [orphaned] vs ExecTarget::Elixir recipe_kernels [exercised]) | the W3 template stack (elixir-template triple + StepMask) | jit.rs either implements against the template stack or retires; ExecTarget::Jit path documented | QUEUED (W3) | +| M11 | 2 kanban-phase representations (SymbiontBoard bare `phase` field vs `KanbanTenant` bytes) | tenant-shaped everywhere (the W2a board-as-tenant type + lane) | POC reads/writes phase through the tenant; grep bare-field phase = zero outside tests | QUEUED (W2a) | +| M12 | 2 budget concepts (elevation `PatienceBudget` per-strategy vs the −550_000 µs Libet anchor per-cycle) | one budget allocator (elevation extended as the 550 ms scheduler, W2d) | elevation reads/writes the Libet anchor; doc cross-ref both ways | QUEUED (W2d) | +| M13 | 2 "OGAR action" concepts (elixir_template::OgarAction enum vs contract `action::ActionDef`+CapabilityExecutor RBAC gate) | keep BOTH (different jobs) — collapse the NAME ambiguity via explicit disambiguation in every doc/brief | guardrails §2 row (done) + compiled-templates.md disambiguation; grep unqualified "OGAR action" in briefs = zero | IN-FLIGHT (doc-side done this PR) | +| M14 | 3 `BindSpace` concepts (shader-driver singleton SoA; ladybug 8:8 dispatch table; graph/spo/merkle store) + stale "BindSpace" prose | scoped names; shader singleton RETIRES (M4); prose sweep to MailboxSoA vocabulary | grep bare `BindSpace` in doc comments describing per-mailbox mechanisms = zero | QUEUED (doc sweep + W7) | +| M15 | 2 `GateDecision` types (mul::{Flow,Hold,Block} live kanban gate vs collapse_gate::{gate,merge} write-merge) — the documented GATE-1 clash + 3 "CollapseGate" vocabulary users | rename the write-merge one (e.g. `WriteMergeGate`) and/or the dispersion op (`ResonanceDispersionGate`); mul::GateDecision keeps the name | grep `GateDecision` resolves to ONE type per import; cycle_accumulator GATE-1 note closed | RULING-NEEDED (rename choice) | +| M16 | 3 independently-invented fail-closed deferral patterns (RuntimeError::NotImplemented / EquivalenceClass::Failure-note / CompileError::NotImplemented) | one documented convention (not a new abstraction) | a §-note in compiled-templates.md naming the pattern; new deferrals cite it | QUEUED (doc-only) | +| M17 | 2 control-flow vocabularies with a FALSE 1:1 claim (graph-flow NextAction×6 vs template linear-only) | honest mapping: Step↔Task + ogar_name()↔Task::id(); control flow closed by StepMask/ControlSignal (W3a/b) | adapter tests replay a template with WaitForInput/End/GoTo semantics; compiled-templates.md corrected (this PR) | IN-FLIGHT (doc corrected; code W3) | +| M18 | 2 lifecycle vocabularies (planner sigma chain Ω→Δ→Φ→Θ→Λ vs KanbanColumn 6 phases) with no documented mapping | a documented mapping (or an explicit "orthogonal" ruling) | one table in mailbox-kanban-model.md; both modules cross-ref it | RULING-NEEDED | +| M19 | duplicated consumer routes (per multi-anchor AST: N duplicated routes = one canonical concept) | 1 canonical concept (classid) + N ClassView skins | the duplication anchor's vote report per consumer; mints reviewed | QUEUED (per-consumer, W5; detector = E-RUFF-ODOO-MULTI-ANCHOR-AST) | +| M20 | 64-bit awareness cramming (CausalEdge64 3/4-bit mantissa) alongside facet payloads | 96-bit facet payloads, classview-lens-selected (E-V3-CLASSVIEW-FOCUS-LENS) | no NEW CausalEdge64 bit-field semantics (review gate); residual role ruling | IN-FLIGHT (ruling recorded; scoping [H] open) | +| M21 | 3 dep-free hand-copies of the 16-byte NodeGuid LE encoder (q2 cpic, q2 fma/converge.rs, woa-rs erp/canon.rs — each "byte-identical", zero shared code) | one zero-dep `canon-node-bytes` extraction all three import | byte-parity test vs contract NodeGuid; grep local encoders = imports only | QUEUED (W5) | +| M22 | 2 divergent q2 OSINT V3 bakes (crates/osint-bake canon-high 0x0700_0000 vs data/osint-v3 STALE pre-flip 0x1000_0700 dual-GUID scheme) | one canon-high bake against osint_classview.rs's 0x0700/0x0701 reservation | re-bake; grep pre-flip forms in q2 data/ = zero (or dual-alias-read only) | QUEUED (W5; latent until a reader assumes canon-high) | +| M23 | 2 write-path doctrines coexisting (owner-stamped V3 writes vs smb-office-rs `LanceConnector::upsert` — the ONE live online consumer write, no stamp/classid/envelope) | all online consumer writes routed through the batch-writer cast | consumer-map §2 table shows zero ORPHAN-WRITE rows; warden green fleet-wide | QUEUED (W5 first live migration; medcare-soa writer BORN stamped as the prevention half) | + +## The meta-rule (why this ledger exists) + +Every milestone above was found EITHER by an operator ruling OR by the +duplication/parallel-representation smell — never by feature pressure. The +V3 migration is, structurally, this ledger: the substrate is done when the +QUEUED column is empty and every gate is green. New candidate rows: append +below with the same four columns; a row without a mechanical gate is not a +milestone, it's a wish. + +Cross-ref: COMPONENT-MAP.md (per-subsystem evidence), INTEGRATION-PLAN.md +(waves that execute the rows), board E-* entries (canonical ruling texts), +docs/TYPE_DUPLICATION_MAP.md (the pre-V3 duplication ledger M9 extends). diff --git a/.claude/v3/INTEGRATION-PLAN.md b/.claude/v3/INTEGRATION-PLAN.md new file mode 100644 index 000000000..8f4fc4cdf --- /dev/null +++ b/.claude/v3/INTEGRATION-PLAN.md @@ -0,0 +1,128 @@ +# V3 Substrate Integration Plan — waves W0–W6 + +> **Status:** ACTIVE (W0 ships with this PR; W1–W6 sequenced below) +> **Date:** 2026-07-02 · **Authority:** operator rulings of 2026-07-02 +> (board entries E-MAILBOX-KANBAN-NO-COLLAPSEGATE, E-COMPILED-THINKING-TEMPLATES, +> E-DTO-LADDER-OWNERSHIP-SPLIT, E-TWO-RESONANCES-SPLIT, E-V3-MARKER-IS-A-MONITOR, +> E-CLASSID-* arc) under standing full authorization. +> **Index entry:** `.claude/board/INTEGRATION_PLANS.md` (prepended same commit). +> **Deliverable dashboard:** STATUS_BOARD rows `D-V3-*` + the existing +> D-MBX-A6 / D-PERT-1 / D-CC-* / D-VCW-* / D-CCF-4 rows this plan adopts. + +The organizing principle is unchanged from v3-convergence-wiring: **wire, +don't invent** — every wave below wires machinery that already exists +(envelope, kanban types, DSL triple, graph-flow, classid helpers) into the +ruled model. Anything that looks like a new layer is a defect in this plan. + +--- + +## Wave map (dependency order) + +``` +W0 ratify/document ──► W1 envelope+ownership ──► W2 kanban executors ──► W5 consumers + │ │ + └──► W4 DTO ladder └──► W3 templates ──► (catalogue ⤳ W6/P4) + W6 monitor & retirement (P4 = operator checkpoint) +``` + +Rule of thumb: **W1 is the keystone** — the cast pairing +(`cast(on_behalf = envelope.mailbox_owner(), payload = BusDto)`) is what +every later wave consumes. W4 can run any time (rename + doc). W6's scanner +can be built early; its retirements only fire on proof. + +--- + +## W0 — Ratify & document (THIS PR) + +| D-id | Deliverable | State | +|---|---|---| +| D-V3-W0a | `.claude/v3/` tree (README, this plan, COMPONENT-MAP, ENTROPY-MILESTONES, MODULE-TABLE, soa_layout/*) | this commit | +| D-V3-W0b | V3 awareness layer: knowledge docs, 4 agent cards (`v3-*`), `/v3` skill, `/v3-audit` command, CLAUDE.md + BOOT.md entrypoints | this commit | + +Gate: board hygiene same-commit (INTEGRATION_PLANS prepend, STATUS_BOARD +rows, AGENT_LOG, handover pointer). + +## W1 — Envelope & ownership (the keystone) + +| D-id | Deliverable | Notes | +|---|---|---| +| D-V3-W1a | `SoaEnvelope::mailbox_owner()` stamp | **SHIPPED** (this branch) — default 0 = bootstrap, zero-fallback ladder | +| D-V3-W1b | **Batch writer**: `cast(on_behalf, payload)` pairing + AHEAD kanban update fired at cast (never at write-ack) | new module, planner-adjacent; the ONLY sanctioned online write shape | +| D-V3-W1c | **Delegation cache**: cast id vs envelope stamp; hit = proceed, miss = resolve once + cache | lives in the batch writer; consumers never re-implement | +| D-V3-W1d | MailboxId minting path (non-zero owners; `debug_assert` uniqueness in default basin) | per CANON zero-fallback ladder | +| D-V3-W1e | Probe: ahead-update ordering test (kanban board reflects intent BEFORE Lance ack) + delegation-miss test | probe-first; W2 consumes | + +Gates: `v3-envelope-auditor` LAYOUT-CLEAN; `v3-mailbox-warden` OWNED on the +writer's own paths; no serialization on the hot path (zero-copy invariant). + +## W2 — Kanban executors (two arms + structural owner) + +| D-id | Deliverable | Notes | +|---|---|---| +| D-MBX-A6 | `Outcome → KanbanMove` adapter emit in `lance-graph-planner strategy/style_strategy.rs` (arm #1) | adopts existing STATUS_BOARD row; converged/cycle_count from BusDto feed it | +| D-V3-W2a | **Per-mailbox kanban board as TENANT** (type + lane; sibling of per-row `KanbanTenant`) | envelope-auditor gate: field-isolation matrix | +| D-V3-W2b | Supervisor wiring: `kanban_actor.rs` applies moves via `MailboxSoaOwner::advance_phase` (sole mutator); ractor stays spawn-only | structural-owner proof unchanged | +| D-V3-W2c | symbiont arm (SurrealDB-on-kv-lance): kanban updates as KV transactions | **CORRECTED 2026-07-02:** coordinates RESOLVED 2026-06-16 — the remaining block is the deliberate cold-build gate (`BlockedColdBuild`, surreal_container Cargo.toml dep commented out to keep `cargo check` fast); arm #2 = one dependency-uncomment + ~10 min cold build away; POC = `symbiont/kanban_loop.rs`; read glove `SurrealMailboxView` compiles today | +| D-V3-W2d | 550 ms budget: load-balancing hooks into planner `elevation/` (extend, don't shadow) + budget instrumentation | 64k–256k SoA prioritization | +| D-V3-W2e | **Sub-µs dispatch speed probe**: rs-graph-llm (graph-flow) vs SurrealQL-on-kv-lance, same kanban/thinking hot path, measured | operator 2026-07-02: "the planner is too slow for sub-microsecond"; winner owns the hot-path `ExecTarget` (Native/Jit/SurrealQl/Elixir already coded, kanban.rs); planner = slow/plan path either way; truth-architect reviews the numbers | + +Gate: W1b/W1c shipped (moves fire off casts). Standing rule: updates +reprioritize, never gate — a missing update must not deadlock a cycle. + +## W3 — Compiled templates + +| D-id | Deliverable | Notes | +|---|---|---| +| D-V3-W3a | `StepMask` in contract (sibling of FieldMask; selection, not control flow) | zero-dep | +| D-V3-W3b | ElixirTemplate → graph-flow `GraphBuilder` adapter; Session threads the MailboxId (ownership inheritance) | rs-graph-llm seam; Iron-Rule-5-style contract pull | +| D-V3-W3c | Rig oracle node: FailureTicket → oracle run → `template-equivalence` gate → `cognitive-compiler` compile-down into catalogue | D-VCW-7 lineage; deterministic-first | +| D-V3-W3d | Catalogue keyed INTERNALLY (template-id); classid custom-half keying deferred to W6/P4 | styles-as-lenses F2 lands here post-P4 | + +Gate: replay equivalence green on every template change (template-smith rule). + +## W4 — DTO ladder (parallel, any time) + +| D-id | Deliverable | Notes | +|---|---|---| +| D-PERT-1 | Rename `dto.rs::ResonanceDto` → `PerturbationDto` (~9 files thinking-engine + cognitive-shader-driver engine_bridge), deprecated alias | adopts existing row; "cascade" key-tier vocabulary NOT renamed (canon) | +| D-V3-W4a | BusDto/cast pairing call sites in cognitive-shader-driver (consumes W1b) | BusDto never grows ownership fields — warden check 2 | +| D-V3-W4b | L4 learning loop doc-to-code check: converged residue → owner-stamped tenant lane → template reads row next cycle | probe over an end-to-end cycle | + +## W5 — Consumer adoption (write-on-behalf fleet-wide) + +| D-id | Deliverable | Notes | +|---|---|---| +| D-V3-W5a | q2: CI re-bakes (`osint-bake`, `fma`) + `body.soa` re-release; drop `FMA_V3_CLASSID_LEGACY` from BodyV3.tsx | handover continuation §1 | +| D-V3-W5b | q2 cpic contract pull with mereology (kinds → cascade positions under `0x0E01_1000`) — dissolves interim `0x0E01_000N` + `ISS-Q2-CPIC-MIRROR` | handover F3 | +| D-V3-W5c | Bake pipelines annotated bootstrap-owner; NEW online consumer writes route through the batch writer | per write-on-behalf.md interim rules | +| D-V3-W5d | Probes D-VCW-3 (P7 render, bitmask→askama) + D-VCW-5 (cascade3 nibble falsifier) — q2 gate already WAIVED | validate V3 keys end-to-end | +| D-V3-W5e | Stragglers: ladybug-rs (pre-V3/rustynum-era) contract pulls only | never bridges | +| D-V3-W5f | **smb-office-rs ORPHAN-WRITE migration**: `LanceConnector::upsert` (smb-bridge/lance.rs:176-201, live caller smb-woa/customer.rs:189) — the ONE online consumer write; stamp + batch-writer routing when W1 lands | consumer-map §2; until then explicitly flagged, never silently grandfathered | +| D-V3-W5g | OGAR `emit.rs` post-flip fix: 3× `facet_classid() as u16` doc-label → `concept_of(...)` (emit_rust/csharp/python) + regen check | 1 line × 3; propagates into every generated SDK until fixed | +| D-V3-W5h | MedCare-rs `medcare-soa` writer **born stamped** (design gate before first merge) | prevention half of M23 | +| D-V3-W5i | q2 dual-bake collapse: retire/re-bake stale pre-flip `data/osint-v3` codebook into the canon-high osint-bake (M22) | latent I-LEGACY shape | + +## W6 — Monitor & retirement (proof-gated) + +| D-id | Deliverable | Notes | +|---|---|---| +| D-V3-W6a | **Adoption/corpus scanner**: ONE two-metric range-count tool (canon-high adoption % + old-form row count) over Lance datasets | metrics are range counts over the DECODED classid u32 (or an order-preserving BE key) — never raw LE key-byte prefixes; old-form = ALL THREE legacy shapes incl. `0xAAAA_DDCC` render-prefix-high (codex #629 sharpenings; routing.md §1/§5) | +| D-CCF-4 | `0x1000` marker retirement (P4) — trigger DEFINED: adoption reads 100% | **operator checkpoint** | +| D-V3-W6b | Legacy alias retirement (`CLASSID_*_LEGACY`, compat reader narrowing) | corpus proof = zero old-form rows; never before | +| D-V3-W6c | Custom half opens: 64k ClassView render catalogue + template catalogue dispatch (completes W3d/F2) | post-P4 only | + +--- + +## Standing gates (every wave) + +1. **Probe-first** — mechanism lands after its failing probe (workspace rule). +2. **Warden + auditor green** on any write-path / layout diff (`/v3-audit` is the cheap pre-check). +3. **Board hygiene same-commit** (STATUS_BOARD row transitions, EPIPHANIES for findings). +4. **Model economy** — Sonnet 5 grindwork, Fable/Opus decisions (operator ruling 2026-07-02). Every Sonnet brief carries the §1 preamble of `knowledge/sonnet-worker-guardrails.md` verbatim; §5 escalation triggers are STOP+report, never worker-resolved. +5. **Wire, don't invent** — a new struct/trait/layer proposal must first fail the "existing machinery" search (COMPONENT-MAP is that search, precomputed). + +## What this plan supersedes / adopts + +- Adopts (does not duplicate): D-MBX-A6, D-PERT-1, D-CC-RUNTIME/EQUIV/COMPILER rows, D-VCW-3/5/7, D-CCF-4. +- Extends: `v3-convergence-wiring-v1` (its seam list is W1–W3's ancestry) and `soa-value-tenant-migration-v2` (Phase-2 tenant shaping proceeds under W2a's tenant discipline). +- Supersedes in prose only: any remaining CollapseGate-as-singleton framing in older docs (primer §6 table governs). diff --git a/.claude/v3/MODULE-TABLE.md b/.claude/v3/MODULE-TABLE.md new file mode 100644 index 000000000..1f3e3f970 --- /dev/null +++ b/.claude/v3/MODULE-TABLE.md @@ -0,0 +1,333 @@ +# Module Table — per-file census of the three core crates + +> Operator-requested overview (2026-07-02): per file — visibility, what it +> consumes, what it emits, its LE contract, function/benefit, tech debt, +> duplication, and its V3 wave. Produced by the 21-chunk Sonnet census +> fleet; assembled mechanically. Wave tags: W0–W6 (see INTEGRATION-PLAN), +> CORE = V3-neutral query engine, HW = SIMD/codec hardware, LEGACY = +> superseded singleton/baton artifact. + +## Status: FINDING — 304 files censused + +**Rollup:** 51 files carry an LE/byte surface · 146 carry +cited tech debt · 78 carry known duplication · wave mix: CORE:206, HW:31, W1:22, W3:13, LEGACY:9, W5:8, W4:7, W2:6, W6:2 + + +## lance-graph (108 files) + +| File | Vis | Consumes | Emits | LE contract | Function / benefit | Tech debt | Duplication | V3 wave | +|---|---|---|---|---|---|---|---|---| +| `ast.rs` | pub | serde::{Deserialize,Serialize}; std::collections::HashMap | CypherQuery, GraphPattern, NodePattern, RelationshipPattern, ValueExpression, BooleanExpression | none | Defines the Cypher AST (patterns, clauses, expressions, distance metrics) parsed by parser.rs and consumed by logical_plan.rs | none | none | CORE query engine — Cypher AST types | +| `cam_pq/ivf.rs` | mixed | Vec vectors/queries; std::cmp::Ordering | IvfConfig, IvfIndex::train/assign/probe, IvfCamResult, merge_partition_results | none | K-means IVF coarse partitioning to shrink billion-scale search before CAM-PQ stroke cascade | kmeans is a standalone copy of ndarray's cam_pq k-means (per own doc comment) | kmeans duplicates ndarray::hpc::cam_pq k-means algorithm (stated in file comment) | HW (SIMD/codec hardware) | +| `cam_pq/jitson_kernel.rs` | pub | thresholds/top_k/lance_table strings; feeds ndarray jitson::template::from_json | cam_pq_cascade_template, cam_pq_full_adc_template, select_kernel_template (JSON strings) | none | Generates JITSON JSON configs so ndarray's Cranelift JIT compiles AVX-512 CAM-PQ ADC scan kernels | none | none | HW (SIMD/codec hardware) | +| `cam_pq/mod.rs` | pub | none (module declarations only) | pub mod ivf, jitson_kernel, storage, udf | none | Crate-root doc + module wiring: lance-graph's CAM-PQ layer wraps ndarray's cam_pq codec for storage/UDF/IVF/JIT | none | none | HW (SIMD/codec hardware) | +| `cam_pq/storage.rs` | pub | arrow::datatypes/arrow_array builders; ids/cams/codebook Vec>> inputs | cam_vectors_schema, cam_codebook_schema, build_cam_batch/build_codebook_batch, extract_*, CamStorageStats | FixedSizeBinary(6) CAM byte layout; no LE int packing, byte-level fingerprint schema | Arrow/Lance schema + RecordBatch builders for CAM fingerprints (6B) and codebook persistence, ADC storage stats | .expect()/.unwrap() on column downcast+lookup in extract_* (panics on malformed batch) | supersedes bgz-tensor's raw CMPQ/CMFP binary format (cam_pq_calibrate.rs) per own doc comment | HW (SIMD/codec hardware) | +| `cam_pq/udf.rs` | mixed | arrow::array, datafusion ScalarUDF/ColumnarValue, vector_ops from datafusion_planner | CamDistanceTables, create_cam_distance_udf, create_cam_heel_distance_udf, register_cam_udfs | none | Registers cam_distance/cam_heel_distance DataFusion scalar UDFs for ADC nearest-neighbor scoring in Cypher/SQL | none | none | CORE (V3-neutral query engine) | +| `case_insensitive.rs` | pub | std::collections::HashMap, std::hash::{Hash,Hasher} | CaseInsensitiveStr, CaseInsensitiveMap, qualify_column(), CaseInsensitiveLookup trait | none | Case-insensitive string/HashMap utilities for labels & properties; qualify_column() builds alias__property join keys | none | none | CORE query engine — case-insensitive identifiers | +| `config.rs` | pub | crate::error::{GraphError, Result}; serde | GraphConfig, GraphConfigBuilder, NodeMapping, RelationshipMapping | none | Maps Lance dataset labels/relationship types to id/property fields; builder normalizes keys lowercase and validates | 2 TODOs: make node_mappings/relationship_mappings private to enforce lowercase-key invariant | none | CORE query engine — graph-to-dataset mapping config | +| `datafusion_planner/analysis.rs` | pub | ast::RelationshipDirection, logical_plan::LogicalOperator tree | QueryAnalysis, RelationshipInstance, PlanningContext, analyze() | none | Phase 1: walks logical plan, assigns unique relationship-instance IDs and var-to-label map to avoid column name conflicts | none | none | CORE (query engine planner internals) | +| `datafusion_planner/builder/aggregate_ops.rs` | internal | logical_plan::ProjectionItem, expression::{to_df_value_expr,contains_aggregate} | DataFusionPlanner::build_project_with_aggregates() | none | splits projections into group/aggregate exprs, builds DataFusion aggregate+projection plan with alias reuse | none | none | CORE (datafusion planner builder) | +| `datafusion_planner/builder/basic_ops.rs` | internal | PlanningContext, LogicalOperator (Filter/Project/Sort/Limit/Offset/Unwind) | build_filter/build_project/build_distinct/build_sort/build_limit/build_offset/build_unwind | none | translates basic relational Cypher operators into DataFusion LogicalPlanBuilder calls, incl. UNWIND via unnest_column | none | none | CORE (datafusion planner builder) | +| `datafusion_planner/builder/expand_ops.rs` | internal | join_ops::{SourceJoinParams,TargetJoinParams}, analysis::PlanningContext | build_expand/build_variable_length_expand/build_fixed_length_path/build_expand_on_plan | none | graph traversal: single-hop Expand as joins; variable-length paths unrolled per hop count and UNIONed | none | none | CORE (datafusion planner builder) | +| `datafusion_planner/builder/helpers.rs` | internal | logical_plan::LogicalOperator tree | DataFusionPlanner::extract_variables() / collect_variables() | none | recursively collects node and relationship variable names from a logical plan tree for join-key inference | none | none | CORE (datafusion planner builder) | +| `datafusion_planner/builder/join_builder.rs` | internal | case_insensitive::qualify_column, analysis::PlanningContext | build_join(), infer_join_keys() | none | builds Cross/Inner/Left/Right/Full DataFusion joins, inferring keys from shared node/relationship variables | none | none | CORE (datafusion planner builder) | +| `datafusion_planner/builder/mod.rs` | internal | logical_plan::LogicalOperator, analysis::PlanningContext, sibling submodules | DataFusionPlanner::build_operator() dispatcher; declares aggregate_ops/basic_ops/expand_ops/helpers/join_buil… | none | Phase 2 entry point: matches each LogicalOperator variant and dispatches to the specialized builder submodule | none | none | CORE (datafusion planner builder) | +| `datafusion_planner/config_helpers.rs` | internal | config::{NodeMapping,RelationshipMapping}, lance_graph_catalog::GraphSourceCatalog | get_relationship_mapping(), get_target_node_mapping(), get_catalog() | none | case-insensitive config/catalog lookup helpers, incl. label inference for synthetic _temp_* multi-hop variables | none | none | CORE (datafusion planner builder) | +| `datafusion_planner/cost_estimation.rs` | pub | graph::blasgraph::hdr::Band | band_selectivity(), should_use_cascade(), full_scan_cost(), cascade_scan_cost(), choose_scan_strategy(), Scan… | none | cost model choosing cascade-accelerated vs full sequential scan for Hamming predicates using sigma-band selectivity | none | none | CORE (query optimizer cost model) | +| `datafusion_planner/expression.rs` | internal | ast::{BooleanExpression,ValueExpression,PropertyValue}, case_insensitive::qualify_column, udf | to_df_boolean_expr(), to_df_value_expr(), contains_aggregate(), to_cypher_column_name() | none | translates Cypher AST boolean/value expressions (comparisons, arithmetic, aggregates, LIKE/CONTAINS, vectors) to DataFusion Expr | TODO(#107) upgrade unsupported-aggregate NULL fallback to hard error; TODO on COUNT(var) limitation for non-n… | none | CORE (expression translation) | +| `datafusion_planner/join_ops.rs` | internal | case_insensitive::qualify_column, config::{NodeMapping,RelationshipMapping}, analysis::RelationshipInstance | SourceJoinParams/TargetJoinParams, join_source_to_relationship(), join_relationship_to_target(), join_relatio… | none | low-level join-key wiring connecting node scans to relationship scans; handles direction-based key selection and variable-reuse filters | TODO: property filters on reused variable not yet supported (returns PlanError) | none | CORE (datafusion planner builder) | +| `datafusion_planner/mod.rs` | pub | config::GraphConfig, lance_graph_catalog::GraphSourceCatalog, analysis module | GraphPhysicalPlanner trait, DataFusionPlanner struct, DataFusionPlanner::plan() | none | crate's canonical Cypher-to-DataFusion entry point: two-phase Analysis then Build converting LogicalOperator into LogicalPlan | none | none | CORE (query engine planner root) | +| `datafusion_planner/predicate_pushdown.rs` | pub | cost_estimation::{choose_scan_strategy,ScanStrategy}, graph::blasgraph::{hdr::Band,cascade_ops::CascadeScanCo… | HammingPredicate, PushdownAnalysis | none | detects hamming(col,q) | none | Crate-wide error type with snafu Location tracking and From impls bridging DataFusion/Lance/Arrow errors | none | none | CORE query engine — error type | +| `graph/arigraph/episodic.rs` | pub | crate::graph::fingerprint::{hamming_distance,label_fp,Fingerprint}, spo::truth::TruthValue | EpisodicMemory, Episode, UnbundleReport, RebundleReport, UNBUNDLE_HARDNESS_THRESHOLD | none | Capacity-bounded episodic memory: Hamming top-k retrieval, hardness-gated triplet unbundle/rebundle for AriGraph. | none | none | CORE (V3-neutral query engine) | +| `graph/arigraph/language.rs` | pub | super::triplet_graph::{Triplet,TripletGraph} | LanguageBackend trait, ContextBlackboard, BackendChoice, PlanResult, select_backend() | none | Internal/external LLM backend trait + shared ContextBlackboard + DK/temperature-based backend routing policy (P18). | none | none | CORE (V3-neutral query engine) | +| `graph/arigraph/markov_soa.rs` | pub | lance_graph_contract::soa_view::MailboxSoaView | SpoRanks, WaveProjection, SoaWavePrimer, BundleProvenance, RowContribution, best_guess_match() | none | Vocabulary-agnostic fuzzy SoA-window Markov wave projector over MailboxSoaView; deterministic, never asserts truth. | doc admits staging location: 'truly-correct home is still inside the EW64-in-SoA seam' | none | W1 envelope/ownership | +| `graph/arigraph/mod.rs` | pub | episodic/language/markov_soa/orchestrator/retrieval/sensorium/spo_bridge/triplet_graph/witness_corpus/xai_cli… | module re-exports: WitnessCorpus, WitnessEntry, WitnessId, WitnessIndexHashMap (+CamPq under with-cam-pq) | none | AriGraph module root: declares submodules and re-exports the public WitnessCorpus/WitnessEntry surface. | none | none | CORE (V3-neutral query engine) | +| `graph/arigraph/orchestrator.rs` | pub | crate::graph::spo::truth::TruthValue, serde | MetaOrchestrator, MulAssessment, DkPosition, StyleTopology, GraphSensorium, HealingAction, StepResult | none | Meta-Uncertainty Layer + NARS-topology agent orchestrator: adaptive/hardcoded mode switching, DK gating, auto-heal. | duplicates GraphSensorium/HealingAction/diagnose_healing verbatim from sensorium.rs; may be legacy per its doc | GraphSensorium/HealingAction/diagnose_healing duplicated in graph/arigraph/sensorium.rs | CORE (V3-neutral query engine) | +| `graph/arigraph/retrieval.rs` | pub | super::episodic::EpisodicMemory, super::triplet_graph::TripletGraph | OsintRetriever, RetrievalConfig, RetrievalResult, EXTRACTION_PROMPT + 5 other prompt consts | none | Combines BFS graph expansion with fingerprint episodic recall into unified LLM context; verbatim AriGraph prompts. | none | none | CORE (V3-neutral query engine) | +| `graph/arigraph/sensorium.rs` | pub | super::episodic::EpisodicMemory, super::triplet_graph::TripletGraph, serde | GraphSensorium, GraphBias, HealingAction, HealingType, diagnose_healing(), apply_healing() | none | Real-time graph health signals (contradiction/entropy/revision/plasticity) driving MUL self-regulation + auto-heal. | none | GraphSensorium/HealingAction/diagnose_healing duplicated in graph/arigraph/orchestrator.rs | CORE (V3-neutral query engine) | +| `graph/arigraph/spo_bridge.rs` | pub | fingerprint::{dn_hash,label_fp}, spo::builder::SpoBuilder, spo::store::SpoStore, spo::truth::TruthGate | promote_to_spo(), promote_graph_to_spo(), PromoteGate, SpoHandle, canonical_dn() | none | One-way L1(AriGraph warm)->L2(SpoStore cold) promotion writer gated by TruthGate; keys via dn_hash of DN path. | none | none | CORE (V3-neutral query engine) | +| `graph/arigraph/triplet_graph.rs` | pub | fingerprint::{label_fp,Fingerprint}, spo::truth::TruthValue | Triplet, TripletGraph, ContextTag, CounterfactualSpoG, infer_deductions(), detect_contradictions() | none | OSINT triplet graph: BFS association, spatial pathfinding, NARS deduction/contradiction/revision, Pearl rung-2 intervention. | find_path() calls .unwrap() on path.last() (invariant-safe but undocumented) | none | CORE (V3-neutral query engine) | +| `graph/arigraph/witness_corpus.rs` | mixed | ndarray::hpc::cam_pq (feature with-cam-pq), lance_graph_contract::vsa::roles | WitnessCorpus, WitnessEntry, WitnessId, WitnessIndexHashMap, WitnessIndexCamPq, spo_to_fingerprint() | spo: u64 packed s_idx\|p_idx<<8\|o_idx<<16 palette triple; CamFingerprint 6B codes (no to/from_le_bytes) | Peer-witnessed SPO corpus: chain-ordered exact-match HashMap index + optional CAM-PQ ANN index (VSA role-bound Option A). | none | none | HW (SIMD/codec hardware) | +| `graph/arigraph/xai_client.rs` | pub | super::retrieval::{EXTRACTION_PROMPT,PLAN_PROMPT,REFINING_PROMPT}, triplet_graph::{Triplet,TripletGraph}, ADA… | XaiClient, XaiConfig, XaiResponse, parse_triplets(), parse_outdated(), parse_response() | none | xAI/Grok REST client: builds/parses OpenAI-compatible chat completions for extraction, refinement, planning, classification. | hand-rolled JSON parsing (extract_json_string/number, no serde) for xAI responses — fragile to schema drift | none | CORE (V3-neutral query engine) | +| `graph/audio/hhtl_bridge.rs` | pub | super::node::{AudioNode, spectral_l1} | cascade_search(), AudioCascadeLevel, AudioCascadeResult, CascadeStats, assign_route_hints() | none | HEEL/HIP/TWIG/LEAF cascade elimination for audio search via stride+PVQ+palette route table+Base17 L1 distance. | none | none | HW (SIMD/codec hardware) | +| `graph/audio/mod.rs` | pub | hhtl_bridge, node submodules | module wiring only | none | Audio graph module root: wires AudioFrame/PhaseDescriptor into lance-graph AudioNode + HHTL cascade search. | none | none | HW (SIMD/codec hardware) | +| `graph/audio/node.rs` | pub | none (self-contained struct) | AudioNode, TemporalEdge, spectral_l1() | AudioNode::to_bytes/from_bytes: repr(C) 60B layout, per-field to_le_bytes/from_le_bytes (u16 fields) | 60-byte cache-line AudioNode graph vertex: band energies+PVQ+phase+SpiralAddress+palette idx+route hint, byte (de)serialized. | none | none | HW (SIMD/codec hardware) | +| `graph/blasgraph/blasgraph_planner.rs` | pub | blasgraph::{descriptor,matrix,semiring,sparse,typed_graph,types}, logical_plan::LogicalOperator | compile_to_blasgraph(), BlasGraphPlanError | none | Second execution backend: compiles LogicalOperator (ScanByLabel/Expand/VarLengthExpand/Filter) to GrBMatrix mxm traversal. | none | none | CORE (V3-neutral query engine) | +| `graph/blasgraph/cascade_ops.rs` | pub | super::hdr::{Band,Cascade}, super::types::VECTOR_BITS | CascadeScanConfig, hamming_predicate_to_cascade(), estimate_selectivity() | none | Translates Cypher Hamming-distance predicates into sigma-band-calibrated cascade scan config + selectivity estimate. | none | none | CORE (V3-neutral query engine) | +| `graph/blasgraph/clam_neighborhood.rs` | pub | blasgraph::neighborhood::build_scope, blasgraph::types::BitVec (tests) | scent_l1_distance(), scent_hamming_distance(), measure_cluster_radii(), analyze_pareto_convergence(), ParetoA… | none | CLAM ball-tree radius measurement over scent vectors — empirical conjecture test for Pareto-frontier compression convergence. | explicitly a conjecture-validation module ('this is a TEST, not a fact'); Pareto convergence hypothesis uncon… | none | CORE (V3-neutral query engine) | +| `graph/blasgraph/columnar.rs` | pub | arrow_schema::{DataType,Field,Schema} | NodeSchema, EdgeSchema, FingerprintSchema (arrow_schema(), arrow_schema_ref()) | Arrow FixedSizeBinary(2048) plane / (6) seal column widths — schema byte-width contract, no explicit LE fns | Arrow/Lance columnar schemas for cognitive nodes/edges/fingerprints: FixedSizeBinary planes+seals, BF16 edge weights. | none | none | CORE (V3-neutral query engine) | +| `graph/blasgraph/descriptor.rs` | pub | none (std::fmt only) | DescField, DescValue, Descriptor, GrBDesc preset builders (t0/t1/comp/replace/structure) | none | GraphBLAS operation descriptor controlling transpose/mask-complement/replace/structure-mask behavior for mxm/mxv/ewise ops | none | none | CORE (V3-neutral query engine) | +| `graph/blasgraph/hdr.rs` | pub | std::time::Instant (tests only); no external crate deps | isqrt, Band, RankedHit, ShiftAlert, ReservoirSample, Cascade (calibrate/query/observe/recalibrate) | none | Self-calibrating integer-only exposure-meter cascade for Hamming-distance candidate elimination (sigma bands + reservoir quantiles + shift … | none (integer-only by design, no unwraps in hot path) | none | HW (SIMD/codec hardware) | +| `graph/blasgraph/heel_hip_twig_leaf.rs` | pub | super::zeckf64::scent, super::neighborhood::build_scope (tests), super::types::BitVec | heel_search, hip_search, twig_search, leaf_verify, cascade_search, LeafResult, SearchConfig | none | 4-stage HEEL/HIP/TWIG/LEAF neighborhood cascade: scent-byte popcount matching narrows ~10K scope to ~50 candidates before cold verification | none | none | HW (SIMD/codec hardware) | +| `graph/blasgraph/lance_neighborhood.rs` | pub | arrow_schema::{DataType,Field,Schema,TimeUnit}, super::neighborhood::{NeighborhoodVector,Scope,MAX_SCOPE_SIZE} | scopes_schema, neighborhoods_schema, cognitive_nodes_schema, serialize/deserialize_scope_node_ids, serialize_… | serialize/deserialize_scope_node_ids pack node_ids as LE u64 via to_le_bytes/from_le_bytes into FixedSizeBina… | Arrow/Lance extension-table schemas + (de)serializers for neighborhood scent/resolution columns and cognitive_nodes cold-verification table | none | none | CORE (V3-neutral query engine) | +| `graph/blasgraph/matrix.rs` | pub | descriptor::Descriptor, semiring::{apply_binary_op,apply_monoid,Semiring}, sparse::{CooStorage,CscStorage,Csr… | GrBMatrix (mxm/mxv/vxm/ewise_add/ewise_mult/extract/apply/reduce_rows/reduce_cols/reduce/transpose), MatrixIt… | none | Sparse GraphBLAS matrix of BitVec elements with dual CSR/CSC storage; zero-copy transpose when CSC populated | set() rebuilds full CSR from COO on every call — O(nnz) per single-element write | none | CORE (V3-neutral query engine) | +| `graph/blasgraph/mod.rs` | pub | declares 17 submodules (blasgraph_planner..zeckf64) | Descriptor, GrBDesc, GrBMatrix, ops::*, HdrSemiring, Semiring, sparse types, BitVec/HdrScalar re-exports, GrB… | none | blasgraph module root: re-exports the GraphBLAS-inspired sparse matrix/vector/semiring algebra surface + GrBInfo status codes | none | none | CORE (V3-neutral query engine) | +| `graph/blasgraph/ndarray_bridge.rs` | pub | super::types::{BitVec,VECTOR_WORDS}; optional ndarray::hpc::{fingerprint::Fingerprint<256>,bitwise} under nda… | NdarrayFingerprint, dispatch_hamming, dispatch_popcount (+ AVX2/AVX-512BW/AVX-512VPOPCNTDQ intrinsics fallbac… | none (native-endian bytes via unsafe transmute of [u64;256], not LE-specified) | Zero-copy bridge BitVec<->ndarray Fingerprint<256> + 4-tier SIMD Hamming/popcount dispatch, used when ndarray-hpc feature is off | hand-rolled AVX2/AVX-512 intrinsics duplicate ndarray::hpc::bitwise logic — kept only as non-ndarray-hpc fall… | Fingerprint/BitVec x4 (ndarray canonical) — NdarrayFingerprint is a standalone mirror of ndarray::hpc::finger… | HW (SIMD/codec hardware) | +| `graph/blasgraph/neighborhood.rs` | pub | super::types::BitVec, super::zeckf64 | MAX_SCOPE_SIZE, Scope, NeighborhoodVector, build_scope, ScentVector, ProgressiveU16Vector | none | Scope-indexed neighborhood-vector graph representation: positional ZeckF64 edges per node up to 10K-node scope, at 3 storage-precision tiers | none | none | CORE (V3-neutral query engine) | +| `graph/blasgraph/neighborhood_csr.rs` | pub | none external (self-contained) | ScentCsr (from_scent_vectors, get, degree, spmv, row_range) | none | Secondary CSR adjacency bridge (u8 scent-weighted) for BFS/PageRank-style algorithms over neighborhood scent vectors | row() method is a stub that always returns &[] — doc comment says use row_range() instead; dead/misleading API | CSR x5 — one of 6 CSR/adjacency implementations across blasgraph/neighborhood/planner (see docs/ADJACENCY_SYN… | CORE (V3-neutral query engine) | +| `graph/blasgraph/ops.rs` | pub | descriptor::{Descriptor,GrBDesc}, matrix::GrBMatrix, semiring::{HdrSemiring,Semiring}, types::*, vector::GrBV… | grb_mxm/mxv/vxm/ewise_*/reduce_*/apply_*/extract_*/assign_vector/transpose, hdr_bfs, hdr_sssp, hdr_pagerank | none | GraphBLAS C-API-style free functions + HDR graph algorithms (BFS/SSSP/PageRank) built on GrBMatrix/GrBVector semiring ops | none | none | CORE (V3-neutral query engine) | +| `graph/blasgraph/semiring.rs` | pub | ndarray_bridge (HammingMin/SimilarityMax popcount compare), types::{hamming_to_similarity,BinaryOp,BitVec,Hdr… | Semiring trait, HdrSemiring (7 variants), apply_binary_op, apply_monoid | none | 7 GraphBLAS semirings (XorBundle/BindFirst/HammingMin/SimilarityMax/Resonance/Boolean/XorField) pairing multiply+add ops for matrix/vector … | none | none | CORE (V3-neutral query engine) | +| `graph/blasgraph/sparse.rs` | pub | types::BitVec | SparseEntry, SparseVec, CooStorage, CsrStorage, SparseFormat, StorageFormat, CscStorage, HyperCsrStorage | none | Sparse storage formats (COO/CSR/CSC/HyperCSR) for BitVec-valued matrices/vectors with format conversions | none | CSR x5 — one of 6 CSR/adjacency models in the workspace (docs/ADJACENCY_SYNERGY_MAP.md); overlaps lance-graph… | CORE (V3-neutral query engine) | +| `graph/blasgraph/typed_graph.rs` | pub | descriptor::GrBDesc, matrix::GrBMatrix, semiring::Semiring, sparse::CooStorage, types::BitVec, graph::spo::{s… | TypedGraph (add_relation/add_label/traverse/multi_hop/masked_traverse), BlasGraphHit, apply_truth_gate | none | Property-graph typed adjacency: one BitVec matrix per relationship type + one boolean mask per label, with TruthGate-filtered traversal | from_spo_store is a stub — SpoStore doesn't expose iteration so it returns an empty SPO relation for callers … | none | CORE (V3-neutral query engine) | +| `graph/blasgraph/types.rs` | pub | std::fmt; optional ndarray::hpc::bitwise under ndarray-hpc feature | VECTOR_WORDS, VECTOR_BITS, BitVec (xor/and/or/not/popcount/density/hamming_distance/bundle/permute), hamming_… | BitVec::as_bytes/from_bytes unsafe-transmute [u64;256]<->[u8;2048] using native-endian (from_ne_bytes, not fr… | Core 16384-bit BitVec hyperdimensional vector type + all semiring/matrix operator enums (UnaryOp/BinaryOp/MonoidOp/SelectOp/HdrScalar) | from_bytes uses from_ne_bytes (native-endian) while sibling files (lance_neighborhood/ndarray_bridge) assume … | Fingerprint/BitVec x4 (ndarray canonical) — BitVec is a standalone 16384-bit mirror of ndarray's Fingerprint<… | CORE (V3-neutral query engine) | +| `graph/blasgraph/vector.rs` | pub | semiring::{apply_binary_op,apply_monoid}, sparse::SparseVec, types::{hamming_to_similarity,BinaryOp,BitVec,Hd… | GrBVector (ewise_add/ewise_mult/apply/reduce/find_nearest/find_within/find_most_similar/extract/assign/set_sc… | none | Sparse BitVec vector with a separate scalar side-channel so non-vector semiring outputs (e.g. HammingMin's Float) survive mxv/vxm | none | none | CORE (V3-neutral query engine) | +| `graph/blasgraph/zeckf64.rs` | pub | super::types::BitVec | zeckf64, zeckf64_from_distances, scent, sign, bands, resolution, progressive_u16, zeckf64_distance, scent_dis… | pack_bytes manually packs 8 bytes into u64 with byte0=LSB (little-endian bit-shift packing, not the from_le_b… | Progressive 8-byte SPO-edge encoding: scent byte (94% precision) + 7 distance-quantile bytes (98% at full width), per ndarray Pareto fronti… | none | ZeckF64 x3 (ndarray canonical) — one of 3 copies per docs/TYPE_DUPLICATION_MAP.md | HW (SIMD/codec hardware) | +| `graph/fingerprint.rs` | pub | lance_graph_contract::hash::{fnv1a,fnv1a_str}, ndarray::hpc::bitwise::hamming_distance_raw | FINGERPRINT_WORDS, Fingerprint=[u64;8], label_fp, dn_hash, hamming_distance, ZERO_FP | none (unsafe transmute of [u64;8] to &[u8] for the ndarray hamming call is native-endian) | FNV-1a-derived 512-bit label fingerprint for SPO node/relationship-type addressing, with density-guard XOR-fold keeping popcount under 11% | none | none (distinct 512-bit label hash, not the 16384-bit BitVec/Fingerprint<256> family) | CORE (V3-neutral query engine) | +| `graph/graph_router.rs` | pub | blasgraph::{matrix::GrBMatrix,semiring::HdrSemiring,sparse::CooStorage,typed_graph::{apply_truth_gate,TypedGr… | GraphHit, Backend (DataFusion/Blasgraph/Palette/MailboxSoa), QueryClass, GraphRouter (add_node/add_edge/query… | none | Three-backend query router (DataFusion cold / Blasgraph hot / Palette hot) over one typed graph; classify_query picks a backend by pattern | only Blasgraph backend is actually wired — Palette/DataFusion branches in query_routed fall through to query_… | none | W2 kanban executors — reserved Backend::MailboxSoa variant … | +| `graph/hydrate.rs` | pub | ndarray::hpc::bgz17_bridge::Base17, gguf_indexer::read_bgz7_file, arrow builders, lance::Dataset::write | TensorRole enum, bgz7_to_batch, hydrate_bgz7, write_to_lance, hydrate_to_lance, compute_heel | none | Hydrates bgz7 Base17 weight vectors into Arrow RecordBatch / Lance dataset with tensor-role + layer-idx partition columns for CAM indexing. | bgz7_to_batch uses .expect("columns valid") on RecordBatch::try_from_iter in the non-test build path | none | HW (SIMD/codec hardware) | +| `graph/mailbox_scan.rs` | pub | lance_graph_contract::canonical_node::EdgeCodecFlavor, hhtl::NiblePath, soa_view::{IdentityPlane,MailboxSoaVi… | NodeMatch, match_nodes_by_class, match_node_by_local_key, clam_contained, cakes_nearest, EdgeNeighbors, edge_… | none (deliberately zero-value-decode: reads only class_id/HHTL key columns via MailboxSoaView, never energy/m… | Cypher MATCH/CLAM/CAKES/basin-tree navigation routed over MailboxSoaView's GUID key, proving substrate-is-the-graph with zero value decode. | several facets explicitly deferred (EdgeBlock slot->row resolution, Helix exact-location, CHAODA, CausalEdge6… | none | W1 envelope/ownership | +| `graph/metadata.rs` | mixed | arrow_array::{RecordBatch,StringArray,UInt32Array}, crate::config::GraphConfig, crate::query::CypherQuery | MetadataStore, NodeRecord, EdgeRecord (CRUD + query()/query_with_params() via CypherQuery) | none | Cold-path graph skeleton store (nodes/edges as Arrow RecordBatches) with CRUD and Cypher query execution via DataFusion planner. | nodes_batch/edges_batch use RecordBatch::try_new(...).unwrap() in the non-test build path | none | CORE (V3-neutral query engine) | +| `graph/mod.rs` | pub | submodules: arigraph, audio, blasgraph, fingerprint, graph_router, hydrate, mailbox_scan, metadata, neighborh… | module tree root; ContainerGeometry enum (Flat/AdjList/Csr/Csc/Coo/Hybrid/Spo) | none | Module root for graph primitives sitting beneath the Cypher/DataFusion query layer: fingerprinting, sparse bitmaps, SPO store, neighborhood… | none | none | CORE (V3-neutral query engine) | +| `graph/neighborhood/clam.rs` | pub | crate::graph::blasgraph::types::BitVec, neighborhood::scope::ScopeBuilder (tests) | scent_l1_distance, scent_hamming_distance, RadiusObservation, measure_cluster_radii, analyze_pareto_convergen… | none | Ball-tree cluster-radius harness testing whether CLAM clustering on scent vectors converges to the 8-bit/57-bit Pareto compression levels. | module doc explicitly frames this as an unvalidated conjecture ("This is a TEST, not a fact"), not yet promot… | none | HW (SIMD/codec hardware) | +| `graph/neighborhood/mod.rs` | pub | submodules clam, scope, search, sparse, storage, zeckf64 | re-exports: ParetoAnalysis, NeighborhoodVector/ScopeBuilder/ScopeMap, HeelResult/SearchCascade/SearchConfig, … | none | Module root for the HEEL/HIP/TWIG/LEAF progressive neighborhood-vector search path (ZeckF64 edges, up to 10K-node scopes). | none | re-exports zeckf64 module; ZeckF64 has 3 copies workspace-wide (ndarray canonical per TYPE_DUPLICATION_MAP) | HW (SIMD/codec hardware) | +| `graph/neighborhood/scope.rs` | pub | crate::graph::blasgraph::types::BitVec, super::zeckf64::{zeckf64,zeckf64_from_distances} | NeighborhoodVector, ScopeMap, ScopeBuilder::{build,build_from_distances}, MAX_SCOPE_SIZE | none | Builds per-node neighborhood vectors (one ZeckF64 edge per scope neighbor) for a scope of up to 10,000 nodes via O(N^2) pairwise SPO compar… | O(N^2) cost documented (~1s at N=10K); no mitigation implemented in this file | none | HW (SIMD/codec hardware) | +| `graph/neighborhood/search.rs` | mixed | super::scope::NeighborhoodVector, super::zeckf64::zeckf64_scent_distance | HeelResult, SearchConfig, SearchCascade::{heel,hip,twig,search,leaf_rerank,neighborhood_scent_l1} | none | In-memory HEEL->HIP->TWIG progressive cascade search plus LEAF re-rank over neighborhood vectors, expanding hop-by-hop with dedup. | leaf_rerank is documented as only the in-memory portion; full LEAF cold-data load is 'handled by the Lance in… | none | HW (SIMD/codec hardware) | +| `graph/neighborhood/sparse.rs` | pub | none (self-contained scent-byte arrays) | ScentCsr::{from_scent_vectors,nnz,row_range,get,degree,spmv} | none | Secondary CSR (u8 scent-weighted) adjacency built from neighborhood scent vectors, for standard graph algorithms (BFS/PageRank) vs primary … | none | CSR adjacency has 5 implementations workspace-wide (different purposes) per TYPE_DUPLICATION_MAP | HW (SIMD/codec hardware) | +| `graph/neighborhood/storage.rs` | pub | arrow_schema::{DataType,Field,Schema,TimeUnit}, super::scope::{NeighborhoodVector,ScopeMap,MAX_SCOPE_SIZE} | scopes_schema, neighborhoods_schema, cognitive_nodes_schema, serialize/deserialize scope+scent+resolution, bu… | serialize_scope_node_ids/deserialize_scope_node_ids use id.to_le_bytes()/u64::from_le_bytes into FixedSizeBin… | Arrow schemas + LE (de)serialization for persisting neighborhood vectors/scopes as Lance extension tables, without touching upstream graph_… | none | none | HW (SIMD/codec hardware) | +| `graph/neighborhood/zeckf64.rs` | mixed | crate::graph::blasgraph::types::BitVec (hamming_distance) | zeckf64, zeckf64_from_distances, scent, resolution, set_sign, get_sign, zeckf64_distance, zeckf64_scent_dista… | packed u64 ZeckF64 wire layout: byte0 (scent bits) \| byte1..7 (quantiles) shifted into a single u64 via bit-… | 8-byte progressive edge encoding for SPO triples: scent byte (7 boolean-lattice band bits) + 7 quantile bytes, giving rho~=0.94 rank correl… | none | ZeckF64 has 3 copies workspace-wide; ndarray is canonical per TYPE_DUPLICATION_MAP | HW (SIMD/codec hardware) | +| `graph/neuron.rs` | pub | ndarray::hpc::bgz17_bridge::Base17 | NeuronPrint{q,k,v,gate,up,down}, NeuronQuery, NeuronTrace::from_neuron | none | 6D holographic per-neuron representation (Q/K/V/Gate/Up/Down as 34-byte Base17 vectors, 204B total) with selective role-probing queries and… | none | none | HW (SIMD/codec hardware) | +| `graph/scheduler.rs` | mixed | lance::dataset::Dataset, lance_graph_contract::kanban::{ExecTarget,KanbanMove}, scheduler::{DatasetVersion,Ne… | LanceVersionScheduler::{new,with_policy,drive_once,drive_at_latest,current_dataset_version} | none | OUT-direction Lance-backed VersionScheduler impl: lowers each Lance dataset version tick into the next proposed Rubicon KanbanMove for a ma… | quotes an upstream lance TODO ('// TODO: support pagination' on Dataset::versions()) as a documented caveat f… | none | W2 kanban executors | +| `graph/semiring_map.rs` | pub | crate::graph::blasgraph::semiring::HdrSemiring | GraphBlasSemiring::{to_hdr_semiring,graphblas_name,hdr_name} | none | Maps 3 standard GraphBLAS semirings (MinPlus/OrAnd/XorBundle) onto the workspace's 7 HDR semiring equivalents, proving algebraic correspond… | none | none | CORE (V3-neutral query engine) | +| `graph/sparse.rs` | pub | none (self-contained; cross-checked in tests against graph::fingerprint::FINGERPRINT_WORDS) | BITMAP_WORDS, Bitmap type, bitmap_zero/or/and/xor/popcount/hamming/is_zero/set_bit, pack_axes | none | Fixed-width [u64;8] bitmap primitives (OR/AND/XOR/Hamming) packing S\|P\|O fingerprints into a single ANN search vector for Lance. | doc comment notes a prior bug: BITMAP_WORDS 'previously hardcoded as [u64; 2] which truncated fingerprints', … | Bitmap/BITMAP_WORDS shadows Fingerprint width, tested equal to FINGERPRINT_WORDS; part of the Fingerprint/Bit… | HW (SIMD/codec hardware) | +| `graph/spo/action_emitter.rs` | mixed | super::odoo_ontology::OntologyTriple | ActionSpec{effects,inputs,raises,reads,traverses}, emit_actions, emit_non_trivial_actions | none | Deterministically composes Foundry-shape ActionSpec records (requires/effects) per function from SPO ontology triples (emitted_by/depends_o… | none | none | CORE (V3-neutral query engine) | +| `graph/spo/builder.rs` | mixed | lance_graph_contract::grammar::FailureTicket, property::Schema, crate::graph::fingerprint::{Fingerprint,FINGE… | SpoRecord{subject,predicate,object,packed,truth}, SpoBuilder::{build_edge,build_forward_query,build_reverse_q… | none | Builds SPO edge records (S/P/O fingerprints + packed ANN bitmap + truth) via a stateless build_edge path and a stateful schema-validated st… | commit_validated carries #[allow(clippy::result_large_err)] (documented: FailureTicket intentionally rich) | none | CORE (V3-neutral query engine) | +| `graph/spo/link_chain.rs` | pub | super::odoo_ontology::OntologyTriple | LinkChain{source_family,hops,leaf}, split_chain, split_all_depends_on, SplitStats, compute_stats | none | Decomposes dotted depends_on IRIs (e.g. account_move.line_ids...amount_residual) into per-hop LinkChain records for Foundry Link-style type… | module doc explicitly defers target-ObjectType resolution to a consumer crate (would require lance-graph-onto… | none | CORE (V3-neutral query engine) | +| `graph/spo/merkle.rs` | pub | crate::graph::fingerprint::{Fingerprint, ZERO_FP} | MerkleRoot, ClamPath, BindNode, VerifyStatus, BindSpace (write/read/verify_lineage/verify_integrity) | none | In-memory BindSpace addressed by ClamPath: stamps Merkle root (XOR-fold hash) per fingerprint, verifies lineage | documented KNOWN GAP: verify_lineage is structural-only, does not re-hash to catch corruption (verify_integri… | none | LEGACY superseded singleton BindSpace concept | +| `graph/spo/mod.rs` | pub | own submodules: action_emitter,builder,link_chain,merkle,nsm_bridge,odoo_ontology,ontology_bridge,semiring,st… | Re-exports: SpoBuilder/Record, BindSpace, MerkleRoot, HammingMin, SpoStore/Hit, TruthGate/Value | none | SPO module root: declares submodules, re-exports public API, hosts RedisGraph-parity end-to-end test suite (10 tests) | none | none | CORE V3-neutral query engine root | +| `graph/spo/nsm_bridge.rs` | pub | graph::fingerprint::{dn_hash,label_fp}; super::builder/truth; arrow_array, arrow_schema (RecordBatch) | NsmSpoMapping, NsmGraderScore, NsmModelEval, ModelComparison, NsmEvalStore, nsm_eval_schema() | none | Maps DeepNSM word-explication evaluations (primes/molecules ratios) into SPO triples w/ NARS truth + Arrow export | none | none | CORE NSM-to-SPO semantic bridge | +| `graph/spo/odoo_ontology.rs` | pub | graph::fingerprint; spo::{builder,store,truth}; serde_json; embedded odoo_ontology.spo.ndjson corpus | OntologyTriple, parse_triples(), load_ontology() -> SpoStore (388 ObjectTypes, 24,579 triples) | none | Loads deterministic Odoo Foundry-ontology (harvested via ruff_python_dto_check+AST) into SpoStore for compute-graph reasoning | none (extraction generator not in-tree, only its ndjson output + spo_enrich enrichment script) | none | CORE Odoo ontology ingestion | +| `graph/spo/ontology_bridge.rs` | internal | lance_graph_contract::ontology::{Ontology,SchemaExpander}; ::property::{LinkSpec,Schema} | test-only: validates SchemaExpander trait produces SPO-shaped triples from Ontology/Schema/LinkSpec | none | Test-only integration module validating lance-graph-contract's Ontology->SPO SchemaExpander trait end-to-end | module doc promises Phase-2 ExpandedTriple->SpoRecord helpers; not yet implemented, file is test-only | none | CORE ontology-to-SPO trait validation | +| `graph/spo/semiring.rs` | pub | super::truth::TruthValue | SpoSemiring trait, HammingMin (min-plus over Hamming distance), TraversalHop | none | Semiring algebra (combine=min, extend=saturating_add) for Hamming-distance-cost graph traversal chains | none | one of ~15 semirings across repos (blasgraph 7 HDR semirings, planner TruthPropagating, bgz17 palette) | CORE traversal cost semiring | +| `graph/spo/store.rs` | pub | graph::fingerprint, graph::sparse::{bitmap_hamming,Bitmap}; super::{builder,semiring,truth} | SpoHit, SpoStore (insert/query_forward/query_reverse/query_relation/walk_chain_forward) | none (1 unsafe ptr-cast to bytes for fnv1a hash key, not a stored wire layout) | In-memory brute-force SPO triple store w/ bitmap Hamming ANN queries (2^3 projection verbs) + chain traversal | doc states 'development/testing implementation; production will use Lance ANN indices'; 1 unsafe block | none | CORE dev/test triple store | +| `graph/spo/truth.rs` | pub | none (serde derive only) | TruthValue{frequency,confidence,expectation,strength,revision}, TruthGate{OPEN..CERTAIN} | none | NARS-style truth value (frequency,confidence) + named gate thresholds (OPEN/WEAK/NORMAL/STRONG/CERTAIN) | none | candidate NARS truth/InferenceType family (3 copies noted in docs); possibly overlaps planner nars::truth | CORE NARS truth primitive | +| `graph/versioned.rs` | pub | lance::dataset::{Dataset,WriteMode,WriteParams}; blasgraph::columnar schemas; neighborhood::{scope,storage} | VersionedGraph{local/s3/azure/gcs,commit_encounter_round,at_version,tag,diff,graph_seal_check,write_scope} | FixedSizeBinary columns: plane_s/p/o(2048B), seal_s/p/o(6B), fingerprint(2048B) — Arrow/Lance schema layouts | Lance-backed versioned graph storage (nodes/edges/fingerprints/scopes/neighborhoods) w/ time-travel + Merkle seal diff | none major | none | CORE Lance versioned storage | +| `graph/witness_tombstone.rs` | pub | crate::graph::spo::builder::SpoRecord (doc-ref); crate::error::Result | HotWitness, calcify()[todo!], Tombstone{from_hot,persist}[todo!], WitnessLink{new,verify[todo!]} | none yet — compressed_payload is Box<[u8]> placeholder pending Scent/Base17 codec entry point (BLOCKED) | D-ATOM-5 scaffold: AriGraph mailbox hot-witness -> calcified SPO fact -> Lance tombstone GoBD audit chain | SCAFFOLD ONLY: calcify/from_hot/persist/verify are all todo!(); many inline BLOCKED markers for unresolved ty… | none | W1 mailbox-death tombstone ownership scaffold | +| `lance_native_planner.rs` | mixed | crate::config::GraphConfig, crate::logical_plan::LogicalOperator; lance_graph_planner::api::Planner (feature) | LanceNativePlanner (GraphPhysicalPlanner impl), classify(), gate_check() | none | Bridges lance-graph-planner strategy selection into GraphPhysicalPlanner trait; still returns EmptyRelation placeholder | TODO(Phase 3): translate planner IR to DataFusion LogicalPlan; plan() stubs to EmptyRelation | none | CORE query engine — planner bridge stub | +| `lance_vector_search.rs` | mixed | crate::ast::DistanceMetric, crate::datafusion_planner::vector_ops; arrow arrays; lance::Dataset | VectorSearch builder (search/search_lance), VectorSearchResult | none | Two-step GraphRAG vector search API: brute-force RecordBatch rerank or Lance ANN search().nearest() by column | none | none | CORE query engine — vector similarity search | +| `lib.rs` | pub | all lance-graph submodules; lance_graph_catalog re-exports | pub mod declarations; re-exports GraphConfig, GraphError, CypherQuery, SqlQuery, VectorSearch, MAX_VARIABLE_L… | none | Crate root: declares all modules and re-exports the public Cypher/SQL query-engine API surface | none | none | CORE query engine — crate root | +| `logical_plan.rs` | mixed | crate::ast::*, crate::error::{GraphError,Result}, crate::GraphConfig | LogicalOperator (ScanByLabel/Expand/VariableLengthExpand/Project/Join/Filter/Sort/etc), LogicalPlanner | none | Converts semantically-analyzed Cypher AST into logical plan operators (scan/expand/filter/project/join/sort/limit) | TODO: infer better join type based on shared vars (currently always JoinType::Cross for disconnected patterns) | none | CORE query engine — logical planning | +| `nsm/encoder.rs` | pub | SpoTriple from super::parser | WordDistanceMatrix, RoleVectors, NsmEncoder, EncodedTriple, EncodedSentence, TripleSimilarity, test_encoder() | rank.to_le_bytes() XOR-bound into RoleVectors::bind; not a stored wire layout | Builds/queries palette-quantized 4096x4096 upper-triangle word distance matrix for O(1) triple/sentence similarity comparison. | none | 4096-word CAM-PQ distance matrix parallels bgz17/bgz-tensor 256x256 palette distance tables (CLAUDE.md codec … | CORE (V3-neutral semantic transformer) | +| `nsm/mod.rs` | pub | nothing; declares submodules only | pub mod encoder, nsm_word, parser, similarity, tokenizer | none | Module root/doc for DeepNSM-CAM: 4096-word x12-bit exact O(1)/O(n) semantic transformer pipeline, no GPU/regex. | none | none | CORE (V3-neutral query engine) | +| `nsm/nsm_word.rs` | mixed | encoder::{NsmEncoder,RoleVectors,WordDistanceMatrix,NUM_PRIMES}, similarity::SimilarityTable, tokenizer::Voca… | NsmRuntime, NsmLoadError, create_nsm_similarity_udf(), register_nsm_udfs(), test_runtime() | codebook_pq.bin decoded via f32::from_le_bytes over 4-byte chunks (alignment-free LE contract, comment cites … | Domain bridge: loads CAM codebook + word-rank CSVs into NsmRuntime, registers nsm_similarity DataFusion scalar UDF. | build_synthetic_matrix has a dead code block (computes idx, never writes) before falling back to build() with… | none beyond encoder.rs's noted WordDistanceMatrix/palette overlap | CORE (DataFusion UDF wiring, V3-neutral) | +| `nsm/parser.rs` | mixed | tokenizer::{PoS, Token} | SpoTriple (u64 packed), ParseState, ModRelation, SentenceStructure, ModifierAttachment, parse() | SpoTriple: u64 bit-packed 12-bit S/P/O fields (bits 0-12/12-24/24-36); in-memory only, no from/to_le_bytes | PoS-driven FSM extracting SPO triples, modifiers, negation, and conjunction-forked clauses from a token stream. | current_verb_negated and last_subject_head computed then discarded via `let _ = ...` (dead locals, suppressed… | SpoTriple bit-packing is a second SPO representation alongside nsm_bridge.rs's NSM->SPO mapping (CLAUDE.md ns… | CORE (V3-neutral query engine) | +| `nsm/similarity.rs` | pub | encoder::WordDistanceMatrix | SimilarityTable::{from_distance_matrix, linear, similarity, similarity_u32, band, cosine_equivalent, raw_tabl… | none | Builds a calibrated CDF-based u8-distance -> f32-similarity lookup table (256 entries) with named similarity bands (foveal/near/good/miss). | none | none | CORE (V3-neutral semantic transformer) | +| `nsm/tokenizer.rs` | mixed | std::collections::HashMap | PoS (13 tags), WordEntry, Token, Vocabulary::{load, from_entries, tokenize_word, tokenize, word, lookup}, tes… | none | Hash-based word->12-bit-rank/PoS tokenizer with case-insensitive and inflected-form resolution plus negation detection. | test_vocabulary() contains a duplicate 'the' entry, inline-commented as 'dup, ignored by HashMap' | none | CORE (V3-neutral query engine) | +| `parameter_substitution.rs` | mixed | crate::ast::*, crate::error::{GraphError,Result}; serde_json::Value | substitute_parameters() — walks CypherQuery AST replacing $param with literals/VectorLiteral | none | Recursively substitutes $param references throughout a parsed CypherQuery AST with literal or vector values | none | none | CORE query engine — parameter substitution | +| `parser.rs` | mixed | nom combinators (branch/bytes/character/combinator/multi/sequence); crate::ast::*, crate::error | parse_cypher_query() -> CypherQuery (only pub fn; ~30 private nom combinator parsers) | none | nom-based recursive-descent Cypher parser: MATCH/UNWIND/WHERE/WITH/RETURN/ORDER BY/paths/expressions to AST | none observed in read portion | one of 4 Cypher/GQL/Gremlin/SPARQL frontends across repo; lance-graph-planner has own CypherParse strategy | CORE query engine — Cypher parser | +| `query.rs` | mixed | crate::ast/config/logical_plan/parser/spark_dialect; datafusion, lance_namespace | CypherQuery::{execute*, explain, to_sql}, SqlDialect, ExecutionStrategy, CypherQueryBuilder | none | High-level Cypher facade: parse->plan->execute against datasets/SessionContext/namespace; SQL unparse; vector rerank | execute_blasgraph() has dead code past an early return guard; builder query_text is a TODO stub | none | CORE query engine — high-level Cypher query API | +| `semantic.rs` | mixed | crate::ast::*, crate::case_insensitive::CaseInsensitiveLookup, crate::config::GraphConfig | SemanticAnalyzer, VariableInfo, VariableType, ScopeType, SemanticResult | none | Validates & enriches parsed Cypher AST: variable discovery/scoping, clause validation, schema + type checks | TODO at line 663: type checking (validate_types) not implemented | none | CORE query engine — semantic analysis | +| `spark_dialect.rs` | pub | datafusion_sql::sqlparser::ast; datafusion_sql::unparser::dialect::CustomDialectBuilder | build_spark_dialect() -> CustomDialect | none | Configures Spark SQL unparser dialect (backtick quoting, STRING casts, EXTRACT) used by query.rs to_sql() | none | none | CORE query engine — SQL unparser dialect | +| `sql_catalog.rs` | pub | crate::error; datafusion::execution::context::SessionContext; lance_graph_catalog::connector::Connector | build_context_from_connector() | none | Auto-registers all tables from a catalog connector schema into a fresh DataFusion SessionContext | none | none | CORE query engine — catalog-to-SessionContext bridge | +| `sql_query.rs` | mixed | crate::error; crate::query::{normalize_record_batch,normalize_schema}; datafusion MemTable/SessionContext | SqlQuery (execute/execute_with_context/explain) | none | Raw-SQL execution path against in-memory datasets or a SessionContext, bypassing Cypher/GraphConfig entirely | none | none | CORE query engine — direct SQL interface | +| `table_readers.rs` | pub | lance_graph_catalog::{catalog_provider,table_reader::TableReader}; datafusion; deltalake (feature delta) | ParquetTableReader, DeltaTableReader (feature-gated), default_table_readers() | none | Built-in TableReader impls registering Parquet/Delta tables into DataFusion SessionContext by storage_location | none | none | CORE query engine — table reader implementations | + +## lance-graph-contract (113 files) + +| File | Vis | Consumes | Emits | LE contract | Function / benefit | Tech debt | Duplication | V3 wave | +|---|---|---|---|---|---|---|---|---| +| `a2a_blackboard.rs` | pub | zero-dep; pure data (ExpertId, capabilities) posted/read by external orchestrators | Blackboard, BlackboardEntry, ExpertCapability, ConsensusStrategy, compute_consensus() | none | Layer-1 runtime A2A shared workspace: experts post typed results, router selects, consensus (weighted/majority/unanimous) merges | none | none | CORE (V3-neutral runtime A2A bus) | +| `action.rs` | pub | NodeGuid (canonical_node), ExecTarget (kanban), GateDecision (mul), ActorContext (auth), ClassRbac (rbac) | ActionState, StateGuard, ActionDef, ClassActions, actions_for(), effective_actions(), ActionInvocation::commi… | none | OGAR IR DO arm: static ActionDef declarations + dynamic ActionInvocation lifecycle, gated by RBAC then MUL impact before committing to an e… | none | none | CORE (OGAR IR DO/action arm) | +| `aiwar.rs` | pub | canonical_node::{NodeGuid, EdgeBlock, NodeRow}, literal_graph::LiteralGraph, soa_graph::project_snapshot | AiwarClassView, aiwar_node_rows() | constructs NodeGuid/EdgeBlock/NodeRow (canonical_node LE key), head-only value slab left zero | Maps the aiwar OSINT neo4j-harvest graph into canonical OSINT NodeRows so categories become stable family/anchor hub nodes for q2's Gotham … | none | none | W1 envelope/ownership (canonical_node/soa_graph consumer) | +| `atoms.rs` | pub | nothing external; defines its own bare-metal carrier | I4x32, I4x64 (pack/unpack), AtomGroup, Atom, CANONICAL_ATOMS (locked 33-dim TSV) | I4x32/I4x64 two's-complement nibble-packed carrier, byte-compatible with QualiaI4_16D and CausalEdge64 mantis… | The LOCKED 33-dim ThinkingStyleVector atom basis + i4 CAM pack/unpack carrier; composition/SIMD dispatches to cognitive-shader-driver, not … | none (prior layout ambiguities marked RESOLVED in header comments) | ThinkingStyle x4 (this is the atom-lane basis a style vector weights over, adjacent to thinking.rs ThinkingSt… | W3 templates (thinking-style vector basis feeding compiled … | +| `auth.rs` | pub | sla::TenantId | ActorContext, AuthError | none | JWT-derived actor identity envelope (actor_id/tenant_id/roles) consumed by the DataFusion RLS rewriter and audit log | AuthError::InvalidSignature documented as 'Phase 2 — not yet implemented' | none | CORE (RLS/auth, V3-neutral) | +| `callcenter/mod.rs` | pub | ogit_uris + role_keys submodules; crate::savants roster | pub mod re-exports: savant_ogit_uri*, savant_role_key*, SAVANT_* consts | none | Module hub for callcenter Layer-2 identity catalogue: canonical OGIT URIs + desperation-bucket role-key fallback | none | sibling of grammar/role_keys.rs (same I-VSA-IDENTITIES 3-layer pattern) | W1 envelope/ownership (OGIT codebook doctrine) | +| `callcenter/ogit_uris.rs` | pub | crate::savants::{savant, savant_by_name, SAVANTS} | SAVANT_OGIT_BASE, SAVANT_OGIT_URIS LazyLock[String;25], savant_ogit_uri(), savant_ogit_uri_by_name() | none | Canonical OGIT-URI codebook for 25 Odoo savants; resolves through OntologyRegistry to a stable row index (identity layer 1/3) | Steps 2-4 (TTL hydration, MappingProposal, inheritance tree) explicitly deferred, out of scope this commit | none | W1 envelope/ownership (OGIT codebook doctrine) | +| `callcenter/role_keys.rs` | pub | crate::grammar::role_keys::RoleKey; crate::savants::{savant, savant_by_name, Savant, SAVANTS} | SAVANT_SLICE_START/WIDTH/END, SAVANT_ROLE_KEYS LazyLock[RoleKey;25], savant_role_key(), _by_name() | Binary16K u64 bitpacked RoleKey slices [14096..16346) within the 16384-dim VSA space | Desperation-bucket fallback identity (FNV-seeded bipolar RoleKey slices) for savants when OGIT codebook lookup unavailable | docs explicitly mark this NOT the canonical identity -- bitpacked bits are compute-only fallback | same pattern as grammar/role_keys.rs (disjoint VSA slice catalogue) | HW (VSA bitpacked fallback) | +| `cam.rs` | pub | nothing external | CodecRoute, route_tensor(), CamStrategy, DistanceTableProvider, CamCodecContract, IvfContract, CodecParams/Co… | none | CAM-PQ codec contract: tensor routing rules (Passthrough/CamPq/Skip), distance-table + codec traits ndarray implements, and JIT-sweep Codec… | none | none | HW (SIMD/codec hardware contract) | +| `canonical_node.rs` | pub | class_view::FieldMask, kanban::{ExecTarget,KanbanColumn}, qualia::QualiaI4_16D, soa_envelope::{ColumnDescript… | NodeGuid, EdgeBlock, NodeRow, ValueTenant/VALUE_TENANTS, ValueSchema, TailVariant, ReadMode, NODE_ROW_COLUMNS | the LE contract itself: NodeGuid::new packs classid/HEEL/HIP/TWIG/family/identity via to_le_bytes, from_le_by… | LOCKED minimal SoA node: 512B = key(16)+edges(16)+value(480), zero-fallback ladder (classid/family default to 0), the canonical GUID every … | ClassView::value_schema default is a documented TEMPORARY POC (returns Full, meant to revert to Bootstrap bef… | canonical — v1/v2(feature guid-v2-tail)/v3(feature guid-v3-tail) tail variants coexist by design, not acciden… | W1 envelope/ownership (the canonical node + LE contract) | +| `class_view.rs` | pub | ontology::{DisplayTemplate, FieldRef}, canonical_node::{EdgeCodecFlavor, ValueSchema} (via default methods) | ClassId, FieldMask, ComputeEdge, compute_dag_is_acyclic()/compute_dag_topo_order(), ClassView trait, RenderRo… | none (FieldMask is a presence bitmask, not a byte-wire layout) | The class as a meta-DTO flying above the SoA: presence FieldMask + late-bound label/template resolver + acyclic recompute-DAG topo-order, s… | ClassView::value_schema default explicitly documented TEMPORARY POC (Full instead of canon zero-fallback Boot… | none | W1 envelope/ownership (FieldMask/ClassView resolver above c… | +| `codebook.rs` | pub | nothing external (feature guid-v2-tail scoped) | Codebook, FamilyCodebookRegistry, CODEBOOK_CAP | none (label interning table, index 0..255 is the 1-byte in-family adapter value written into EdgeBlock elsewh… | Per-family ≤256-entry label codebook (family→Codebook), the finer sibling of classid→ClassView; a family exceeding 256 entries splits rathe… | in-memory LazyLock tier only; Lance-backed + OntologyRegistry-integrated persistence explicitly deferred | none | W1 envelope/ownership (v2-tail family codebook) | +| `codegen_manifest.rs` | pub | nothing external | MethodSig, ClassMethods, methods_for() | none | Core-side compile target for the ruff_cpp_codegen-generated const method-resolution manifest (THINK-arm method signatures, const-constructi… | runtime classid→methods registry intentionally deferred; only type + lookup shipped, data generated downstream | none | CORE (OGAR codegen method manifest) | +| `codegen_spine.rs` | pub | std::collections::BTreeSet only (zero-dep) | Triple, TripletProjection trait + roundtrip_eq(), OdooMethodKind (16-variant bucket enum), RouteBucket, Widge… | none | Four canonical contracts gating the triplets→codegen→askama-route→GUI-shape pipeline against duplication/drift: lossless round-trip test, o… | doc explicitly notes the OdooMethodKind classifier (body→kind function) is a separate emitter, TBD, not yet w… | none | CORE (Odoo transcode codegen pipeline) | +| `cognition/advance.rs` | pub | super::entity::NormalizedEntity, super::op::{Op,Output}, super::stages::*, crate::transaction::*Ctx traits | impls: resolve_ogit, hydrate_owl, classify_dolce, align_fibu, op, chk_data, review, abduct, report, output | none | Five-verb typestate advancement algebra moving NormalizedEntity through Raw->WithOgit->...->Reported pipeline stages | hydrate_owl/classify_dolce/align_fibu bodies are todo!() (Stage 2 unwired); chain discards step() Result | none | W5 consumers (Odoo/callcenter typestate op chain) | +| `cognition/cascade.rs` | pub | super::entity::MailboxRow | pub enum CascadeKind, pub enum TraversalMode, pub trait CascadeWalker { walk_dependents } | none | Collapses Odoo's six cascade mechanisms (@api.depends/constrains/FK/automation/_inherits) into one CausalEdge64/EdgeColumn walk | walk_dependents unimplemented (trait shape only); doc cites superseded Baton (u16,CausalEdge64) emission (E-B… | none | LEGACY (doc cites superseded Baton emission) | +| `cognition/entity.rs` | mixed | super::stages::{Raw,Stage}, core::marker::PhantomData | pub struct MailboxRow, NormalizedEntity, OdooEntityRef/OgitUriRef/OwlClassRef/FibuAlignmentRef, DolceCateg… | none | Typed carrier: NormalizedEntity is a Copy typed lens into a MailboxSoA row (mailbox_ref,row_idx), not owning the columns | 4 zero-dep placeholder handles marked TODO(Stage 2), to be replaced by real ontology-crate types | none | W5 consumers (MailboxRow typed lens onto mailbox SoA) | +| `cognition/mod.rs` | pub | advance, cascade, entity, op, stages submodules | pub re-exports: NormalizedEntity, Op/OpError/OpKind/Output, CascadeKind/Walker/TraversalMode, 9 Stage markers | none | Crate doc + module hub for the normalized OGIT/OWL/DOLCE/Odoo entity pipeline; carries 4 compile_fail doctests gating typestate | none | none | W5 consumers (Odoo cognition pipeline hub) | +| `cognition/op.rs` | pub | super::entity::NormalizedEntity, super::stages::Stage | pub struct OpKind, pub struct Output, pub trait Op, pub struct OpError | none | Op trait: identity (kind()) + step() hook + three planned call sites (cold/warm/hot) sharing one set of const data | apply_stream and apply_soa call sites commented out, deferred to Stage 2 pending Stream/MailboxSoA dep decisi… | none | W5 consumers (Op dispatch trait) | +| `cognition/stages.rs` | pub | none (leaf module) | pub structs Raw/WithOgit/WithOwl/WithDolce/Normalized/Checked/Reviewed/Abducted/Reported, pub trait Stage (se… | none | Nine phantom-typed stage markers enforcing compile-time-checked pipeline ordering via a sealed Stage trait | none | none | W5 consumers (typestate stage markers) | +| `cognitive_shader.rs` | pub | collapse_gate::{GateDecision, MergeMode}, escalation::rung_delta (in tests) | MetaWord, MetaFilter, ColumnWindow, StyleSelector, RungLevel/RungElevator, ShaderDispatch, ShaderResonance, S… | MetaWord: packed u32 bitfields (thinking(6)+awareness(4)+nars_f(8)+nars_c(8)+free_e(6)) | Cognitive Shader DTO API mirroring the Φ/Ψ/B/Γ DTO ladder (Dispatch/Resonance/Bus/Crystal) for zero-copy BindSpace-column dispatch, plus Ru… | MaterializeProvenance.fork documented CONJECTURE (dispersion proxy pending real CoarseResidue magnitude) | none | W4 DTO ladder (Φ ShaderDispatch / Ψ ShaderResonance / B Sha… | +| `collapse_gate.rs` | pub | nothing external | ALPHA_SATURATION_THRESHOLD, MergeMode, GateDecision (+ FLOW_XOR/FLOW_BUNDLE/BLOCK/HOLD consts), MailboxId | none | Layer-3 write-back protocol: MergeMode (how overlapping writers merge) + GateDecision (2-byte gate+merge microcopy) + MailboxId addressing … | documents its own supersession: CollapseGateEmission/wire_cost_bytes() REMOVED per PR #477 three-tier zero-co… | none | W1 envelope/ownership (MailboxId + per-row write-airgap sur… | +| `container.rs` | pub | nothing external | Container ([u64;256] alias), CONTAINER_WORDS/BITS/BYTES, CogRecord, ContentGeometry | none | The pre-V3 BindSpace record unit — 16Kbit Container aligned with ndarray::Fingerprint<256>, CogRecord = metadata+content 4KB pair | models the singleton-BindSpace 'Container' shape the V3 mailbox-kanban ruling superseded; not yet marked depr… | Fingerprint/BitVec x4 (Container backing store mirrors ndarray::hpc::fingerprint::Fingerprint<256>) | LEGACY (superseded singleton-BindSpace record unit; canonic… | +| `content_store.rs` | pub | hash::fnv1a | ContentId, SourceSpan, ContentError, ContentStore trait, ContentSink trait | none | Content-addressed cold text/blob store contract enforcing the hot/cold firewall (ADR-022): fixed-size ContentId/SourceSpan live on the node… | doc notes 64-bit fnv1a should widen to 128-bit if corpus approaches birthday-collision range (~2^32 sources) | none | CORE (hot/cold membrane contract, V3-neutral) | +| `counterfactual.rs` | pub | escalation::CouncilVerdict (in tests) | SPAWN_DISSONANCE_THRESHOLD, SplitPoles, deposit_counterfactual(), EpisodicEdge trait, CounterfactualMailbox, … | RawEdge is a mantissa-only 1-byte structural wrapper (size_of::()==1) standing in for the CausalEdge… | D-ATOM-4 split-resolution: v2 deposits the minority pole as a -6 counterfactual mantissa nibble (4 bits, no replay buffer); v3 ghost-tier m… | heavy: multiple todo!() stubs (CounterfactualMailbox::new/poll/cancel, revise_if_minority_wins) and explicit … | none | CORE (NARS/causal-edge counterfactual reasoning, distinct f… | +| `crystal/context.rs` | pub | super::{Crystal,CrystalFingerprint,CrystalKind,SentenceCrystal,TruthValue} | pub struct ContextCrystal, pub enum ReplayDirection, impl Crystal for ContextCrystal | none | Markov +/-5 sentence-crystal window around a focal sentence; supports replay for disambiguation of ambiguous parses | none | none | W4 DTO ladder (persistence-time crystal view) | +| `crystal/cycle.rs` | pub | super::{Crystal,CrystalFingerprint,CrystalKind,TruthValue}, crate::proprioception::StateAnchor | pub struct CycleCrystal, impl Crystal for CycleCrystal | fingerprint: CrystalFingerprint == cycle_fingerprint:[u64;256] backing shared with cognitive_shader::ShaderBus | Persistence-time view of one cognitive cycle (observe->act->feedback); mirrors cognitive_shader::ShaderCrystal (Gamma rung) | none | none | W4 DTO ladder (Gamma persistence view of ShaderCrystal) | +| `crystal/document.rs` | pub | super::{Crystal,CrystalFingerprint,CrystalKind,TruthValue} | pub struct DocumentCrystal, impl Crystal for DocumentCrystal | none | Full-document crystal summary (document_id + sentence_count); materialization of underlying sentences is downstream | none | none | W4 DTO ladder (persistence-time crystal view) | +| `crystal/fingerprint.rs` | mixed | none (leaf, defines its own algebra) | pub enum CrystalFingerprint (5 variants), Quorum5D, Structured5x5, vsa_bind/bundle/superpose/cosine, vsa16k_*… | Binary16K Box<[u64;256]> <-> Vsa16kF32 Box<[f32;16384]> bit-addressable bipolar projection, lossless both ways | Polymorphic crystal fingerprint carrier (5 native forms) + VSA bind/bundle/cosine algebra on 10K and 16K f32 spaces | none; byte_size table + iron-rule doc comments kept in sync with I-VSA-IDENTITIES | Vsa16kF32 carrier is the same Click switchboard concept documented at repo-root CLAUDE.md | HW (VSA bind/bundle/cosine SIMD-shaped algebra) | +| `crystal/mod.rs` | pub | context, cycle, document, fingerprint, sentence, session submodules | pub trait Crystal, pub enum CrystalKind, pub struct TruthValue, UNBUNDLE_HARDNESS_THRESHOLD, re-exports | none | Crystal hierarchy hub; documents mapping of cognitive_shader Phi/Psi/B/Gamma DTOs to Sentence/Context/Document/Cycle/Session crystals | none | none | W4 DTO ladder (crystal-hierarchy trait hub) | +| `crystal/sentence.rs` | pub | super::{Crystal,CrystalFingerprint,CrystalKind,TruthValue}, crate::grammar::tekamolo::TekamoloSlots | pub struct Triple, pub struct SentenceCrystal, impl Crystal for SentenceCrystal | none | One parsed sentence crystallized: SPO triples + optional TEKAMOLO adverbial slots + NARS truth/hardness/revision | none | minimal Triple shape overlaps richer SPO triple stores elsewhere in the workspace (graph/spo) | W4 DTO ladder (persistence-time crystal view) | +| `crystal/session.rs` | pub | super::{Crystal,CrystalFingerprint,CrystalKind,TruthValue} | pub struct SessionCrystal, impl Crystal for SessionCrystal | none | Full conversation/agent session crystal summary (session_id + cycle_count) at the top of the crystal hierarchy | none | none | W4 DTO ladder (persistence-time crystal view) | +| `cycle_accumulator.rs` | pub | std::time::{Duration, Instant} only | AccumulatorAction, CycleAccumulator (push/drain/pending_age_ms) | none | Per-cadence flush gate absorbing the ~10,000x L1(ns)↔L3(ms) speed ratio via row-count OR time thresholds; caller drives the actual outbound… | none | none (explicitly distinguished from collapse_gate::GateDecision to avoid a GATE-2 namespace clash) | CORE (single-binary L1-L3 topology infra, V3-neutral) | +| `distance.rs` | pub | nothing external | Distance trait (+ scalar impls for [u64;256]/[u8;6]/[u8;3]), fisher_z_inverse(), mean_similarity_fisher() | none | Type-intrinsic zero-cost distance dispatch (monomorphized, no dyn) for Binary16K/CamPqCode/PaletteEdge carriers, plus FisherZ transform for… | scalar impls are an explicit non-SIMD baseline; ndarray consumers are expected to shadow with SIMD kernels on… | Fingerprint/BitVec x4 ([u64;256] Hamming carrier mirrors ndarray::Fingerprint<256> / Binary16K) | HW (SIMD/codec distance math) | +| `episodic_edges.rs` | pub | no imports; pure zero-dep u64 packed word | EdgeRef, EpisodicEdges64 (4x16-bit slots), DemotionSink trait | EpisodicEdges64 packed u64: to/from_le_bytes, write_le/read_le, to_u64/from_u64 | AriGraph episodic edges: 4-slot MRU hot tier (promote/evict) over a family/local edge reference | none | none | W1 envelope/ownership (SoA edge column) | +| `escalation.rs` | pub | raw scalar signals (trust/humility/flow/load); no crate deps | CollapseHint, InnerCouncil, EpiphanyDetector, GhostEcho, WisdomMarker, Checklist | none | Boot checklist verified by an escalation+epiphany loop (council majority vote, surprise detector, green-flip) | GhostEcho duplicates thinking_engine::ghosts::GhostType per TECH_DEBT TD-GHOST-ECHO-DUP-1 (excluded crate) | GhostEcho vs excluded crate thinking_engine::ghosts::GhostType | CORE (V3-neutral cognitive substrate) | +| `exploration.rs` | pub | crate::literal_graph::{LiteralEdge, LiteralGraph, LiteralNode} | MassExplorer, FrontierEdge, PearlQuery, NarsTruth (proposer-side), ExplorationStats | none | NARS-gated web-crawl graph expansion: Pearl 2^3 query decomposition + curiosity-ranked frontier | TD-EXPLORATION-1/2 placeholders (empty frontier ctor, unused node_ids filter); NarsTruth is offline float dup… | NarsTruth is proposer-side dup of canonical nars_engine::nars_infer (lance-graph-planner), per own doc note | CORE (V3-neutral cognitive substrate) | +| `external_membrane.rs` | pub | crate::cognitive_shader::{MetaWord, ShaderBus}, crate::orchestration::UnifiedStep | ExternalRole, ExternalEventKind, CommitFilter, MembraneGate, ExternalMembrane trait | none (BBB invariant enforced via Arrow-scalar-only Commit assoc type, no VSA/semiring types) | Blood-Brain Barrier typed boundary between cognitive substrate and external callcenter surface | none | none | W5 consumers (callcenter external boundary) | +| `facet.rs` | pub | core only; borrowed [u8;16] slabs | FacetTier, FacetCascade (16B), CascadeShape (G6D2/G4D3/G3D4), ClassArm | FacetCascade repr(C,align(16)) reinterpret; from_bytes/to_bytes/as_u128/from_u128; const size asserts (2B tie… | Content-blind 8:8 facet substrate: one 16B register readable as row/tile/prefix/nibble lanes for any classid-selected schema | none (unsafe reinterpret blocks carry SAFETY comments) | none | W1 envelope/ownership (the V3 atom's 4+12 facet) | +| `facet_schema.rs` | pub | crate::facet::FacetCascade | FacetSchema enum (TierCascade/SpoTriplet/Pair48), payload()/as_triplets()/as_pair48() on FacetCascade | reads/writes FacetCascade's 12 payload bytes (LE) under 3 alternate tilings, no byte movement | Classid-selected re-tiling of a facet's 12 payload bytes (6x2:2, 4x3, 2x48) without touching the 480B value slab | of_classid() schema-bit position is explicitly provisional, pending operator/panel ratification | none | W1 envelope/ownership (facet payload schema) | +| `faculty.rs` | pub | crate::thinking::ThinkingStyle | ToolAbility, FacultyRole enum, FacultyDescriptor | none | Internal cognitive-function identity (asymmetric inbound/outbound thinking style transducer) alongside ExternalRole | none | none | CORE (V3-neutral A2A blackboard role) | +| `grammar/context_chain.rs` | pub | crystal::fingerprint::CrystalFingerprint::Binary16K bit array | ContextChain, DisambiguationResult, WeightingKernel, DisambiguateOpts | none | Markov +-5 context chain; counterfactual replay disambiguation scores candidates by Hamming coherence | 4 disambiguate* methods #[deprecated] in favor of disambiguate_with(opts) | none | CORE Markov disambiguation primitive | +| `grammar/disambiguator.rs` | pub | none (generic trait, zero external deps) | Disambiguatable trait, disambiguate_general fn, GeneralizedResult | none | Domain-agnostic generalization of ContextChain::disambiguate for coreference/RLS/AriGraph/style reuse | none | generalizes context_chain.rs logic (documented outlook E5, not literal dup) | CORE generic disambiguation primitive | +| `grammar/finnish.rs` | pub | super::{TekamoloSlot, WechselRole} | FinnishCase enum (15 cases), finnish_case_for_suffix() | none | Finnish grammatical case suffix lookup mapping 15 cases to TEKAMOLO slots and cross-lingual Wechsel roles | none | none | CORE grammar morphology table | +| `grammar/free_energy.rs` | pub | super::ticket::FailureTicket | FreeEnergy, Hypothesis, Resolution{Commit,Epiphany,FailureTicket} | none | Active-inference free-energy formulation: composes likelihood+KL into Commit/Epiphany/FailureTicket | none | none | CORE active-inference grammar resolution | +| `grammar/inference.rs` | pub | crate::thinking::StyleCluster, crate::nars::InferenceType | NarsInference enum (7 variants), inference_to_style_cluster() | none | Maps 7 grammar-specific NARS inference types to core InferenceType and thinking-style cluster dispatch | none | NARS InferenceType x3 dup family; this is an extended set that maps down to the core 5 | CORE NARS dispatch table | +| `grammar/mod.rs` | pub | 9 grammar submodules | re-exports ContextChain, FreeEnergy, FailureTicket, RoleKey*, VerbRoleTable; LOCAL_COVERAGE_THRESHOLD | none | Grammar module root: tiered local-parse-then-LLM-fallback routing wired across 9 submodules | none | none | CORE module root | +| `grammar/role_keys.rs` | pub | super::finnish::FinnishCase, super::inference::NarsInference, crate::hash::fnv1a_str | RoleKey, RoleKeySlice, SUBJECT_KEY..STEUER_KEY statics, 15/12/7-entry slice tables | none | Canonical disjoint [start:stop) VSA role-key catalogue (16384-dim) for SPO/TEKAMOLO/Finnish/Tense/NARS/SMB | bind/unbind/recovery_margin methods removed (comment-documented); #[allow(dead_code)] unused consts | none (canonical per I-VSA-IDENTITIES layer-2 catalogue) | CORE VSA role-key catalogue | +| `grammar/tekamolo.rs` | pub | none | TekamoloSlot enum, TekamoloSlots struct | none | Temporal/Kausal/Modal/Lokal/Instrument adverbial slot positions as lightweight token-index pairs | none | none | CORE grammar slot types | +| `grammar/thinking_styles.rs` | pub | context_chain::WeightingKernel, inference::NarsInference, crystal::TruthValue, thinking::ThinkingStyle | GrammarStyleConfig, GrammarStyleAwareness, ParamKey, ParseOutcome, revise_truth(), parse_style_yaml() | none | NARS-revised per-style grammar policy (morphology/tekamolo/markov/spo_causal) + zero-dep YAML loader | none; zero-dep hand-rolled YAML subset parser is a documented scope limitation | ThinkingStyle x4 dup family; consumes canonical crate::thinking::ThinkingStyle | W3 compiled thinking-style policy dispatch | +| `grammar/ticket.rs` | pub | inference::NarsInference, tekamolo::TekamoloSlots, wechsel::WechselAmbiguity | PartialParse, CausalAmbiguity, FailureTicket, FailureTicket::missing_required() | none | Structured LLM-fallback ticket carrying partial parse + ambiguity for surgical (not full-sentence) escalation | none | none | CORE LLM-escalation ticket type | +| `grammar/verb_table.rs` | pub | crate::grammar::role_keys::Tense | VerbFamily, SlotPrior, SlotPriorDelta, VerbRoleTable, tense_modifier(), base_prior(), default_table() | none | 144-cell (12 verb family x 12 tense) TEKAMOLO slot-prior table with linguistically-grounded tense modulation | doc-comment mojibake (encoding corruption); priors explicitly marked starter/tune-empirically | none | CORE grammar prior table | +| `grammar/wechsel.rs` | pub | none | WechselRole enum, WechselAmbiguity struct | none | Dual-role token ambiguity markers (prepositions/conjunctions/pronouns) feeding context-replay disambiguation | none | none | CORE grammar ambiguity type | +| `graph_render.rs` | pub | core only; zero deps | RenderNode, RenderEdge, GraphSnapshot, GraphSnapshotProvider/GraphInferenceProvider/CypherExecutor/EpisodicTr… | none | Visual-render contract for Neo4j/Palantir-Gotham-style cockpit UIs consuming the live knowledge graph without lance-graph core dep | none | none | W5 consumers (q2 cockpit-server) | +| `hash.rs` | pub | core only | fnv1a(const fn), fnv1a_str | none | Canonical stable FNV-1a 64-bit hash shared by all crates (e.g. role-key seed computation) instead of local copies | none | none (this IS the dedup target other crates should use) | CORE (V3-neutral utility) | +| `head2head.rs` | pub | crate::a2a_blackboard::{Blackboard, BlackboardEntry, ExpertId} | WinnerCriterion, CompetitionOutcome, Head2Head | none | Selects the winning expert bid among competing mailbox-experts on the A2A blackboard (dissonance/confidence/support-spread scoring) | none (documented clippy pedantic allow-list, not debt) | none | CORE (V3-neutral Layer-1 A2A blackboard) | +| `hhtl.rs` | pub | crate::canonical_node::NodeGuid, crate::ogar_codebook::split_classid[_with], crate::class_view::FieldMask (te… | NiblePath (16-nibble packed u64 tree address), FAN_OUT/MAX_DEPTH consts | packed()/from_packed() u64+depth roundtrip; from_guid_prefix[_v2/_v3] decode NodeGuid key bytes into a routin… | 16^n nibble-bucket router: O(1) bit-shift IS-A ancestry/prefix/LCA/hop-count over the DOLCE subClassOf tree, domain-agnostic | v1/v2/v3 GUID-fold variants coexist behind cfg features (deliberate migration path, not a stray TODO) | none (explicitly dissolves a DolceCategory dup at the resolution layer, not here) | W1 envelope/ownership (NodeGuid HHTL routing) | +| `high_heel.rs` | pub | core only; zero deps | SpoBase17, Heel, HighHeelBGZ (2KB container), BasinAccumulator, LensProfile, LensConfig, LENS_REGISTRY | HighHeelBGZ::pack/unpack to raw [u64;256]; spo_to_bytes/bytes_to_spo LE byte packing; CONTAINER_WORDS/HEEL_WO… | 2KB family-basin container (HEEL metadata + up to 240 CausalEdge64) + basin-merge accumulator + per-lens encoding-distortion profiles | none (large eprintln-heavy streaming experiment test is intentional diagnostic, test-only) | none | HW (SIMD/codec hardware, palette/distance math) | +| `jit.rs` | pub | crate::thinking::{ScanParams, ThinkingStyle} | JitTemplate, KernelHandle, JitCompiler trait, StyleRegistry trait, JitError | none | JIT compilation contract: jitson template -> Cranelift-compiled kernel, cached by thinking style | none (KernelHandle raw fn_ptr Send/Sync unsafe impls carry inline safety rationale) | none | W3 templates (compiled thinking / JIT) | +| `kanban.rs` | pub | crate::collapse_gate::MailboxId, crate::mul::GateDecision | KanbanColumn (6-phase Rubicon DAG), KanbanMove, ExecTarget, RubiconTransitionError | KanbanMove const size assert (<=16B airgap microcopy); no byte serialization | 4-phase (+2 terminal) mailbox lifecycle kanban contract shared by planner (emits), ractor (drives), surrealdb (projects) | none | none | W2 kanban executors | +| `lib.rs` | pub | all ~60 crate submodules | crate root; re-exports canonical_node/class_view/collapse_gate/episodic_edges/head2head/kanban/ogar_codebook/… | none (aggregation point only) | Zero-dep contract crate root: module tree + canonical re-exports for planner/ladybug-rs/in-tree consumers | documents crewai-rust/n8n-rs eviction (2026-06-21) as historical provenance, not live debt | none | CORE (V3-neutral crate root) | +| `literal_graph.rs` | pub | std::collections::HashMap; core only otherwise | LiteralNode, LiteralEdge, LiteralGraph, GraphStats, ingest_aiwar_json() | none | Literal (string-labelled) AriGraph faithful to the original paper: O(1) node lookup + BFS association, minimal zero-serde JSON ingest | hand-rolled minimal JSON parser (no serde) for ingest_aiwar_json — fragile on malformed input | none | CORE (V3-neutral AriGraph) | +| `mail.rs` | pub | core::future::Future only | MailParser trait, ParseHints, PartRef, AttachmentRef, ThreadLinker trait | none | Email parsing contract (async MIME parse + thread linking) for the callcenter external membrane | none | none | W5 consumers (callcenter email surface) | +| `manifest.rs` | pub | generated include!() from OUT_DIR (ogit_namespace.rs, manifest_metadata.rs) | Escalation, StackProfile, ManifestEntry, manifest_metadata() binary-search lookup | none | Hand-written support types (~60 LOC) for build.rs-generated OGIT manifest metadata: RBAC policy + stack knobs per domain | none | none | CORE (V3-neutral manifest codegen support) | +| `materialize.rs` | mixed | recipe_kernels::{kernel,GateState,ThoughtCtx,SD_BLOCK,SD_FLOW}; recipes::{recipe,Bucket,Mechanism,Tier} | select_tactic(), materialize(), Trace, Step, awareness_is_causal(), recompute_free_energy(), HOMEOSTASIS_FLOOR | none | Closes the F->34->F active-inference dispatch loop: selects 1-of-34 reasoning tactics from awareness (free_energy primary axis), runs+folds… | none | none | CORE (cognitive dispatch loop, V3-neutral) | +| `mul.rs` | mixed | crate::qualia::QualiaI4_16D; core::arch::{x86_64,aarch64} SIMD intrinsics | SituationInput, MulAssessment, TrustQualia/Texture, DkPosition, Homeostasis, FlowState, GateDecision, MulThre… | none (repr(u8) SIMD layout invariant D-CSV-13b, not byte-wire LE) | Meta-Uncertainty Layer contract: DK/trust/flow/compass gate assessment from f64 SituationInput or packed i4 qualia, w/ runtime AVX-512+NEON… | TODO: ontology_context_id plumb-through (Wave-2 deliverable) still passes hardcoded 0 | richer MulAssessment also lives in lance-graph-planner::mul (this is the zero-dep carrier-method version) | CORE (MUL/gate contract; consumed by but not specific to V3… | +| `nan_projection.rs` | mixed | crate::canonical_node::{NodeRow, ValueTenant} | f32_bits_nonfinite(), NanReport, project_energy_nonfinite(), energy_all_finite() | u32::from_le_bytes over NodeRow.value Energy tenant slab (fixed-offset f32 bit read) | Read-only NaN/Inf sweep over the SoA Energy tenant -- the demoted singleton BindSpace, kept ONLY as a projection surface (operator ruling 2… | none | none | W6 monitor/retirement (explicit demotion of singleton-BindS… | +| `nars.rs` | pub | crate::grammar::inference::NarsInference | InferenceType(5), QueryStrategy(5), to_mantissa()/from_mantissa(), SemiringChoice(5) | none | Canonical NARS inference-type taxonomy shared by n8n-rs/planner/crewai-rust; to_mantissa bridges to CausalEdge64's signed i4 mantissa gramm… | none | NARS InferenceType x3 -- this is the contract-canonical copy | CORE (NARS taxonomy, V3-neutral) | +| `ocr.rs` | pub | crate::canonical_node::{classid_read_mode, EdgeBlock, NodeGuid, NodeRow, ValueTenant, VALUE_SLAB_LEN} | OcrProvider trait, PageImage, OcrOpts, Bbox, BlockKind(+entity_type), LayoutBlock::to_node_row() | writes EntityType/Energy ValueTenant offsets via to_le_bytes into NodeRow.value slab, schema-gated by classid… | OCR contract; the keystone transcode of one recognized layout block into a canonical SoA NodeRow, honoring the resolved ReadMode value sche… | none | none | W1 envelope/ownership (canonical_node ReadMode/ValueTenant … | +| `ogar_codebook.rs` | pub | self-contained; NodeGuid classid values referenced in tests | ConceptDomain, canonical_concept_domain(), AppPrefix, render_classid(), CODEBOOK table, LabelDTO, ClassidOrde… | LabelDTO::id_le() u16 to_le_bytes; classid canon/custom u16-half bit composition (the ONE flippable classid l… | Wire-compat mirror of OGAR's ogar-vocab codebook + the flippable canon-high classid half-order composition routing classid to ConceptDomain… | documented limitation: a future canon==0x1000 would be indistinguishable from the V3 marker under classid_can… | declared wire-compat mirror of OGAR ogar_vocab::CODEBOOK/ConceptDomain/app (not accidental duplication; drift… | W6 monitor/retirement (CLASSID_ORDER=CanonHigh flip + 0x100… | +| `ontology.rs` | pub | crate::cam::CodecRoute; crate::property::{ActionSpec,LinkSpec,Marking,PrefetchDepth,PropertyKind,Schema,Seman… | Locale, Label, EntityTypeId, Ontology+builder, ModelBinding, ModelHealth, SimulationSpec, ExpandedTriple, Sch… | none | Foundry-equivalent ontology contract (stages 3-5): ModelBinding/ModelHealth/SimulationSpec + Schema-to-SPO-triple expansion + Object Explor… | none | none | CORE (ontology/Foundry-parity contract, V3-neutral) | +| `orchestration.rs` | pub | crate::nars::InferenceType; crate::plan::ThinkingContext; crate::thinking::ThinkingStyle | StepDomain(incl. Kanban), DomainProfile, Escalation, VerbTaxonomyId, UnifiedStep, StepId, StepStatus, Orchest… | none | THE unified step-routing contract replacing crewai-rust StepRouter / n8n-rs crew_router / ladybug-rs HybridEngine; StepDomain::Kanban route… | cfg(feature="trajectory-audit") step_trajectory_hash() is unimplemented!() -- explicit stub, do not call unti… | none (this IS the canonical replacement for 3 previously-duplicated routers) | W2 kanban executors (StepDomain::Kanban is the planner/ract… | +| `orchestration_mode.rs` | pub | crate::thinking::{FieldModulation, ThinkingStyle} | InferenceOp(10), CausalMask(8, Pearl 2^3), SurvivorProjection, decompose_survivors(), Hypothesis+lifecycle, I… | none | Multi-stage inference DAG orchestrator: fan-out->explain->form->test pipeline with Pearl 2^3 causal decomposition, hypothesis testing, and … | none | none | CORE (inference-DAG/RL engine, predates V3 ruling) | +| `pearl_junction.rs` | mixed | crate::hhtl::NiblePath; crate::nars::InferenceType | PearlJunction(Chain/ChainRev/Fork/Collider/Unrelated), EdgePair::classify(), classify_junction() | none (identity compare over packed NiblePath, not byte-wire) | Pure classifier mapping a pair of SPO edges to Pearl's causal-junction taxonomy via HHTL NiblePath identity equality; bridges SPO syntax to… | #[deprecated] NarsRule enum + nars_rule() method (since 0.2.0) kept as back-compat shim for PR #456, supersed… | explicitly avoids a parallel NARS-rule taxonomy by sourcing crate::nars::InferenceType | CORE (HHTL/SPO causal classification, V3-neutral) | +| `persona.rs` | pub | crate::a2a_blackboard::{ExpertEntry, ExpertId}; crate::external_membrane::ExternalRole | PersonaCard, RoutingHint(+is_implicit()) | none | Identity bundle for agent-card personas on the Layer-1 A2A blackboard (role+card+trust); documents VSA-binding-is-stack-side-only BBB invar… | none | none | CORE (A2A runtime persona contract, orthogonal to V3 mailbo… | +| `plan.rs` | pub | crate::cognitive_shader::RungLevel; crate::mul::{GateDecision,MulAssessment,SituationInput}; crate::nars::{In… | ThinkingContext, PlanResult(incl. emitted_edges), QueryFeatures, PlanError, StrategySelector, PlannerContract… | PlanResult.emitted_edges: Vec little-endian CausalEdge64/EpisodicEdges64 words -- the radix key the vart… | The single PlannerContract trait lance-graph-planner implements and ladybug-rs/crewai-rust/n8n-rs consume for the MUL->ThinkingStyle->strat… | none | none | CORE (planner contract, V3-neutral) | +| `property.rs` | pub | crate::cam::CodecRoute | PropertyKind, PropertySpec, PropertySchema, Schema+SchemaBuilder, LinkSpec, PrefetchDepth, ActionSpec, Markin… | none | AriGraph SPO predicate classification (Required/Optional/Free -> codec route + NARS floor) plus the full ontology property surface: schema … | none | none | CORE (property/schema contract, V3-neutral) | +| `proprioception.rs` | mixed | none external | AXIS_LABELS[11], ProprioceptionAxes, StateAnchor(7), AnchorState, ANCHOR_REGISTRY, StateReport, StateClassifi… | none | 11D proprioceptive state-classification contract: 7 calibration anchors an agent's felt-state vector is matched against via L2 nearest-neig… | none | none | CORE (proprioception contract, V3-neutral) | +| `qualia.rs` | pub | crate::proprioception::{CORE_AXES, DRIVE_AXES, STATE_DIMS} | QUALIA_DIMS=17, AXIS_LABELS, QualiaVector, qualia_to_state(), QUALIA_I4_DIMS=16, QualiaI4_16D(packed u64 get/… | QualiaI4_16D repr(C,align(8)) packed 4-bit-per-dim u64 layout (16 signed i4 lanes, get/set via shift+mask) | 17D qualia observation-vector contract + its 9x-compressed i4-packed 8-byte sibling QualiaI4_16D, plus the canonical 17D->11D proprioceptiv… | none | none | CORE (qualia observation contract, V3-neutral) | +| `quorum.rs` | mixed | crate::escalation::{CouncilVerdict, InnerCouncil}; crate::a2a_blackboard::Blackboard (blocked signature) | AxisProjection(settled/contested/is_contested/nars_frequency), AxisSignal, quorum_project()[todo!()], quorum_… | none | D-ATOM-3 per-axis quorum projection: maps InnerCouncil deliberation to a NARS-truth-shaped AxisProjection; contested (split) verdicts hand … | BLOCKED: quorum_project(), quorum_project_blackboard(), resolve_contest() are all todo!() scaffolds pending D… | none | CORE (atom-mailbox-substrate-v1 D-ATOM-3 scaffold, predates… | +| `rbac.rs` | pub | crate::class_view::FieldMask; crate::property::PrefetchDepth; crate::ogar_codebook::classid_canon_compat | ScopeSpec(+DENY/intersect), ClassId, Operation, ClassRbac trait(4 methods), OpMask(READ/WRITE/CREATE/DELETE/A… | none (routes via classid_canon_compat but carries no raw byte layout itself) | Classid-keyed RBAC grant-resolution trait (OGAR keystone Sec4/Sec11): 4-axis authorization -- verb op-mask, role-hierarchy fold, row-scope … | CONJECTURE noted inline: roles_reaching() hook not yet consumed by authorize()/authorize_scoped() | none (single canonical trait home; lance-graph-rbac re-exports it) | W1 envelope/ownership (classid-keyed access-grant surface, … | +| `reasoning.rs` | pub | core::future::Future | Reasoner trait, ReasoningContext, ReasoningKind, EvidenceRef, Budget | none | Thin line-of-business reasoning adapter contract composing the existing thinking/faculty/plan surfaces for scoped async conclusion derivati… | none | none | CORE (thin adapter contract, V3-neutral) | +| `recipe.rs` | pub | crate::jit::{JitError, KernelHandle}; forward stubs for D-ATOM-1 (atoms::I4x32/Atom) | StyleRecipe, PersonaRecipe, Beta, RecipeTemplate, register_recipe() | none | Composition layer atoms->StyleRecipe->PersonaRecipe->KernelHandle; JIT targets the fused recipe not per-atom dot | entire compile path is todo!() — BLOCKED on D-ATOM-1 (I4x32) and StyleRegistry::register_recipe API extension | none | W3 templates (compiled recipe/persona JIT scaffold) | +| `recipe_kernels.rs` | pub | crate::recipes::{recipe, Bucket, Recipe} | ThoughtCtx, GateState, Outcome, ThoughtField, ThoughtMask, Tactic trait, 34 tactic structs (Rte..Hkf), kernel… | none | 34 working reasoning-tactic kernels implementing uniform Tactic trait over shared substrate-marker ThoughtCtx (CollapseGate SD/FE/NARS/rung) | none; heavily self-tested including anti-theater checklist-variance tests | none (executable counterpart to recipes.rs metadata) | W3 templates (34 executable thinking tactics) | +| `recipes.rs` | pub | nothing external (self-contained static data) | Tier, Mechanism, Bucket, Coverage, Recipe, RECIPES[34], recipe(), recipe_by_code(), by_mechanism(), causal() | none | Static catalogue of the 34 LLM reasoning tactics with Tier/Mechanism/Bucket/SPO-2cubed metadata; catalogue spine for recipe_kernels.rs | none | none | W3 templates (recipe catalogue metadata) | +| `repository.rs` | pub | core::future::Future | EntityKey, Batch trait, EntityStore trait, EntityWriter trait | none | Zero-dep row-oriented entity store read/write contract consumed by smb-bridge MongoConnector/LanceConnector implementations | none | none | CORE (V3-neutral query engine) | +| `savants.rs` | pub | crate::nars::{InferenceType, SemiringChoice}, crate::reasoning::ReasoningKind, crate::thinking::StyleCluster | other_kind consts, Savant, SAVANTS[25], savant(), savant_by_name(), unaligned(), Savant::query_strategy() | none | 25-entry Odoo delegated-reasoner roster mapping OGIT family x ReasoningKind x InferenceType x Semiring x StyleCluster for AXIS-B decisions | 9+ savants carry family=None awaiting a Layer-2 OGIT alignment axiom (documented follow-on, id 16 intentional… | none | CORE (V3-neutral query engine) | +| `scenario.rs` | pub | nothing external (facade; docs reference downstream VersionedGraph/WorldModelDto/Intervention) | ScenarioBranch, ScenarioDiff, ScenarioWorld trait | none | Named counterfactual branch/diff facade composing Pearl Rung-3 intervention + Lance dataset versioning + world-model gestalt diff | none in-file; concrete ScenarioWorld impls deliberately deferred downstream (documented, not debt) | none (module doc explicitly rejects scenario_id-column and new-crate alternatives) | CORE (V3-neutral query engine) | +| `scheduler.rs` | pub | crate::kanban::{ExecTarget, KanbanColumn, KanbanMove}, crate::soa_view::MailboxSoaView | DatasetVersion, VersionScheduler trait, NextPhaseScheduler | none | IN-direction reactive seam: lowers a Lance dataset-version event to the next legal KanbanMove for the mailbox owner to apply | none | none (documented dual of soa_view::MailboxSoaOwner OUT direction) | W2 kanban executors | +| `sensorium.rs` | pub | crate::mul::{DkPosition, FlowState, TrustTexture} | GraphSignals, GraphBias, suggested_bias(), HealingType, AgentStyle, OrchestratorMode, OrchestratorStatus, Ste… | none | Real-time knowledge-graph health-signal + orchestrator status/step contract; arigraph produces, MUL/consumers read and request healing | none | none | CORE (V3-neutral query engine) | +| `sigma_propagation.rs` | pub | nothing external (self-contained math, cross-checked against crates/jc::ewa_sandwich probe) | Spd2, ewa_sandwich(), ewa_inverse(), log_norm_growth(), pillar_5plus_bound() | none | EWA-Sandwich kernel for multi-hop 2x2 SPD-matrix propagation with PSD-preservation + Koestenberger-Stark concentration bound (Pillar 6 veri… | none; explicitly zero-dep, standalone regression proof lives in a separate crate on purpose | none | HW (SIMD/codec hardware) | +| `sla.rs` | pub | nothing external | SlaPolicy, SlaPriority, TenantId, TenantScope | none | Outside-BBB SLA policy (LF-91) and multi-tenant isolation scope (LF-92) types for external REST/gRPC consumer contracts | none | none | CORE (V3-neutral query engine) | +| `soa_envelope.rs` | pub | crate::collapse_gate::MailboxId | ENVELOPE_LAYOUT_VERSION, ColumnKind, ColumnDescriptor, EnvelopeError, SoaEnvelope trait | SoaEnvelope trait: ColumnDescriptor/ColumnKind byte geometry, ENVELOPE_LAYOUT_VERSION=2, verify_layout(), row… | Canonical SoA envelope LE byte-geometry contract: where columns sit in the row stride, cycle stamp, mailbox_owner() ownership; zero-copy cr… | none; v1->v2 layout migration already handled correctly with version gate (HelixResidue 48B->6B slip fix) | none; explicitly complementary to ndarray::simd::MultiLaneColumn (column-level vs envelope-level) | W1 envelope/ownership | +| `soa_graph.rs` | pub | crate::canonical_node::{NodeGuid, NodeRow}, crate::graph_render::{GraphSnapshot, RenderEdge, RenderNode}, cra… | DomainSpec, OSINT_GOTHAM, FMA_ANATOMY, PROJECT, ERP, project_snapshot(), AnchorHop, nearest_anchor() | reads only the 32-byte NodeRow head (key+edges) via NodeGuid classid/family/identity (tail_variant-dispatched… | Projects the canonical SoA node head into a Neo4j/Gotham-style GraphSnapshot: family nodes + 16-adapter edge resolution + anchor hop ranking | none; guid-v2/v3-tail feature dispatch correctly follows I-LEGACY-API-FEATURE-GATED | none | W1 envelope/ownership | +| `soa_view.rs` | pub | crate::collapse_gate::MailboxId, crate::kanban::{KanbanColumn, KanbanMove, RubiconTransitionError} | IdentityPlane, MailboxSoaView trait, MailboxSoaOwner trait | zero-copy column-borrow vocabulary over the mailbox SoA (energy/edges_raw/meta_raw/entity_type, EdgeBlock, id… | Transparent zero-copy read view over the ONE per-mailbox SoA (R1); owner (mutating, phase-advancing) vs view (read-only) split | several accessors deliberately deferred to None (qualia, EpisodicWitness64, row_for_local_key) pending first … | none | W1 envelope/ownership | +| `splat.rs` | pub | nothing external (zero-dep) | SplatChannel, TriadicProjection, ReasoningWitness64, AwarenessPlane16K, CamPlaneSplat, SplatPlaneSet, CamSpla… | AwarenessPlane16K = [u64;256] packed 2KB plane, repr(C)/repr(u8) structs, deterministic q8 encoding, no float… | Gaussian-splat -> CAM-plane deposition contract: witness-weighted semantic pressure projected into CAM/COCA awareness planes as a hot appro… | none; explicitly zero-dep, deterministic, no serde | none | HW (SIMD/codec hardware) | +| `tax.rs` | pub | core::fmt::Debug, core::marker::PhantomData | TaxEngine trait, TaxPeriod, PeriodKind, Jurisdiction, PostingBatchRef, RuleBundle trait | none | Zero-dep sandboxed tax-declaration contract; TaxEngine::collect must be a pure deterministic function over a posting batch | none | none | CORE (V3-neutral query engine) | +| `tenant_counter.rs` | mixed | crate::canonical_node::{ValueTenant, VALUE_TENANTS} | N_TENANTS, tenant_update(), tenant_count() [feature-gated], snapshot() [feature-gated] | none | Cheap atomic per-ValueTenant update counters for debug instrumentation of the SoA write cascade; compile-time no-op unless tenant-counters … | none; feature-gated by design for zero-cost default | none | W1 envelope/ownership | +| `thinking.rs` | pub | super::mul::MulAssessment (trait signature only) | ThinkingStyle(36), StyleCluster, PlannerCluster, FieldModulation, ScanParams, ThinkingStyleProvider trait | FieldModulation::to_fingerprint() -> [u8;7] BindSpace storage prefix 0x0D packing | SINGLE SOURCE OF TRUTH for the 36 thinking styles / 6 clusters / tau addresses, consumed by crewai-rust, n8n-rs, ladybug-rs, lance-graph-pl… | none; header documents the resolved reconciliation of the planner's prior 12-style/4-cluster duplicate | ThinkingStyle: 4 copies per CLAUDE.md Type Duplication Map — this file is the canonical one | W3 templates | +| `transaction/bulk.rs` | pub | super::ctx::{Context,DolceCtx,FibuCtx,OgitCtx,OwlCtx}, cognition::entity types | Bulk struct (Stage-1 unit placeholder) + 4 trait impls | none | Stage-1 placeholder batch-import transaction context: per-batch Lance snapshot, lazy per-epoch Baton flush | 4 todo!() unimplemented trait bodies (Stage 2); Stage-1 is a unit-struct placeholder only | sibling shape of Interactive/Periodisch (distinct SLA by design, not accidental dup) | LEGACY Baton-emission-queue design predates V3 zero-copy to… | +| `transaction/ctx.rs` | pub | cognition::entity::{DolceCategory,FibuAlignmentRef,OgitUriRef,OwlClassRef} | Context (sealed trait), OgitCtx, OwlCtx, DolceCtx, FibuCtx traits | none | Five-verb-algebra per-stage context traits (Raw->WithOgit->WithOwl->WithDolce->Normalized), sealed to 3 | none in this file (todo!() bodies live in the 3 implementors, not here) | none | CORE sealed trait definitions | +| `transaction/interactive.rs` | pub | super::ctx traits, cognition::entity types | Interactive struct (Stage-1 unit placeholder) + 4 trait impls | none | Stage-1 placeholder single-entity context: eager Baton fan-out, live Lance version, sync DFS cascade | 4 todo!() unimplemented trait bodies (Stage 2 placeholder) | sibling shape of Bulk/Periodisch (distinct SLA by design) | LEGACY Baton-emission-queue design predates V3 zero-copy to… | +| `transaction/mod.rs` | pub | bulk, ctx, interactive, periodisch submodules | re-exports Bulk, Context, DolceCtx, FibuCtx, OgitCtx, OwlCtx, Interactive, Periodisch | none | Module root + doc table comparing the 3 typed transaction-context SLA regimes (op site/version/cascade) | none in this file directly | none | LEGACY doc table centers on Baton-emission terminology (pre… | +| `transaction/periodisch.rs` | pub | super::ctx traits, cognition::entity types | Periodisch struct (Stage-1 unit placeholder) + 4 trait impls + frozen_lance_version() | none | Stage-1 placeholder fiscal-close context: frozen Lance version, JIT fixed-point, epochal Baton emission | 5 todo!() unimplemented bodies (Stage 2), including frozen_lance_version() | sibling shape of Interactive/Bulk (distinct SLA by design) | LEGACY Baton-emission-queue design predates V3 zero-copy to… | +| `unichar.rs` | pub | nothing external | utf8_step(), utf8_to_utf32() | none | Faithful Tesseract UNICHAR UTF-8 byte-parity transcode (256-entry lead-byte step table + decode) preserving overlong-encoding quirks, OGAR … | none; quirks (overlong C0/C1 acceptance) are deliberately preserved, not fixed, per behaviour-preservation ru… | none (sibling of unicharset.rs, different concept) | CORE (V3-neutral query engine) | +| `unicharset.rs` | mixed | std::collections::HashMap, std::path::Path; parses .unicharset text format | pub struct UniCharSet (load_from_str/file, id_to_unichar, unichar_to_id, get_is*, script, other_case, dump*) | none | Tesseract UNICHARSET content-store adapter: id<->unichar bijection + properties/script/other_case parsed for the byte-parity probe vs C++ o… | none | none | CORE V3-neutral OGAR content store | +| `unicharset_adapter.rs` | pub | crate::codegen_manifest::{methods_for, ClassMethods}; crate::unicharset::UniCharSet | pub trait UniCharSetStore; enum UniCharCall/UniCharOut/DispatchError; fn invoke_unicharset | none | Keystone dispatcher: classid -> ClassView method-composition gate -> classid-keyed content store -> UniCharSet adapter leaf; proves core-fi… | none | none | CORE classid ClassView dispatch keystone | +| `view_angle.rs` | pub | none (zero-dep); conceptually pairs with class_view::FieldMask and head2head | pub struct ViewAngle(u8) with new/canonical/index, MAX=16 | none | 4-bit view-schema selector: which inherited (OGIT-class) attention pattern applies over a row's presence bitmask | none | none | CORE class-inherited attention selector | +| `vsa/mod.rs` | pub | none | pub mod roles | none | Module root scoping 256-D CAM-PQ VSA role-key algebra, explicitly distinct from 16384-D grammar::role_keys | none | none (deliberately scoped apart from grammar/role_keys.rs 16K-dim algebra) | CORE VSA scope-boundary doc | +| `vsa/roles.rs` | pub | none (self-contained FNV-64/xorshift64 PRNG) | make_role_key(), make_palette_id(), CAM_PQ_DIM, S/P/O_SLICE_START/END consts | none | 256-D bipolar disjoint-slice S/P/O VSA identity role keys for WitnessIndexCamPq SPO adapter | none | none | CORE VSA identity-key generator | +| `witness_table.rs` | pub | const-generic array; conceptually resolves contract::collapse_gate::MailboxId (u32) | pub struct WitnessEntry{mailbox_ref,spo_fact_ref}; pub struct WitnessTable{entries} with new/get/… | none | Per-cohort column-type primitive resolving the 6-bit W-slot field of CausalEdge64 v2 to (mailbox_ref, spo_fact_ref) for Markov belief-updat… | scaffold-only per file docs: not yet wired into CausalEdge64/MailboxSoA/emission path (explicit later slice, … | none (explicitly distinguished in doc comment from perturbation-sim::witness numeric arc) | W1 envelope/ownership mailbox witness scaffold | +| `world_map.rs` | pub | crate::proprioception::{AnchorState, DriveMode, StateAnchor, StateReport, AXIS_LABELS, STATE_DIMS} | pub struct WorldMapDto; pub trait WorldMapRenderer; pub struct DefaultRenderer | none | Minimal numeric state-map DTO (vector+anchor+drive) with pluggable renderer trait so consumers apply own labels without contract vocabulary… | #[allow(unused_imports)] on AnchorState pending TD-WM-1 AnchorState->WorldMap blending function | complements world_model.rs::WorldModelDto (heavier full quadrant snapshot); same proprioception domain, light… | CORE consumer-facing proprioception DTO | +| `world_model.rs` | pub | crate::proprioception::{ProprioceptionAxes, StateReport}; crate::qualia::QualiaVector | pub struct WorldModelDto (self/user/field/context quadrants); SelfState/UserState/FieldState/ContextState/Ges… | none | Agent situational-awareness snapshot DTO (self/user/field/context + qualia + proprioception + cycle fingerprint) for downstream consumer cr… | none | complements world_map.rs::WorldMapDto (minimal numeric variant of the same proprioception domain) | CORE consumer-facing world-model DTO | + +## lance-graph-planner (83 files) + +| File | Vis | Consumes | Emits | LE contract | Function / benefit | Tech debt | Duplication | V3 wave | +|---|---|---|---|---|---|---|---|---| +| `adjacency/batch.rs` | pub | no external crate imports - pure Vec batch structures | AdjacencyBatch (targets_for/edge_ids_for/intersect), IntersectionResult | none | Flat Arrow-ListArray-shaped adjacency batch + sorted-merge intersect() - Kuzu's worst-case-optimal join primitive for A-B-C traversal | none | none | CORE (V3-neutral query engine) - vectorized traversal batch | +| `adjacency/csr.rs` | pub | super::batch::AdjacencyBatch, super::properties::EdgeProperties | AdjacencyStore (CSR+CSC, adjacent/adjacent_incoming/batch_adjacent/from_edges) | none | Core columnar adjacency storage: dual CSR (outgoing) + CSC (incoming) compressed sparse structures, one store per relationship type | none | CSR adjacency: one of 5 known implementations across the workspace per CLAUDE.md Type Duplication Map | CORE (V3-neutral query engine) - CSR/CSC adjacency ground | +| `adjacency/distance.rs` | pub | super::batch::AdjacencyBatch, super::csr::AdjacencyStore | adjacent_fingerprint_distance() -> AdjacentDistanceResult | none | Hamming-distance scan restricted to adjacent node pairs (not full table scan) - resonance filtering scoped to the traversal graph | hamming_distance() is a scalar fallback; doc comment says production path should call ndarray's AVX-512 VPOPC… | none | CORE (V3-neutral query engine) - adjacent-only distance scan | +| `adjacency/mod.rs` | pub | batch, csr, distance, propagate, properties submodules | pub use AdjacencyBatch, AdjacencyStore, EdgeProperties (module doc + re-exports) | none | Module doc + re-exports for the P0 adjacency substrate: CSR/CSC storage, batch traversal, distance scan, truth propagation, edge props | doc describes a planned 'VSA Focus-of-Awareness' 10K Hamming prefilter that is not yet implemented | none | CORE (V3-neutral query engine) - adjacency module root | +| `adjacency/propagate.rs` | pub | super::batch::AdjacencyBatch, super::csr::AdjacencyStore, crate::nars::TruthValue, physical::accumulate::{Sem… | adjacent_truth_propagate() -> Vec<(u64, TruthValue)> | none | One-pass NARS truth propagation along adjacency edges via semiring multiply/add, merging at fan-in targets - semiring meets adjacency | none | none | CORE (V3-neutral query engine) - truth propagation on adjac… | +| `adjacency/properties.rs` | pub | std::collections::HashMap | EdgeProperties (float/int/string/fingerprint columns), with_nars_truth(), truth_value(), get_float/get_finger… | none | Columnar edge-property storage (Arrow-compatible layout): NARS truth_f/truth_c columns plus generic float/int/string/fingerprint columns | none | none | CORE (V3-neutral query engine) - columnar edge properties | +| `api.rs` | pub | physical::CamPqScanOp, selector::StrategySelector, traits::*, thinking::style, mul::gate::GateDecision | Planner{plan,plan_with_style,plan_assessed}, QueryLanguage::detect, PolyglotResult, CamSearch top_k/encode | none | Ergonomic same-binary API: Planner wraps PlannerAwareness; QueryLanguage auto-detects 4 dialects; CamSearch wraps PQ scan/encode | CamSearch::top_k() calls self.tables.as_ref().expect(...) if prepare_query() wasn't called first — panics not… | none | CORE (V3-neutral query engine) - planner ergonomic API | +| `cache/candidate_pool.rs` | pub | kv_bundle::{bundle_into, HeadPrint} | Phase, HeadAddress, Candidate, CandidatePool (add/emit/update_phase) | none | Ranked autocomplete candidate pool; tracks already-said bundle + Exposition→Coda composition phase from surprise/alignment/contradiction | none | none | CORE autocomplete cache candidate ranking pool | +| `cache/convergence.rs` | pub | kv_bundle::HeadPrint, nars_engine::{SpoHead,MASK_SPO}, ndarray::hpc::{bgz17_bridge,palette_distance} | PlaneDistance, triplet_to_headprint, headprint_to_spo, triplets_to_palette_layers, run_convergence | none | p64 convergence highway: AriGraph SPO triplets → Base17 fingerprints → [[u64;64];8] palette layers → CognitiveShader hot path | none | none — wraps ndarray canonical SpoDistanceMatrices rather than reimplementing | HW palette codec convergence AriGraph bridge | +| `cache/kv_bundle.rs` | pub | ndarray::hpc::bgz17_bridge::Base17 (re-exported as HeadPrint) | HeadPrint, bundle_into, unbundle_from (deprecated), AttentionMatrix (get/set/surprise/row_divergence) | none | VSA superposition KV store: bundle/unbundle i16 HeadPrints into a holographic gestalt at HEEL/HIP/TWIG resolution | unbundle_from #[deprecated]: NOT the exact inverse of weighted-average bundle_into; gestalt drifts over epoch… | HeadPrint is a type alias for ndarray's Base17 (Base17 x3 duplication family) | HW Base17 VSA bundle unbundle codec | +| `cache/lane_eval.rs` | pub | candidate_pool::{Candidate,HeadAddress}, kv_bundle::{AttentionMatrix,HeadPrint}, triple_model::{DkPosition,Tr… | Tension (analytical/creative/focused/integrative), LaneEvaluator::{evaluate, evaluate_triple} | none | Fires all 4096 interdependent attention heads through an Euler-gamma noise floor to produce ranked candidates per DK-selected Tension | none | none | CORE attention lane evaluator thinking tension | +| `cache/mod.rs` | pub | candidate_pool, convergence, kv_bundle, lane_eval, nars_engine, triple_model submodules | module re-exports only | none | Module root for AutocompleteCache: documents HHTL resolution levels HEEL 8x8 / HIP 64x64 / TWIG 256x256 | none | none | CORE autocomplete cache module root docs | +| `cache/nars_engine.rs` | pub | triple_model::{truth_revision,Truth}, causal_edge::{tables,CausalEdge64,CausalMask,PlasticityState} | SpoHead, MASK_* Pearl consts, SpoDistances, Inference enum, StyleVector fns, NarsEngine | packs/unpacks causal_edge::CausalEdge64 (8B packed edge, defined in causal_edge crate) via to/from_causal_edge | Causal NARS inference engine over SPO palette-indexed 8-byte attention heads; Pearl 2^3 masks, O(1) distance tables, style scoring | multiple TODO(PR-LL-4): confidence modifiers (0.85/0.70) and mask overrides are TUNED-LATER placeholders pend… | local Inference enum duplicates causal_edge::edge::InferenceType / contract nars.rs InferenceType (NARS Infer… | CORE NARS causal inference Pearl masks | +| `cache/triple_model.rs` | pub | kv_bundle::{AttentionMatrix,HeadPrint}, ndarray::hpc::nars::NarsTruth (aliased Truth) | Plasticity, truth_revision, truth_unknown, DkPosition, ModelState, TripleModel | none | Self/user/impact triple of 64x64 attention matrices; DK-position transitions and Friston free-energy prediction error | none | DkPosition may overlap mul/dk.rs DkPosition enum — not confirmed identical without cross-read | CORE self user impact attention model | +| `compose.rs` | pub | ir::{Arena,LogicalOp,LogicalPlan}, traits::{PlanContext,PlanInput,PlanStrategy}, PlanError | pub fn compose_and_execute(strategies, context) -> Result | none | Runs selected strategies in phase order over a shared Arena, folding PlanInput through each strategy.plan() call | none | none | CORE (V3-neutral query engine) - pipeline composition | +| `elevation/budget.rs` | pub | super::ElevationLevel, crate::thinking::style::ThinkingCluster | PatienceBudget, budget_for_cluster | none | Maps ThinkingCluster (Convergent/Divergent/Attention/Speed) to latency/result/memory thresholds and elevation ceiling | none | none | CORE elevation patience budget per cluster | +| `elevation/decompose.rs` | pub | crate::physical::Morsel | FanOutAnalysis, analyze_fanout, decompose_fanout | none | Estimates variable-length-path fan-out explosion and decides whether to split a Morsel into independent sub-query partitions | decompose_fanout leaves partitioned columns empty; comment says 'Real impl: slice Arrow columns' | none | CORE fan-out detection query decomposition | +| `elevation/homeostasis.rs` | pub | budget::PatienceBudget, super::ElevationLevel, crate::mul::homeostasis::FlowState | modify_budget | none | MUL FlowState (Anxiety/Flow/Boredom/Apathy) scales a PatienceBudget's latency/result/memory limits and ceiling at runtime | none | none | CORE MUL flow state budget modulation | +| `elevation/learning.rs` | pub | super::{ElevationEvent, ElevationLevel} | ElevationHistory, ElevationLearner (observe/predict_start_level/hash_features) | none | Records elevation events per query and learns feature-hash → majority final level to predict starting elevation preemptively | hash_features is a simple bit-packed hash, comment admits 'production would be a proper locality-sensitive ha… | none | CORE elevation history RL feedback learner | +| `elevation/mod.rs` | pub | lance_graph_contract::cognitive_shader::RungLevel, budget submodule | ElevationLevel (Point..Async), ElevationTrigger, ElevationEvent, should_elevate, from_rung | none | Dynamic elevation stack (L0 Point..L5 Async): starts cheap, elevates on observed latency/result/memory resistance; calibrated to RungLevel | none | none | CORE dynamic elevation stack cost model | +| `elevation/operator.rs` | pub | budget::PatienceBudget, learning::ElevationHistory, super::{should_elevate,ElevationEvent,ElevationLevel,Elev… | LevelOperator trait, ElevationError, ElevatingOp | none | Physical operator wrapping per-level operators; executes current level, elevates and seeds partial results when budget is exceeded | start_level field marked #[allow(dead_code)] beyond construction | none | CORE elevating physical operator level seed | +| `execute/mod.rs` | pub | crate::physical::{Morsel, PhysicalPlan, Pipeline} | PipelineExecutor, ExecutionResult, toposort | none | Morsel-driven pipeline executor (Kuzudb/Polars pattern): decomposes physical plan into pipelines, topo-sorts, executes per worker thread | decompose() returns a hardcoded single placeholder Pipeline; execute() just accumulates morsel_size as u64 in… | none | CORE morsel pipeline executor stub | +| `ir/expr.rs` | pub | super::Node | ExprNode, AExpr, Literal, BinaryOp, UnaryOp, DataType | none | Arena-allocated expression IR (Polars AExpr pattern) with first-class Resonate/HammingDistance/TruthValue query expressions | none | none | CORE arena expression IR resonance ops | +| `ir/logical_op.rs` | pub | super::Node, super::ExprNode | LogicalOp (~25 variants), Direction, JoinType, AggregateExpr, ScanStrategy, SemiringType, CollapseGate | none | Logical operator vocabulary merged from lance-graph+Kuzudb; adds resonance BROADCAST→SCAN→ACCUMULATE→COLLAPSE query operators | none | local CollapseGate (flow/hold f64 thresholds, doc says 'from agi-chat's CollapseGate') duplicates the superse… | LEGACY superseded CollapseGate BROADCAST SCAN operator | +| `ir/mod.rs` | pub | expr, logical_op, properties, schema submodules | Node, Arena, LogicalPlan, SubqueryGraph, SubsetIter, SubPlansTable, SubgraphPlans, LogicalPlanRef | none | Arena-allocated plan IR root (Polars Node-handle pattern) plus Kuzudb-style DP join enumeration subgraph bitmask + plan table | none | none | CORE arena plan IR DP join table | +| `ir/properties.rs` | pub | no external imports | PlanProperties, OrderingColumn, is_unique, is_determined_by | none | Tracks UCCs, functional dependencies, ordering and cardinality per plan node for optimizer rules (Hyrise-style) | none | none | CORE plan properties UCC FD ordering | +| `ir/schema.rs` | pub | super::ExprNode (unused import, allowed) | Schema, FactorizationGroup, factorization_encoding, merge, flatten_group | none | Factorization-aware schema (Kuzudb): tracks flat/unflat expression groups, enforcing at-most-one-unflat invariant to avoid exponential blow… | none | none | CORE factorization schema flat unflat groups | +| `lib.rs` | pub | ir::LogicalPlan, mul::{GateDecision,MulAssessment}, selector::StrategySelector, thinking::ThinkingContext | pub struct PlannerAwareness, PlanResult, PlanError; declares adjacency/nars/execute/ir/mul/... modules | none | Crate root: declares all planner submodules, defines PlannerAwareness (16-strategy orchestrator), plan_full/plan_auto entry points | none | none | CORE (V3-neutral query engine) - crate root orchestrator | +| `mul/compass.rs` | pub | super::MulAssessment (trust/dk/homeostasis composite) | navigate(), CompassResult, CompassDecision, CompassNeedles, LearningLoop (Brier calibration) | none | 5-needle compass (Kant/analogy/identity/reversibility/curiosity) scores navigation when the MUL gate can't decide; feeds Execute/Explorator… | none | none | CORE (V3-neutral query engine) | +| `mul/dk.rs` | pub | super::SituationInput (felt/demonstrated competence) | DkPosition enum, detect(), DkDetector (trend: Learning/Overconfident/Stable) | none | Dunning-Kruger curve position detector from felt-vs-demonstrated competence gap; humility_factor gates autonomous action | none | none | CORE (V3-neutral query engine) | +| `mul/escalation.rs` | pub | lance_graph_contract::escalation (InnerCouncil/Epiphany/WisdomMarker/Checklist); super::MulAssessment | verdict_from() -> CouncilVerdict, boot_checklist() -> Checklist (6 HARD + 3 SOFT) | none | Planner-side wiring (D-PERSONA-1) turning MulAssessment into a CouncilVerdict live signal; defines boot-gate checklist for NARS/SoA/thresho… | none | none | CORE (V3-neutral query engine) | +| `mul/gate.rs` | pub | super::{dk::DkPosition, homeostasis::FlowState (unused), trust::TrustTexture, MulAssessment} | GateDecision enum, check() -> Proceed/Sandbox/Compass | none | MUL gate checklist: blocks Mount-Stupid, unmapped complexity, depleted homeostasis, dissonant trust before planning proceeds | #[allow(unused_imports)] on FlowState — dead import awaiting homeostasis gate wiring | none | CORE (V3-neutral query engine) | +| `mul/homeostasis.rs` | pub | super::SituationInput (challenge/skill/allostatic_load) | FlowState enum, Homeostasis struct, CorrectiveAction enum, assess() | none | Csikszentmihalyi flow-state assessor (Flow/Anxiety/Boredom/Apathy) computing allostatic load, corrective action, flow_factor | none | none | CORE (V3-neutral query engine) | +| `mul/mod.rs` | pub | compass/dk/escalation/gate/homeostasis/trust submodules | SituationInput, MulAssessment, assess(), gate_check() | none | Meta-Uncertainty Layer orchestrator: outer planning loop assessing trust/DK/homeostasis/complexity before query planning proceeds | none | none | CORE (V3-neutral query engine) | +| `mul/trust.rs` | pub | super::SituationInput (competence/source/environment/calibration) | TrustQualia struct, TrustTexture enum (Crystalline..Dissonant), assess() | none | Trust-qualia geometric-mean composite of 4 orthogonal dims mapped to a felt texture level gating autonomous operation | none | none | CORE (V3-neutral query engine) | +| `nars/inference.rs` | pub | super::truth::TruthValue; crate::ir::logical_op::SemiringType; crate::thinking::NarsInferenceType | NarsInference enum (Deduction/Induction/Abduction/Revision/Synthesis), apply(), from_thinking_type() | none | Maps NARS inference types to semirings and applies inference rules to edge truth values; bridges thinking-layer Pearl rungs into data-layer… | none | NARS InferenceType duplicated x3 across workspace per CLAUDE.md Type Duplication Map (contract canonical) | CORE (V3-neutral query engine) | +| `nars/mod.rs` | pub | inference, truth submodules | NarsInference, TruthValue re-exports | none | P1 NARS schema+thinking module root: truth values as edge properties, inference rules as semiring operations over them | none | part of the NARS InferenceType x3 duplication set | CORE (V3-neutral query engine) | +| `nars/truth.rs` | pub | none (self-contained f32 truth-value math) | TruthValue struct (frequency, confidence), revise()/deduction()/induction()/abduction()/expectation()/surpris… | none | NARS truth-value algebra (revision/deduction/induction/abduction) — evidence-weighted merge math stored on graph edges | none | NARS truth-value math likely overlaps contract::nars.rs and lance-graph/graph/spo/truth.rs | CORE (V3-neutral query engine) | +| `optimize/mod.rs` | mixed | crate::ir::{Arena, LogicalOp, LogicalPlan, Node}; crate::thinking::ThinkingContext; crate::PlanError; rule::O… | optimize(), RuleResult enum, 9 builtin OptimizerRule impls (Predicate/Projection/Limit pushdown, SIP, Collaps… | none | DataFusion/Hyrise-style composable rule-based optimizer chain over LogicalPlan; thinking-context-conditional SIP insertion, continue-on-rul… | every builtin rule body is `RuleResult::Unchanged // Placeholder` — none of the 9 rules actually rewrite the … | none | CORE (V3-neutral query engine) | +| `optimize/rule.rs` | pub | super::RuleResult; crate::ir::LogicalPlan; crate::thinking::ThinkingContext | OptimizerRule trait, ApplyOrder enum (TopDown/BottomUp) | none | OptimizerRule trait definition (DataFusion pattern): name/apply/apply_order/iterative/max_iterations | none | none | CORE (V3-neutral query engine) | +| `orchestration_impl.rs` | mixed | lance_graph_contract::{orchestration::*, nars::InferenceType, plan::ThinkingContext, thinking::*}, PlannerAwa… | impl OrchestrationBridge for PlannerAwareness (route/resolve_thinking/domain_available) | none | Routes lg.* UnifiedSteps to PlannerAwareness::plan_auto/orchestrate/health; maps planner's 12/5-way enums to contract's 36-style ones | doc admits lossy enum mapping: Pearl rungs Intervention/Counterfactual both bridged to InferenceType::Abducti… | none | CORE (V3-neutral query engine) - OrchestrationBridge impl | +| `physical/accumulate.rs` | pub | super::{ColumnData, Morsel, PhysicalOperator}; crate::ir::logical_op::SemiringType | AccumulateOp, Semiring trait, SemiringValue enum, Boolean/Tropical/XorBundle/TruthPropagating/HammingMin impl… | none | ACCUMULATE physical operator: propagates truth/distance/fingerprint values along graph edges during traversal via pluggable semiring algebra | SemiringType::Palette and Custom fall back to BooleanSemiring — bgz17 palette semiring not wired (TODO in cre… | semiring inventory overlaps blasgraph's 7 HDR semirings + bgz17 PaletteCompose + contract SemiringChoice per … | CORE (V3-neutral query engine) | +| `physical/broadcast.rs` | pub | super::{Morsel, PhysicalOperator} | BroadcastOp, execute() -> Vec | none | BROADCAST physical operator: distributes a 256xu64 query fingerprint (Container) to all scan partitions for parallel Hamming distance | none | none | CORE (V3-neutral query engine) | +| `physical/cam_pq_scan.rs` | pub | super::PhysicalOperator | CamPqStrategy enum, CamPqScanOp, execute()/full_adc()/cascade()/select_strategy()/estimated_cost_us() | 6-byte packed CAM code per candidate ([u8;6]) against [[f32;256];6] distance tables — ADC wire layout, not an… | Cost-model-driven CAM-PQ scan operator: FullAdc/Cascade/IvfCascade strategies over 6-subspace ADC distance tables, chosen by candidate-coun… | none | CAM-PQ scan strategy overlaps ndarray's CAM-PQ codec, lance-graph/cam_pq crate, and bgz17 palette distance ta… | CORE (V3-neutral query engine) | +| `physical/collapse.rs` | pub | super::{Morsel, PhysicalOperator}; crate::ir::logical_op::CollapseGate | CollapseOp, GateState enum (Flow/Hold/Block), classify()/execute() -> CollapseResult | none | COLLAPSE physical operator: SD-based FLOW/HOLD/BLOCK gating of resonance-score result groups (agi-chat Two-Stroke pattern) | GateState FLOW(<0.15)/HOLD/BLOCK(>=0.35) thresholds mirror the pre-V3 singleton-CollapseGate wording flagged … | CollapseGate name reused across ir::logical_op::CollapseGate (this file), contract::collapse_gate, and strate… | CORE (V3-neutral query engine) | +| `physical/mod.rs` | pub | accumulate/broadcast/cam_pq_scan/collapse/scan submodules | PhysicalOperator trait, Morsel, ColumnData enum, PhysicalPlan, Pipeline | none | Physical operator tree root: BROADCAST->SCAN->ACCUMULATE->COLLAPSE fused resonance phases plus morsel/pipeline plumbing | ColumnData is a placeholder enum pending real Arrow RecordBatch integration | none | CORE (V3-neutral query engine) | +| `physical/scan.rs` | pub | super::{ColumnData, Morsel, PhysicalOperator}; crate::ir::logical_op::ScanStrategy | ScanOp, execute_partition()/cascade_scan()/full_scan()/index_scan() | none | SCAN physical operator: vectorized Hamming distance via Cascade (sigma-band pruning)/Full/Index strategies, orchestrating ndarray SIMD kern… | index_scan() falls back to full_scan() — proximity index lookup unimplemented; full_scan doc claims AVX-512 V… | none | CORE (V3-neutral query engine) | +| `pipeline.rs` | pub | lance_graph_contract::orchestration::{OrchestrationBridge,StepId,StepStatus,UnifiedStep} | PipelineDag (build/execute_with/execute_via_bridge), PipelineError, make_step helpers | none | Kahn's-algorithm DAG executor for UnifiedStep graphs: topo order, cycle/dup-id detection, execution via closure or OrchestrationBridge | synchronous only; doc notes async fan-out for independent steps deferred to a future PR-F4/PR-G2 concurrency … | none | CORE (V3-neutral query engine) - LF-12 pipeline DAG executor | +| `plan/cost.rs` | pub | ThinkingContext.modulation.exploration; QueryGraphNode (unused param in scan_cost) | CostModel: scan/hash_join/inl_join/wco_join/resonance_scan/accumulate cost fns | none | Heuristic cost model for DP join enumeration; scales scan/hash/INL/WCO/resonance/accumulate costs by thinking-context exploration discount | scan_cost comment: 'real implementation would use table statistics' — placeholder cardinality heuristic | none | CORE query-planner cost heuristics | +| `plan/dp_enumerator.rs` | mixed | ir::{Arena,LogicalOp,Node,SubPlansTable,SubqueryGraph}; plan::{CostModel,PlannerConfig,QueryGraph}; ThinkingC… | DpEnumerator::enumerate() -> DP join-order plan (INL/hash/WCO joins, greedy fallback) | none | Kuzudb-style DP join-order enumerator: level-by-level INL/hash/WCO join enumeration with greedy left-deep fallback for large queries | #[allow(dead_code)] unused `thinking` field + #[allow(unused_imports)] Direction/JoinType — half-wired thinki… | none | CORE DP join-order enumeration | +| `plan/mod.rs` | mixed | ir::{Arena,LogicalOp,LogicalPlan}; ThinkingContext; DpEnumerator; CostModel; PlanError | plan_query() entry point; PlannerConfig; QueryGraph/QueryGraphNode/QueryGraphEdge types | none | Planner inner-loop entry: builds QueryGraph, dispatches DP join enumeration or resonance BROADCAST->SCAN->ACCUMULATE->COLLAPSE plan | parse_to_query_graph is a stub ('simplified parser'); real 66KB nom parser lives in lance-graph core; placeho… | parse_to_query_graph duplicates lance-graph core's real nom-based Cypher parser (stub) | CORE planner entry point stub | +| `prediction/ingestion.rs` | pub | super::{Derivation,IngestEdge,IngestNode}; serde_json for LLM JSON response parsing | extract_entities(), extraction_prompt(), parse_llm_response() -> ExtractionResult | none | Extracts aiwar entities/relationships from raw intel text via regex patterns or LLM JSON, producing typed IngestNode/IngestEdge for graph m… | none | none | CORE aiwar entity ingestion | +| `prediction/mod.rs` | pub | elevation::budget::{budget_for_cluster,PatienceBudget}; thinking::style::{ThinkingCluster,ThinkingStyle} | Scenario, CausalStep, Derivation, IngestNode/IngestEdge, predict_multi_style() -> PredictionResult | none | Prediction engine: runs a question through multiple thinking styles to generate ranked causal scenarios (aiwar what-if forecasting) | #[allow(unused_imports)] on PatienceBudget/ThinkingCluster at module scope — partial wiring | none | CORE legacy ThinkingStyle scenario dispatch | +| `prediction/scenario.rs` | mixed | super::{CausalStep,Derivation,Scenario}; elevation::budget::PatienceBudget; thinking::style::{ThinkingCluster… | generate_scenarios() dispatch: deep-chain/lateral/focused/heuristic scenario generators | none | Per-cluster scenario generation: deep NARS chains (Convergent), lateral abduction/induction (Divergent), single chain (Attention), heuristi… | generate_deep_chains comment 'Can't follow further without owned string' — chain-following limited to 1 infer… | NARS deduction/abduction/induction logic overlaps lance-graph-planner/src/nars/inference.rs | CORE legacy ThinkingStyle scenario generation | +| `prediction/temporal.rs` | pub | super::{CausalStep,Derivation} | simulate() -> Vec; cascade_depth(); summarize() -> SimulationSummary | none | Temporal NARS simulation: propagates causal truth values through simulated rounds with confidence decay + deduction-based edge inference | none | NARS deduction step overlaps lance-graph-planner/src/nars/inference.rs and prediction/scenario.rs infer_next_… | CORE temporal NARS simulation | +| `selector.rs` | pub | traits::{PipelinePhase,PlanContext,PlanStrategy} | StrategySelector enum (Explicit/Resonance/Auto), select_strategies() | none | Chooses which of the 16 strategies compose a plan: explicit names, resonance-scored by thinking style, or auto top-N-per-phase | two sort_by(...).partial_cmp(...).unwrap() calls on f32 scores (Resonance + Auto branches) — panics on NaN sc… | none | CORE (V3-neutral query engine) - strategy selection | +| `serve.rs` | internal | cache::{candidate_pool::Phase,convergence::*}, strategy::chat_bundle::AutocompleteCache, axum, serde_json | OpenAI-compatible axum routes: /v1/chat/completions, /v1/embeddings, /v1/models, /health (bin target, feature… | none | Feature-gated standalone binary exposing SPO-triplet extraction + NARS scoring over chat messages as an OpenAI-compatible REST API | hardcoded /tmp bgz7 shard paths for knowledge ingestion; several .unwrap() on Mutex::lock()/bind()/serve(); n… | none | CORE (V3-neutral query engine) - lab REST server binary | +| `strategy/arena_ir.rs` | mixed | ir::{logical_op,Arena,LogicalOp,LogicalPlan,Node}, traits::*, PlanContext.features | ArenaIR: PlanStrategy building resonance/graph LogicalPlan from detected features | none | Builds arena logical plan (Polars pattern): resonance BROADCAST/SCAN/ACCUMULATE/COLLAPSE vs simple graph ScanNode | Stub: graph_plan only emits single ScanNode; real AST from CypherParse not yet wired | none | CORE parser/plan-builder strategy | +| `strategy/chat_bundle.rs` | pub | cache::{candidate_pool,kv_bundle,lane_eval,nars_engine,triple_model}, ir, traits | AutocompleteCache engine, CacheRoute enum, AutocompleteCacheStrategy (#17 chat hot path) | none | 4096-head causal cognition cache (TripleModel+NarsEngine+LaneEvaluator+CandidatePool) driving chat autocomplete/route decisions | TODO: wire nars.detect_contradiction — has_contradiction hardcoded to false | none | CORE chat hot-path query strategy | +| `strategy/collapse_gate.rs` | pub | ir, traits, PlanContext.features.has_resonance/has_truth_values | CollapseGateStrategy (#10): plan() no-op stub, doc'd FLOW/HOLD/BLOCK thresholds | none | Documents resonance gating FLOW(<0.15)/HOLD(<0.35)/BLOCK thresholds from agi-chat; inserts COLLAPSE after ACCUMULATE (unimplemented) | plan() is a no-op; implements the singleton CollapseGate sink-in pattern the V3 primer marks superseded | Distinct from contract::collapse_gate and the per-mailbox Kanban CollapseGate successor | LEGACY superseded FLOW/HOLD/BLOCK singleton design | +| `strategy/cypher_parse.rs` | pub | ir, traits, PlanContext.query string | CypherParse (#1): sets QueryFeatures (graph_pattern/mutation/resonance/etc.) via substring detection | none | Detects Cypher query features by uppercase substring match (MATCH/CREATE/HAMMING/etc.) and estimates complexity | Heuristic substring detection, not real nom parser; defers to lance-graph::parser::parse_cypher_query() | none | CORE V3-neutral query parser | +| `strategy/dp_join.rs` | pub | ir, traits, PlanContext.features.num_match_clauses | DPJoinEnum (#3): affinity scoring only, no plan mutation | none | Scores join-order-enumeration affinity by match-clause count; documents delegation to crate::plan::DpEnumerator | plan() is a total pass-through; DpEnumerator DP logic not invoked from this strategy | none | CORE V3-neutral query engine | +| `strategy/extension.rs` | pub | ir, traits | ExtensionPlanner (#13): low (0.1) default affinity extension point | none | DataFusion-style ExtensionPlanner escape hatch for user-defined custom planning logic/operators | No strategy registry for custom extensions implemented; intentional no-op pass-through by design | none | CORE V3-neutral query engine | +| `strategy/gql_parse.rs` | pub | ir, traits, PlanContext.query string | GqlParse (#16): ISO/IEC 39075 GQL feature detection + affinity scoring, 6 unit tests | none | Detects GQL-specific syntax (LEFT MATCH/path modes/LET/USE GRAPH) reusing Cypher detection, sets QueryFeatures | none | Feature-detection substring heuristics largely duplicate cypher_parse.rs's logic | CORE V3-neutral query parser | +| `strategy/gremlin_parse.rs` | mixed | ir::{expr,logical_op::Direction,AExpr,Arena,ExprNode,LogicalOp,LogicalPlan,Node}, traits | GremlinParse (#14): full tokenizer + GremlinStep enum + IR builder for TinkerPop method chains | none | Parses g.V()... Gremlin traversal chains into a full LogicalOp/AExpr IR tree (ScanNode/Filter/Join/Aggregate/etc.) | plan() re-swaps arenas via placeholder LogicalPlan ('compose will merge' comment) — fragile hack | none | CORE V3-neutral query parser | +| `strategy/histogram_cost.rs` | pub | ir, traits, PlanContext.features.estimated_complexity | HistogramCost (#5): affinity scoring for cardinality-sensitive queries | none | Hyrise-style histogram-based cardinality estimation scorer; documents per-column histogram walk (unimplemented) | plan() is a no-op; histogram/catalog statistics walk not implemented | none | CORE V3-neutral query engine | +| `strategy/jit_compile.rs` | pub | ir, traits, PlanContext.features.has_fingerprint_scan/estimated_complexity | JitCompile (#11): affinity scoring for JIT-worthy scan operations | none | Scores JIT-compilation worthiness for fingerprint scan kernels; documents Cranelift compile via ndarray JitEngine | plan() is a no-op; PrecompileQueue lookup, τ-address dispatch, and JitScanOp swap not implemented | τ-address JIT dispatch concept duplicated with style_strategy.rs and lance-graph-contract::jit.rs | W3 templates JIT/thinking-style compiled path | +| `strategy/mod.rs` | pub | crate::traits::PlanStrategy, all 17 sibling strategy modules in this dir | default_strategies() -> Vec>: 17-strategy registry, parse/plan/optimize/exec | none | Central registry wiring all composable planning strategies; affinity system lets the right polyglot parser win | Doc comment says 'all 16 strategies' but vec registers 17 (incl. chat_bundle + style_strategy) — stale count | none | CORE registry (wires CORE parsers + W2 style_strategy) | +| `strategy/morsel_exec.rs` | pub | ir, traits, PlanContext.features | MorselExec (#7): affinity scoring for physical execution planning | none | Kuzudb/Polars morsel-driven physical execution planner; documents LogicalOp→PhysicalOp pipeline decomposition | plan() is a no-op; delegation to crate::execute::PipelineExecutor not implemented | none | CORE V3-neutral query engine | +| `strategy/rule_optimizer.rs` | pub | ir, traits, PlanContext.features.has_graph_pattern | RuleOptimizer (#4): affinity scoring for rule-based optimization | none | Documents 10-pass DataFusion-style rule optimizer (predicate/projection/limit pushdown, semiring, topK, etc.) | plan() is a no-op; none of the 10 listed optimization passes are invoked from this strategy | none | CORE V3-neutral query engine | +| `strategy/sigma_scan.rs` | pub | ir::logical_op::ScanStrategy, ir, traits, PlanContext.features | SigmaBandScan (#6): affinity scoring for fingerprint/resonance vector queries | none | Chooses Cascade/Full/Index scan strategy for Hamming/vector fingerprint queries; SIMD kernels live in ndarray | plan() is a no-op; the Cascade/Full/Index decision logic is not implemented | none | CORE V3-neutral query engine | +| `strategy/sparql_parse.rs` | mixed | ir::{expr,logical_op,AExpr,Arena,ExprNode,LogicalOp,LogicalPlan,Node}, traits, std::collections::HashMap | SparqlParse (#15): full SPARQL SELECT/ASK/CONSTRUCT parser -> ScanNode/Filter/Join/RecursiveExtend IR | none | Parses W3C SPARQL triple patterns/OPTIONAL/FILTER/property-paths/aggregates into the shared logical IR | Same arena-placeholder pattern as gremlin_parse.rs (ops: Arena::new() 'compose will merge' comment) | none | CORE V3-neutral query parser | +| `strategy/stream_pipeline.rs` | pub | ir, traits, PlanContext.features.estimated_complexity | StreamPipeline (#8): affinity scoring for streaming execution | none | Documents Polars-style streaming execution with backpressure tokens and subgraph-at-a-time scheduling | plan() is a no-op; backpressure token insertion and multiplexer auto-insertion not implemented | none | CORE V3-neutral query engine | +| `strategy/style_strategy.rs` | mixed | lance_graph_contract::{recipe_kernels,recipes,thinking::{StyleCluster,ThinkingStyle}}, ir, traits | StyleStrategy (#18), DEFAULT_STYLE const, reliability_of() R-GATE measurable | none | Wires thinking-style->cluster->recipe(Tactic kernel) substrate into planner; computes style-conditioned reliability coefficient | plan() is pure pass-through — reliability computed but not emitted as KanbanMove; D-MBX-A6 output overhaul de… | none | W2 kanban executors (D-MBX-A6 Outcome->KanbanMove seam) | +| `strategy/truth_propagation.rs` | pub | ir::logical_op::SemiringType, ir, traits, PlanContext.features/nars_hint | TruthPropagation (#9): affinity scoring for NARS deduction/revision accumulation | none | Documents NARS truth propagation during traversal: multiply=deduction, add=revision formulas for ACCUMULATE ops | plan() is a no-op; TruthPropagatingSemiring injection lives in (unwired) physical::accumulate module | NARS InferenceType/truth echoes contract::nars.rs and lance-graph/graph/spo/truth.rs (3-copy dup) | CORE V3-neutral query engine | +| `strategy/workflow_dag.rs` | pub | ir, traits, PlanContext.features.has_workflow | WorkflowDAG (#12): affinity scoring for workflow-orchestration queries | none | LangGraph-style workflow-as-graph-traversal planner (Task DEPENDS_ON Task pattern); documents channel+reducer semantics | plan() is a no-op; channel+reducer semantics and checkpoint replay not implemented | none | CORE V3-neutral query engine | +| `temporal.rs` | pub | std only (self-contained); doc references lance/surrealql/ractor/thinking clocks conceptually | EpistemicMode, TemporalStatus, QueryReference, DependsClosure trait, deinterlace()/classify_ready() | none | Merges lance/surrealql/ractor/thinking clocks via HLC tick into one causally-coherent per-row TIME+DATA dispatchability view | DATA-causal axis (SPO depends_on) has only a trivial NoDeps impl; cross-server HLC bus explicitly documented … | none | W1 envelope/ownership - kanban SoA consistency reads | +| `thinking/mod.rs` | pub | crate::mul::MulAssessment, crate::plan::PlannerConfig, contract::cognitive_shader::RungLevel | ThinkingContext struct, orchestrate() fn, re-exports of submodule types | none | Top-level thinking orchestration: picks style/NARS type/semiring/sigma stage, builds ThinkingContext for the query planner | none | none | W3 thinking orchestration entry point | +| `thinking/nars_dispatch.rs` | pub | raw Cypher query string (no external types) | NarsInferenceType (7 variants incl. Pearl rungs), QueryStrategy, route(), detect_from_query() | none | Ports n8n-rs thinking_mode.rs: routes NARS inference type (dedu/induc/abduc/rev/synth/interv/counterf) to query execution strategy | Intervention(0.85)/Counterfactual(0.7) confidence modifiers explicitly marked TUNED-LATER placeholder calibra… | NARS InferenceType is one of 3 known copies (lance-graph-contract::nars is canonical) | W3 thinking styles/NARS dispatch | +| `thinking/semiring_selection.rs` | pub | super::nars_dispatch::NarsInferenceType, super::style::ThinkingStyle, crate::ir::logical_op::SemiringType | SemiringChoice struct (semiring + rationale), select() fn | none | Auto-selects graph traversal semiring (XorBundle/TruthPropagating/Tropical/Boolean/HammingMin) from query shape + style + NARS type | none | none | W3 thinking-driven semiring selection | +| `thinking/sigma_chain.rs` | pub | none external (self-contained; ported from bighorn/extensions/agi_stack thinking_atom.py) | SigmaStage enum (Ω/Δ/Φ/Θ/Λ), ThinkingAtom struct, Proposition struct, escalate()/revise() | none | Tracks epistemic lifecycle of a thinking atom through 5 sigma stages with NARS-style confidence revision merge | none | NARS revision formula (f_revised/c_revised) mirrors truth revision logic likely also in crate::nars::truth | W3 sigma-chain epistemic lifecycle | +| `thinking/style.rs` | pub | crate::mul::dk::DkPosition, crate::mul::homeostasis::FlowState, crate::mul::trust::TrustTexture, crate::mul::… | ThinkingStyle (12 variants/4 clusters), ThinkingCluster, FieldModulation, ScanParams, select_from_mul() | none | Defines 12 base thinking styles w/ tau JIT addresses, default field modulation, converts to ScanParams for ndarray SIMD kernels | doc comment admits only 12 base styles here vs 36 canonical (runtime YAML StyleOverride extends it) | ThinkingStyle is one of 4 known copies; this 12-style/4-cluster set is a subset of contract's 36-style/6-clus… | W3 thinking styles + JIT tau addresses | +| `traits.rs` | pub | ir::{Arena,LogicalOp,LogicalPlan,Node}, PlanError | PlanCapability, PipelinePhase, PlanContext, QueryFeatures, PlanInput, PlanStrategy trait | none | Defines the core composable-strategy trait (name/capability/affinity/plan) and the phase-ordering enum all 16 strategies implement | none | none | CORE (V3-neutral query engine) - strategy trait contract | diff --git a/.claude/v3/README.md b/.claude/v3/README.md new file mode 100644 index 000000000..c1bb64220 --- /dev/null +++ b/.claude/v3/README.md @@ -0,0 +1,71 @@ +# .claude/v3/ — the V3 Substrate entry point + +> **Start here** (or invoke the `/v3` skill — same bootload) for any work +> touching SoA rows, tenants, mailbox ownership, kanban, thinking +> templates, classids, or the DTO ladder. This folder consolidates what is +> NEW since the 2026-07-02 operator rulings (mailbox-kanban model, classid +> canon-high flip, the 4+12 facet, compiled templates, the DTO ladder +> splits) so sessions converge instead of re-deriving. + +## What V3 is, in five sentences + +One **Mailbox** owns one SoA and one Kanban board (a tenant, never a +singleton); ractor proves ownership at compile time and the batch writer +fires **ahead** kanban updates at write cast, on behalf of +`envelope.mailbox_owner()`. Every V3 unit is a **16-byte facet**: +`[1B domain | 1B appid | 2B classview] + 96-bit payload`, the payload +reading selected by the **ClassView as the focus lens the data shape +wants** — labels and positions come from the ClassView, never a slot. +Thinking is **compiled**: the elixir-like DSL × StepMask is to +orchestration what askama × FieldMask is to rendering; a successful LLM +(Rig oracle) run compiles DOWN to a deterministic replayable template +executed by graph-flow under inherited ownership. Thinking cycles follow +**standing async plans** within a 550 ms net budget; updates reprioritize, +never gate. The `0x1000` custom half is a temporary **adoption monitor**; +at 100% adoption (P4) it retires and the classview half opens for the 64k +render/template catalogue. + +## Doc map (read order per task) + +| You are… | Read | +|---|---| +| new to V3 | `knowledge/v3-substrate-primer.md` (one page) → this README's plan/waves row | +| planning / sequencing | `INTEGRATION-PLAN.md` (waves W0–W6, gates, adopted D-ids) | +| deciding reuse vs build | `COMPONENT-MAP.md` (every subsystem's verdict, file:line) | +| hunting collapse work | `ENTROPY-MILESTONES.md` (M1–M23; each row has a mechanical gate) | +| touching bytes / tenants / addresses | `soa_layout/README.md` → le-contract / tenants / consumer-map / routing | +| per-file lookup (3 core crates) | `MODULE-TABLE.md` (consumes / emits / LE / debt / duplication / wave) | +| about to spawn Sonnet workers | `knowledge/sonnet-worker-guardrails.md` — **§1 preamble pasted verbatim, non-negotiable** | +| kanban / batch writer / executors | `knowledge/mailbox-kanban-model.md` | +| templates / oracle / graph-flow | `knowledge/compiled-templates.md` (incl. the corrected NextAction mapping) | +| consumer write paths | `knowledge/write-on-behalf.md` + `soa_layout/consumer-map.md` | +| ruff/odoo transcode landings | `knowledge/multi-anchor-ast-resolution.md` | +| waking an agent | `agents/BOOT.md` (the four `v3-*` cards + trigger routing) | + +Shortcuts: `/v3` (bootload), `/v3-audit` (pre-commit conformance greps). +Canonical ruling texts live on the board (`.claude/board/EPIPHANIES.md`, +entries `E-V3-*`, `E-MAILBOX-KANBAN-NO-COLLAPSEGATE`, +`E-COMPILED-THINKING-TEMPLATES`, `E-DTO-LADDER-OWNERSHIP-SPLIT`, +`E-TWO-RESONANCES-SPLIT`, `E-RUFF-ODOO-MULTI-ANCHOR-AST`, +`E-V3-PLANNER-TWO-NATURES-AND-SPEED-PROBE`) — cite those in PRs, not +these mirrors. + +## The three load-bearing NEW pieces (everything else is wiring) + +1. **W1** — ahead-firing batch writer + delegation cache + (`cast(on_behalf = envelope.mailbox_owner(), payload = BusDto)`). +2. **W2a** — the per-mailbox kanban board as a TENANT (type + lane). +3. **W3a/b** — StepMask + the ElixirTemplate→graph-flow adapter that + closes the (falsified) control-flow gap. + +## Standing gates + +Probe-first; `v3-mailbox-warden` + `v3-envelope-auditor` on every +write-path/layout diff; jc pillars (ICC/Spearman/Cronbach) before a new +lane reading backs any claim; board hygiene same-commit; Sonnet grindwork +/ Fable decisions with the guardrails preamble in every brief; wire, +don't invent — COMPONENT-MAP is the precomputed "does it exist" search. + +Tier-0 workspace reads (`.claude/board/LATEST_STATE.md`, +`PR_ARC_INVENTORY.md`) remain mandatory per `.claude/BOOT.md`; this folder +adds to them, never replaces them. diff --git a/.claude/v3/agents/BOOT.md b/.claude/v3/agents/BOOT.md new file mode 100644 index 000000000..624b7ede3 --- /dev/null +++ b/.claude/v3/agents/BOOT.md @@ -0,0 +1,67 @@ +# V3 Agent Ensemble — activation table + +> The V3 EXTENSION of `.claude/agents/BOOT.md`, not a replacement. The main +> ensemble (19 specialists + 5 meta-agents + PP-13/14/15/16 savants) stays +> authoritative for everything it already covers. This table adds the four +> V3-aware cards and routes V3 triggers to them. +> +> **Card files live in `.claude/agents/v3-*.md`** (the harness discovers +> agents there); this folder holds the activation table + the V3 knowledge +> the cards bootload. + +## The four V3 cards + +| Card | Kind | Fires on | Verdicts / Output | +|---|---|---|---| +| `v3-mailbox-warden` | reviewer | any SoA/Lance write path; ownership-ish fields on DTOs; CollapseGate/baton/emission resurrection; consumers writing as themselves | OWNED / BOOTSTRAP-OK / ORPHAN-WRITE / RESURRECTION | +| `v3-envelope-auditor` | reviewer | soa_envelope.rs / canonical_node.rs / collapse_gate.rs diffs; new tenant lanes; byte-offset changes; ENVELOPE_LAYOUT_VERSION | LAYOUT-CLEAN / LAYOUT-GATED / LAYOUT-BREAK (+ layout-diff table) | +| `v3-kanban-executor-engineer` | builder | style_strategy.rs / kanban_actor.rs / kanban_loop.rs; batch-writer, ahead-update, delegation-cache designs; 550 ms scheduling | probe-first implementation, gated by the two reviewers | +| `v3-template-smith` | builder | elixir-template / template-runtime / template-equivalence / cognitive-compiler; StepMask; graph-flow adapter; Rig oracle loop | probe-first implementation; replay-equivalence gate | + +## Knowledge bootload (Tier-1 for V3 work) + +Every V3 card reads, in order: + +1. `.claude/v3/knowledge/v3-substrate-primer.md` — always. +2. Its own domain doc: `mailbox-kanban-model.md` (warden, engineer) / + `write-on-behalf.md` (warden + every consumer session) / + `compiled-templates.md` (smith). +3. `.claude/v3/soa_layout/le-contract.md` + `tenants.md` (auditor; anyone + touching layout). +4. Tier-0 stays mandatory: `.claude/board/LATEST_STATE.md` + + `PR_ARC_INVENTORY.md` (main BOOT.md rule). + +## Trigger routing (V3 additions to the main Knowledge Activation table) + +| Trigger phrase / diff surface | Wake | With knowledge | +|---|---|---| +| "write on behalf", "mailbox owner", "delegation", new write path | v3-mailbox-warden | write-on-behalf.md | +| "SoaEnvelope", "ColumnDescriptor", "tenant lane", "layout version", byte offsets | v3-envelope-auditor | soa_layout/le-contract.md + tenants.md | +| "kanban", "ahead update", "batch writer", "550ms", "KanbanMove", D-MBX-A6 | v3-kanban-executor-engineer | mailbox-kanban-model.md | +| "template", "StepMask", "replay", "oracle", "graph-flow", "compile down" | v3-template-smith | compiled-templates.md | +| "CollapseGate", "baton", "emission", "BindSpace sink" (non-legacy context) | v3-mailbox-warden (RESURRECTION scan) | v3-substrate-primer.md §6 | + +## Relationship to existing cards + +- `dto-soa-savant` keeps the four-column AGI-as-SoA lens; the warden adds + the OWNERSHIP lens — they compose, not compete. +- `baton-handoff-auditor` keeps cross-crate boundary review; on V3 + surfaces it defers resurrection-scan findings to the warden's verdict + vocabulary. +- `soa-review` (smb-office flavored) and `v3-envelope-auditor` split by + repo: Arrow-schema consumer reviews there, LE register-file audits here. +- The PP-13/14/15/16 lifecycle savants apply unchanged to V3 waves. + +## Model policy (per operator, 2026-07-02) + +Sonnet 5 for grindwork (mechanical wiring, greps, censuses, doc stubs from +spec); Fable/Opus tier for decisions, plans needing nuance, reviews, and +anything accumulating multiple sources. Never Haiku. + +**Sonnet footgun-proofing (operator, 2026-07-02):** every Sonnet worker +brief MUST paste the §1 preamble of +`.claude/v3/knowledge/sonnet-worker-guardrails.md` verbatim, and every +Sonnet worker reads that doc before its first tool call. The doc turns +every V3 rule into a mechanical check (no judgment calls) and defines the +STOP+report escalation triggers. Orchestrators: a worker that improvised +past a §5 trigger produced an invalid result — re-dispatch. diff --git a/.claude/v3/knowledge/compiled-templates.md b/.claude/v3/knowledge/compiled-templates.md new file mode 100644 index 000000000..e4cc0e3c4 --- /dev/null +++ b/.claude/v3/knowledge/compiled-templates.md @@ -0,0 +1,89 @@ +# Compiled Thinking Templates — the DSL triple, StepMask, oracle compile-down + +> READ BY: template-smith, kanban-executor-engineer, any session touching +> elixir-template / template-runtime / template-equivalence / +> cognitive-compiler, rs-graph-llm (graph-flow), or rig. + +## Status: FINDING (operator-ruled 2026-07-02 — E-COMPILED-THINKING-TEMPLATES) + +--- + +## The analogy that IS the design + +``` +askama template ↔ ClassView × FieldMask (rendering: masked selection over a class) +elixir DSL ↔ Template × StepMask (thinking: masked selection over a plan) +``` + +Orchestration **compiles**. The elixir-like low-code syntax (NOT Elixir) is +the source; the compiled orchestration graph is a **deterministic replayable +template**; a **StepMask** bitmask (sibling of `FieldMask`) selects which +steps are live for a given style/dispatch. Knowledge transfers as compiled +templates, not as prompts. + +## The in-tree DSL triple (already shipped, scaffolded) + +| Crate | Role | State | +|---|---|---| +| `crates/elixir-template` | representation + parser (`pipeline do step :x end`, `OgarAction` enum) | scaffolded, tests green | +| `crates/template-runtime` | deterministic OGAR-action dispatch (reflex executor) | scaffolded | +| `crates/template-equivalence` | replay grading (Exact / RankOrder / confidence-drift) | scaffolded | +| `crates/cognitive-compiler` | trace → template synthesis surface | scaffolded (synthesis = first probe) | + +`ogar-from-elixir` (OGAR side) is the future richer frontend; the triple +above is canonical today. The crate doc of `elixir-template` names the +compile-down direction: *a successful LLM run compiles down to the +deterministic template.* + +## The execution + oracle split + +- **rs-graph-llm (graph-flow)** executes template INSTANCES as replayable + sessions. + + > **CORRECTED 2026-07-02 (ground-truthed by the mapping fleet):** the + > original "NextAction maps 1:1 onto OgarAction transitions" claim does + > NOT hold in code. `NextAction` has **6 variants** (Continue, + > ContinueAndExecute, GoTo, **GoBack** [documented no-op], End, + > WaitForInput — task.rs:243-303) while `template-runtime` executes an + > unconditional linear `Vec` with NO control-flow type at + > all. The HONEST 1:1 pairings are: `elixir_template::Step ↔ + > graph_flow::Task` (unit of work) and `OgarAction::ogar_name() ↔ + > Task::id()` (dispatch key). Closing the control-flow gap IS the W3 + > work: either template-runtime grows a NextAction-shaped ControlSignal + > judged by StepMask, or the DSL grows branch/wait grammar the adapter + > translates into graph-flow conditional edges. Building the D-V3-W3b + > adapter while assuming the old 1:1 claim would silently drop + > End/WaitForInput/GoTo semantics — do not. +- **Rig** is the optional **LLM API template oracle**: consulted when the + deterministic template hits a FailureTicket (the <25% tail); a successful + oracle run is graded by `template-equivalence` and, when it passes, + **compiled down** into the template catalogue by `cognitive-compiler`. +- **Ownership inheritance is mandatory:** a graph-flow session executing a + template inherits the SoA ownership of the mailbox it serves — it writes + on behalf of `envelope.mailbox_owner()`, never as itself + (see `write-on-behalf.md`). + +## The standing async plan connection + +The template IS the standing async plan from the mailbox-kanban ruling: +thinking cycles follow their compiled template without waiting to be called +(the `StreamDto` can't-stop-thinking lineage). A kanban update reprioritizes +which template steps are live (StepMask), it does not wake the thinking. + +## Post-P4: the catalogue in the classid + +Once the `0x1000` V3 monitor retires (P4), the classid **custom half** +indexes the template catalogue — 36 thinking styles dispatch as 36 lenses +over the same canon concept, exactly like app render skins +(handover finding F2). Style dispatch becomes catalogue addressing: +`(canon concept, custom template-id) → compiled template`. + +## Gap list (see INTEGRATION-PLAN W3) + +- `StepMask` type does not exist yet (mint in contract, sibling of FieldMask). +- ElixirTemplate → graph-flow `GraphBuilder` adapter (rs-graph-llm side). +- Rig oracle node + equivalence-gated compile-down loop (D-VCW-7 lineage). +- Catalogue dispatch keyed by classid custom half (P4-gated). + +Cross-ref: `v3-substrate-primer.md` §4, board `E-COMPILED-THINKING-TEMPLATES`, +STATUS_BOARD `cognitive-compilation-v1` rows (D-CC-*). diff --git a/.claude/v3/knowledge/mailbox-kanban-model.md b/.claude/v3/knowledge/mailbox-kanban-model.md new file mode 100644 index 000000000..bb16f93d8 --- /dev/null +++ b/.claude/v3/knowledge/mailbox-kanban-model.md @@ -0,0 +1,88 @@ +# Mailbox-Kanban Model — executors, ahead updates, delegation cache + +> READ BY: kanban-executor-engineer, mailbox-warden, integration-lead, and +> any session touching lance-graph-planner strategies, lance-graph-supervisor, +> symbiont, or a batch-writer path. + +## Status: FINDING (operator-ruled 2026-07-02 — E-MAILBOX-KANBAN-NO-COLLAPSEGATE) + +--- + +## The unit: one Mailbox = one Kanban board (as a TENANT) + +Every mailbox carries its own Kanban board. The board is a **tenant** — +per-mailbox state, a sibling of the per-row `KanbanTenant` — never a global +singleton. Phases (Tier 2 of `docs/architecture/soa-three-tier-model.md`): + +``` +Planning → CognitiveWork → Evaluation → Commit → Plan → Prune +``` + +`MailboxSoaOwner::advance_phase(to)` is the SOLE mutator. Everything else +proposes; the owner disposes. + +## The two executor arms + the structural owner + +| Arm | Where | Role | +|---|---|---| +| **Arm #1 — planner** | `lance-graph-planner/src/strategy/style_strategy.rs` | The D-MBX-A6 seam: the deferred `Outcome → Candidate/KanbanMove` adapter. Strategy outcomes (converged, cycle_count, gate verdicts) become kanban moves. | +| **Arm #2 — symbiont** | `crates/symbiont` (`kanban_loop.rs` = POC) | SurrealDB-on-kv-lance executor: kanban updates as KV transactions on the same Lance substrate. Gated on the AdaWorldAPI surrealdb fork `kv-lance` feature. | +| **Structural owner** | `lance-graph-supervisor/kanban_actor.rs` | ractor actor per mailbox. **ractor is a compile-time ownership dummy** — it spawns and proves single-ownership via move semantics (`KanbanActor` with `type State = O`; the owner MOVES in at `pre_start`); it is NOT a data-plane bus and **not for messaging — it is slow** (operator, 2026-07-02). **It MAY serve as a HELPER where it makes sense** — spawn, supervision, occasional control RPC like the serialized Advance/MulAdvance (the codex #578 atomicity mechanism) — always keeping the speed difference in mind: nothing on the hot path may wait on ractor latency; hot-path dispatch belongs to the D-V3-W2e-probed ExecTarget. | + +## The ahead-firing batch writer + +The batch writer is where thinking is masked behind persistence: + +1. Consumer/engine produces a commit (`BusDto`) + the envelope names its + owner (`SoaEnvelope::mailbox_owner()`). +2. Batch writer **casts** the write: + `cast(on_behalf = envelope.mailbox_owner(), payload = BusDto)`. +3. **At cast time** (not at write-landed time) it checks the **delegation + cache**: does the caster hold ownership, need delegation, or already have + it? Mismatch (cast id ≠ envelope stamp) is the cache-logic case. +4. It fires the **AHEAD kanban update immediately on cast** — the kanban + board reflects intent before the write lands. No waiting. +5. Lance's columnar I/O writes the LE bytes from the in-place backing store + (zero-copy; the store never serializes). + +## Execution speed tiers + the planner's two natures (operator, 2026-07-02) + +**The planner is expected too slow for sub-microsecond handling.** The +hot dispatch path is probed, not assumed: **D-V3-W2e benchmarks +rs-graph-llm (graph-flow) execution vs SurrealQL-on-kv-lance** on the +same kanban/thinking workload; the winner owns the sub-µs `ExecTarget` +(the enum already encodes the split: Native / Jit / SurrealQl / Elixir — +kanban.rs). The planner arm remains the SLOW/plan path (strategy +selection, elevation, MUL) either way. + +**Not all planner methods route through DataFusion.** The strategy +surface has two natures: + +1. **Query strategies** — DataFusion-routed (parse → plan → execute). +2. **Resonance-based thinking** — the thinking style (the elixir + low-code compiled template) MATCHING against the **Gestalt resonance + of the object** (the perspectival `awareness_dto::ResonanceDto` — + "what does the object say about itself", classid → ClassView), to + reason at **rung level X** (`RungLevel`/`RungElevator`). No SQL, no + DataFusion — a resonance match dispatches a compiled template at a + rung. This is the V3-native dispatch and must never be forced through + the DataFusion mold. + +## Standing async plans + the 550 ms budget + +Thinking cycles follow a **standing async plan** (the compiled template — +see `compiled-templates.md`) whether or not an update arrived. They never +block on being called. The 64k–256k SoA prioritizes / load-balances the +cycle work within a **550 ms net budget** (minus load delays). Elevation +(planner `elevation/`, L0→L5) is the cost model that smells resistance and +is the natural budget allocator. + +## What the arms still need (gap list — see INTEGRATION-PLAN W2) + +- D-MBX-A6 adapter emit (Outcome→KanbanMove) implemented, not deferred. +- Per-mailbox kanban board carried as a TENANT (type + lane). +- The ahead-firing batch writer itself (cast pairing + delegation cache). +- symbiont arm unblocked by surrealdb `kv-lance` fork coordinates. + +Cross-ref: `v3-substrate-primer.md` §1–2, `write-on-behalf.md`, +`.claude/v3/soa_layout/tenants.md`, board `E-MAILBOX-KANBAN-NO-COLLAPSEGATE`. diff --git a/.claude/v3/knowledge/multi-anchor-ast-resolution.md b/.claude/v3/knowledge/multi-anchor-ast-resolution.md new file mode 100644 index 000000000..b743e949f --- /dev/null +++ b/.claude/v3/knowledge/multi-anchor-ast-resolution.md @@ -0,0 +1,67 @@ +# Multi-Anchor AST Resolution — ruff + odoo landing on OGIT/OGAR/ClassViews + +> READ BY: any session doing ruff-harvest / odoo-rs transcode / OGAR +> adapter or codebook work / OGIT ontology landing / ClassView codegen. +> Sibling doctrine: OGAR `docs/OGAR-TRANSPILE-SUBSTRATE.md` (pull-in/ +> pull-back), `.claude/knowledge/core-first-transcode-doctrine.md`. + +## Status: OPERATOR-STATED 2026-07-02 ([G] for the method's existence per operator; [H] per-mechanism until the ruff/odoo code is ground-truthed — board E-RUFF-ODOO-MULTI-ANCHOR-AST) + +--- + +## The method + +ruff + odoo together carry a **new AST resolution method**: a source +construct is not resolved from syntax alone — it is **triangulated from +multiple anchors simultaneously**, any of which can bind the resolution: + +| Anchor | What it contributes | +|---|---| +| **Database layout** | the ORM/schema ground truth (Odoo models, e.g. `account.move`) — the state shape the construct actually touches | +| **Duplication** | duplicated routes/implementations cluster; N copies doing one thing VOTE for one canonical concept — duplication is a resolution SIGNAL, not noise | +| **Target adapters** | the OGAR classid-keyed adapter surface the construct should land on (identity = classid; state = SoA value tenants; invocation = UnifiedStep) | +| **Target ontology (OGIT)** | the ontology node to land on — label-inheritance chain, schema, assoc | +| **ClassView stacking** | constructors resolve through STACKED ClassViews (classid → ClassView chain), so codegen REUSES existing constructors instead of emitting new ones | +| **Fuzzy ontology match** | for the tail: semantic match against the target ontology when exact anchors are missing — e.g. *"something that constructs an invoice from account, in different duplicated routes"* resolves to the one canonical invoice-construction concept | + +## Why this matters for V3 + +- **Duplication → entropy milestone feedstock.** The duplication anchor + is a mechanical detector for N→1 collapses: N duplicated routes → 1 + canonical concept (classid) + N ClassView skins. This is the same shape + as the classid flip and the DTO dedups — the AST method finds these + collapses in CONSUMER code automatically. +- **Landing surfaces are V3-native.** What a resolution lands ON is + exactly the V3 address stack: OGIT node (ontology), OGAR classid + (identity), ClassView (render/constructor), SoA tenant lanes (state, + per `soa_layout/le-contract.md`), rails (part_of:is_a / memberof) for + the resolved relations. +- **Constructor reuse = slot purity's sibling.** Just as labels/positions + come from the ClassView (never a payload slot), constructors come from + the stacked ClassView chain (never re-emitted per duplicate). Codegen + that emits a fresh constructor for a duplicated route is the same + defect class as a label slot in a facet. +- **Fuzzy matches are the oracle tail.** Exact anchors are the + deterministic path; the fuzzy ontology match is the <25%-tail resolver + — same shape as the template/Rig-oracle split: deterministic first, + semantic match for the remainder, and a successful fuzzy resolution + should be MINTED (into the codebook/ontology) so the next encounter is + exact. + +## Guardrails + +1. A fuzzy match NEVER lands silently: it produces a mint/mapping entry + (reviewable) — the next resolution of the same construct must be exact. +2. Duplication votes pick ONE canonical target; the duplicates become + ClassView-differentiated skins or adapters, never N parallel concepts. +3. Landing must target the OGAR Core surfaces (classid / tenants / + EdgeBlock / ClassView / UnifiedStep) — never a parallel object model + (core-first doctrine). +4. Mirror-to-OGAR: this doc is the lance-graph-side record; the OGAR + DISCOVERY-MAP D-entry goes through OGAR's own 5+3 hardening gate + (queued — do not paste into OGAR canon without that pass). + +Cross-ref: board `E-RUFF-ODOO-MULTI-ANCHOR-AST`, `le-contract.md` §2–3, +`compiled-templates.md` (deterministic-first + oracle tail), +OGAR `docs/OGAR-AS-IR.md` (compiler phases; this method is the front-end ++ linker phases gaining multi-anchor symbol resolution). diff --git a/.claude/v3/knowledge/sonnet-worker-guardrails.md b/.claude/v3/knowledge/sonnet-worker-guardrails.md new file mode 100644 index 000000000..31ba1fc6a --- /dev/null +++ b/.claude/v3/knowledge/sonnet-worker-guardrails.md @@ -0,0 +1,131 @@ +# Sonnet Worker Guardrails — V3 footgun catalogue + the worker preamble + +> READ BY: **every Sonnet worker before its first tool call**, and by every +> orchestrator writing a worker brief. The orchestrator MUST paste §1 (the +> preamble) verbatim into every Sonnet worker prompt that touches this +> workspace. This doc exists because grindwork agents execute literally: +> every rule here is mechanical — no judgment calls required, ever. +> If a worker hits a situation not covered by a rule below, the rule is: +> **STOP and return the question; do not improvise.** + +## Status: FINDING (operator directive 2026-07-02: "no foot gun at any time") + +--- + +## §1 — The worker preamble (orchestrators: paste verbatim into every brief) + +```text +WORKER IRON RULES (V3 workspace — mechanical, no exceptions): +1. SCOPE: touch ONLY the files named in this brief. If a fix seems to + need another file, STOP and report; do not follow the thread. +2. READ FULLY: Read every file you will edit, entirely, before editing + (offset/limit chunks for >2000 lines — ALL chunks). Never paraphrase + from grep/snippet output. grep locates; Read comprehends. +3. NO INVENTION: never mint a new struct/trait/enum/module. If the brief + needs a type, it names the existing one. A "missing" type = STOP+report. +4. CLASSIDS: compose ONLY via contract::render_classid / compose_classid + (or ogar_vocab::app::* in OGAR). Discriminate ONLY via classid_canon / + classid_canon_compat. NEVER write `as u16`, `& 0xFFFF`, `>> 8`, `>> 16` + on a composed classid u32 — not even in tests. +5. BOARD FILES: .claude/board/*.md are append-only ledgers. Bash + `tee -a` ONLY. Never Edit/Write/`>` them. Never reorder or delete rows. +6. BRANCH: work on the branch this brief names. Never checkout/switch/ + create branches. Never push unless the brief says push. +7. NO CARGO BUILDS: do not run `cargo build`/`cargo check`. A targeted + `cargo test -p ` or `cargo clippy -p ` is + allowed ONLY if the brief explicitly grants it. Verification is + centralized in the orchestrator. +8. LEGACY IS LOAD-BEARING: never delete, rename, or "clean up" anything + marked deprecated/legacy/_LEGACY/superseded (aliases, read modes, + collapse_gate.rs contents, BindSpace). Retirement is proof-gated and + never a worker task. +9. DTO PURITY: never add owner/mailbox_id/tenant_id fields to any DTO + (StreamDto/ResonanceDto/PerturbationDto/BusDto/ThoughtStruct). + Ownership lives in SoaEnvelope::mailbox_owner(), nowhere else. +10. CLAIMS: any "there is no X" / "all sites routed" claim in your report + MUST name the exhaustive search that backs it (tool + pattern + scope), + or be phrased as "not found in ". +11. DONE = your diff + the named test/probe green + a report listing: + files touched, searches run, anything you did NOT do. Partial work is + reported as partial, never as done. +``` + +## §2 — Vocabulary disambiguation (the words that bite) + +Sonnet workers MUST use this table; a brief using one of these words means +exactly the row below, never a neighbor. + +| Word | In V3 it means | It does NOT mean | Never do | +|---|---|---|---| +| **tenant (value tenant)** | a lane in the 480-byte value slab, selected by `classid_read_mode(c).value_schema` | a customer/org (that's consumer-app tenancy) | invent a lane; new lanes are envelope-auditor-gated | +| **KanbanTenant (per-row)** | the existing per-row kanban state type | the per-mailbox board | extend it to carry board state | +| **kanban board (per-mailbox)** | W2a deliverable: the mailbox's OWN board, a NEW tenant SIBLING of KanbanTenant | a global/singleton board | implement it without the W2a spec + field-isolation matrix | +| **cascade** | HEEL/HIP/TWIG key tiers (GUID canon; 256×256 centroid tiles) | the perturbation field | rename anything containing "cascade" | +| **PerturbationDto** (was dto.rs `ResonanceDto`) | the MECHANICAL Morton-tile inverse-pyramid field (Ψ) | awareness/perspective | touch awareness_dto.rs during D-PERT-1 | +| **ResonanceDto (awareness_dto.rs)** | the PERSPECTIVAL (Piaget Three-Mountains) resonance — KEEPS its name | a duplicate to dedup | rename/merge it with the Ψ DTO | +| **CollapseGate** | a legacy MODULE NAME (`collapse_gate.rs` still hosts live types: MailboxId, KanbanPhase, MergeMode) | a live singleton gate semantic | re-implement gate semantics OR delete the module | +| **BindSpace** | the legacy global store, MIGRATION IN PROGRESS → MailboxSoA | something to extend or to delete now | add new writers to it; remove it | +| **baton / emission / CollapseGateEmission / emit()** | tombstoned concepts (removed from source) | anything to restore | reintroduce, even "for compatibility" | +| **owner / on_behalf** | `SoaEnvelope::mailbox_owner()` stamp + batch-writer cast pairing | a DTO field | add ownership fields to DTOs (§1 rule 9) | +| **0x1000 (custom half)** | the V3-adoption MONITOR marker (temporary by declaration) | a domain id or a semantic flag | branch business logic on it; mint new meanings for it | +| **canon / custom** | classid halves: hi u16 = canon concept, lo u16 = custom marker/render | "old/new" | read halves with bit math (§1 rule 4) | +| **template** | a compiled, replayable orchestration artifact (elixir-template DSL) | a prompt or a string | degrade a template into a prompt | +| **StepMask** | a QUEUED contract type (W3a) — does not exist yet | something to invent ad hoc | mint it without the W3a spec | +| **facet** | the V3 16-byte atom: 4B prefix (domain\|appid\|classview) + 96-bit payload (soa_layout/le-contract.md §3 catalogue L1–L8) | a free-form struct | add a layout outside the L1–L8 catalogue; put a label/position in a slot | +| **classview (lo u16)** | the ClassView selector in the classid custom half — labels + positions resolve THROUGH it | a place to store data bits | branch on raw classview values other than via read-mode helpers | +| **rail** | a 6×(8:8) payload plane of one-byte refs (part_of:is_a etc.) | an edge list to grow | change rail arity/stride | +| **CAM_PQ digital / analog** | digital = 6×(8:8) palette256² byte pairs (L4, LUT similarity); analog = 48-bit helix + 6B CAM-PQ (L8) | interchangeable encodings | mix the two styles in one lane; compare codes with float math (similarity = DeepNSM 4096 codebook table lookup) | + +## §3 — Footgun catalogue (what broke before → the mechanical prevention) + +| # | Footgun (documented incident) | Mechanical prevention | +|---|---|---| +| F1 | Snippet-read paraphrase errors in briefs/edits (woa-rs Round 9: 3 workers lost 30+ min each) | §1 rule 2. Full Read before edit; grep is a locator only | +| F2 | "All sites routed" claimed from plan inventory; rbac.rs missed (E-CLASSID-COMPAT-READER) | §1 rule 10: coverage claims name the whole-crate grep (pattern + scope) | +| F3 | Local classid bit math shipped 3 latent bugs pre-flip | §1 rule 4 + `/v3-audit` check 1 before commit | +| F4 | Board file edited/overwritten (append-only violation) | §1 rule 5; settings.json denies Edit/Write on the 8 files — do not work around a denial | +| F5 | Write-over-self: file regenerated from prompt instead of edited from state (~N ins/~N del diff signature) | Edit tool for existing files; Write only for NEW files; after a denial or conflict, re-Read then Edit | +| F6 | Shared-tree branch races between parallel workers | §1 rule 6; parallel writers get disjoint FILE lists (this workspace shares one checkout — no worktrees, per cargo-hygiene rule) | +| F7 | 12× cold `target/` build residue (~7 GB each) from fleet cargo runs | §1 rule 7; orchestrator compiles once, centrally | +| F8 | Resurrection of superseded framings copied from stale prose (old CLAUDE.md sections, old plans) | §2 rows CollapseGate/baton/BindSpace; when a doc contradicts `.claude/v3/knowledge/v3-substrate-primer.md` §6, the primer wins — cite it, don't "fix" the code to match stale prose | +| F9 | Deleting/renaming deprecated aliases as "cleanup" (retirement is corpus-proof-gated) | §1 rule 8; the word LEGACY in an identifier = hands off | +| F10 | Inventing a duplicate of an existing type (30-turn rediscovery tax; 4× Fingerprint, 3× ZeckF64 precedent) | §1 rule 3; the brief names types; MODULE-TABLE.md + LATEST_STATE.md Contract Inventory are the lookup — search before any `struct` keyword | +| F11 | New REST endpoint / Wire DTO added on the System-1 path | LAB-only doctrine: extend `UnifiedStep`/`OrchestrationBridge`; a worker asked to add an endpoint = STOP+report (needs lab-vs-canonical-surface.md, an orchestrator decision) | +| F12 | Test literals that only work in one classid order / one layout version (synthetic 0xAB12-style values) | test values come from the §2-sanctioned composers + realistic allocations; never hand-rolled hex composites | +| F13 | Worker "fixes" a failing unrelated test to get green | out of scope (§1 rule 1): report the failure, touch nothing | +| F14 | German PII labels or model identifiers in committed artifacts | never emit either in any file/commit (workspace-wide rule); chat-only | + +## §4 — Sanctioned command palette (copy these, don't improvise) + +- Pre-commit conformance: run the checks in `.claude/commands/v3-audit.md` + (or ask the orchestrator to run `/v3-audit `). +- Board append (the ONLY board write shape): + `tee -a .claude/board/.md > /dev/null <<'EOF' … EOF` +- Coverage grep for classid discriminators (F2/F3): + Grep pattern `(as u16|& *0xFFFF|>> *16|>> *8)` over the WHOLE crate you + touched, then disposition every hit in your report. +- Existing-type lookup before writing any `struct`/`trait`/`enum`: + Grep the name across `crates/` + check `.claude/v3/MODULE-TABLE.md` and + `.claude/board/LATEST_STATE.md` § Contract Inventory. + +## §5 — Escalation (STOP+report triggers — return these, don't resolve them) + +A Sonnet worker returns the question to the orchestrator when ANY of these +appears, because each requires accumulation-tier judgment: + +1. The brief's spec contradicts the code on disk (drift — needs + preflight-drift-auditor, not a local fix). +2. A needed type/lane/mask does not exist (needs a mint decision). +3. Two docs disagree (needs a supersession ruling; primer §6 usually + answers, but the RULING is not the worker's to make). +4. The change would touch bytes at rest (offsets, widths, stored forms — + needs v3-envelope-auditor). +5. The change would add/modify a write path's ownership routing (needs + v3-mailbox-warden). +6. Anything RBAC, PII-adjacent, or externally visible. + +Cross-ref: `.claude/knowledge/autoattended-multiagent-pattern.md` (the +4-savant wave pattern these rules slot into), `v3-substrate-primer.md` +(the doctrine the rules protect), `.claude/v3/MODULE-TABLE.md` (the +existing-type lookup), main `.claude/agents/BOOT.md` (LD-1..5 proof-of-read +checks orchestrators may demand). diff --git a/.claude/v3/knowledge/v3-substrate-primer.md b/.claude/v3/knowledge/v3-substrate-primer.md new file mode 100644 index 000000000..cd19f9297 --- /dev/null +++ b/.claude/v3/knowledge/v3-substrate-primer.md @@ -0,0 +1,117 @@ +# V3 Substrate Primer — the ruled model in one page + +> READ BY: every agent doing V3 work (mailbox-warden, envelope-auditor, +> kanban-executor-engineer, template-smith, integration-lead, dto-soa-savant, +> baton-handoff-auditor) and every fresh session entering via `.claude/v3/README.md`. + +## Status: FINDING (operator-ruled 2026-07-02; board entries are the canonical text) + +This is the orientation doc. Each section names its canonical board entry — +cite THOSE in PRs, not this primer. + +--- + +## 1. The mailbox-kanban model (E-MAILBOX-KANBAN-NO-COLLAPSEGATE) + +There is **no CollapseGate** in the singleton-BindSpace sink-in bundle/bind +sense. The unit of cognition ownership is the **Mailbox**: + +- **One Mailbox = one Kanban board**, carried as a TENANT (per-mailbox, + sibling of the per-row `KanbanTenant`). Six phases: + `Planning → CognitiveWork → Evaluation → Commit → Plan → Prune`. +- Kanban updates execute in **lance-graph-planner** (arm #1, seam + D-MBX-A6: `Outcome → KanbanMove` in `strategy/style_strategy.rs`) or in + **SurrealDB-on-kv-lance symbiont mode** (arm #2, `crates/symbiont` is the + POC shape). `lance-graph-supervisor kanban_actor.rs` is the ractor + structural owner. +- **ractor is a compile-time ownership dummy** — spawn-only, never a + hot-path bus. Rust move semantics through the actor model prove + single-ownership at compile time; that proof is the point, not the runtime. +- The **batch writer fires an AHEAD kanban update on write CAST** — it does + not wait for the write to land. Ownership delegation is checked via cache + logic at cast time (cast id vs envelope stamp). +- **Thinking cycles follow a standing async plan** regardless of updates + (they can't stop thinking; they never wait to be called). The 64k–256k SoA + **load-balances within a 550 ms net budget** (minus load delays). + +## 2. The envelope ownership contract (SHIPPED — `SoaEnvelope::mailbox_owner()`) + +Every SoA envelope is **zero-copy from creation to Lance tombstone** +(`docs/architecture/soa-three-tier-model.md` is canonical). The LE contract +inherits mailbox ownership **up and down**: + +- **Structural** (compile-time): envelope views are `&self` owner-borrows. +- **Nominal** (runtime): `SoaEnvelope::mailbox_owner() -> MailboxId` + (default `0` = bootstrap per the zero-fallback ladder) stamps the owner + for Lance-down provenance and consumer-up write-on-behalf. +- **Iron rule (fleet-wide): every consuming crate writes ON BEHALF OF the + ractor dummy-owner mailbox.** See `write-on-behalf.md`. +- **The V3 atom is the 4+12 facet** (E-V3-FACET-4-PLUS-12): 4-byte prefix + `[domain|appid|classview u16]` + a 96-bit payload from the sanctioned + L1–L8 catalogue (rails / palette256² digital CAM_PQ / triplets / quads / + hhtl+helix absolute location / helix+CAM_PQ analog). **Labels and + positions come from the ClassView — never a payload slot.** Byte truth: + `.claude/v3/soa_layout/le-contract.md`. + +## 3. The DTO ladder (E-DTO-LADDER-OWNERSHIP-SPLIT + E-TWO-RESONANCES-SPLIT) + +`thinking-engine → p64 → cognitive-shader-driver`, four rungs: + +| Rung | DTO | Role | V3 note | +|---|---|---|---| +| Φ | `StreamDto` | perturbation ingress | ancestor of the standing-async-plan ruling | +| Ψ | `dto.rs::ResonanceDto` | MECHANICAL Morton-tile inverse-pyramid perturbation field | renames → `PerturbationDto` (D-PERT-1, deprecated alias) | +| B | `BusDto` | cognitive commit (what was thought, how settled) | **never grows ownership fields**; batch writer pairs `cast(on_behalf = envelope.mailbox_owner(), payload = BusDto)` | +| Γ | `ThoughtStruct` | persistence | persists via the owner-stamped envelope | + +`awareness_dto.rs::ResonanceDto` **keeps its name** — it is the PERSPECTIVAL +resonance (Piaget Three-Mountains: 3D subject/predicate/object HdrResonance + +inferred user model) against the object's self-Gestalt (`classid → ClassView` += "the object speaks for itself"). "Cascade" (HEEL/HIP/TWIG key tiers) is +canon vocabulary and is NOT renamed. + +**L4 learning loop:** converged perturbation residue persists into tenant +lanes via the owner-stamped envelope; the next cycle's standing template +reads the row — the persisted perturbation reshapes the next F landscape. + +## 4. Compiled thinking templates (E-COMPILED-THINKING-TEMPLATES) + +Orchestration compiles like `askama ↔ ClassView × FieldMask`: + +- DSL triple ships in-tree: `elixir-template` (representation + parser) + + `template-runtime` (deterministic OGAR-action dispatch) + + `template-equivalence` (replay grading). `ogar-from-elixir` = future + richer frontend. +- A successful LLM run (**Rig = optional LLM template oracle**) compiles + DOWN to a deterministic replayable template. `rs-graph-llm` (graph-flow) + executes instances as replayable sessions **inheriting SoA ownership**. +- A **StepMask** bitmask (sibling of `FieldMask`) selects live steps per + style/dispatch. Post-P4 the classid custom half indexes the template + catalogue — 36 thinking styles as 36 lenses over the same canon concept. + +## 5. Classid canon-high + the V3 monitor (E-CLASSID-* + E-V3-MARKER-IS-A-MONITOR) + +- Composed classid = `[hi u16 CANON concept/domain:appid][lo u16 CUSTOM]`. + Compose only via `contract::render_classid` / `compose_classid`; + discriminate only via `classid_canon` / `classid_canon_compat`. + FORBIDDEN on the composed u32: `as u16`, `& 0xFFFF`, `>> 8`, `>> 16`. +- `0x1000` in the custom half = the **V3-adoption MONITOR**, temporary by + declaration. P4's trigger is defined: adoption reads 100%; then the marker + retires and the custom half opens for the 64k render/template catalogue. +- Canon-high is a **clustered index**: domain scans = key-range predicates; + the adoption monitor + corpus-proof scanner are ONE two-metric + range-count tool. + +## 6. What must NOT be reinvented + +| Superseded | Successor | +|---|---| +| Singleton BindSpace + CollapseGate sink-in | per-mailbox `MailboxSoA` + Kanban tenant | +| Baton / `CollapseGateEmission` / `emit()` | zero-copy envelope; Lance columnar I/O is the only writer | +| `Vsa16kF32` as cross-mailbox carrier | intra-compartment bundle math only (The Click, local) | +| Ownership fields on `BusDto` | `SoaEnvelope::mailbox_owner()` + cast pairing | +| Local classid bit math in consumers | contract/ogar-vocab composers | + +Cross-ref: `.claude/board/EPIPHANIES.md` (entries named above), +`.claude/handovers/2026-07-02-classid-canon-high-flip-to-v3-thinking-sessions.md`, +`docs/architecture/soa-three-tier-model.md`, `.claude/v3/README.md`. diff --git a/.claude/v3/knowledge/write-on-behalf.md b/.claude/v3/knowledge/write-on-behalf.md new file mode 100644 index 000000000..8c47cb9f3 --- /dev/null +++ b/.claude/v3/knowledge/write-on-behalf.md @@ -0,0 +1,79 @@ +# Write-on-Behalf — the fleet-wide consumer iron rule + +> READ BY: mailbox-warden, envelope-auditor, every consumer-crate session +> (q2, MedCare-rs, woa-rs, smb-office-rs, openproject-nexgen-rs, OGAR, +> ladybug-rs), and any session adding a write path to SoA rows / Lance +> datasets / tenant lanes. + +## Status: FINDING (operator-ruled 2026-07-02; enforcement mechanics EXTEND — batch writer pending) + +--- + +## The rule + +**Every consuming crate writes ON BEHALF OF the ractor dummy-owner mailbox. +Always.** No consumer writes a SoA row, tenant lane, or Lance dataset as +itself. The write names its owner via the envelope stamp: + +```rust +// the ONLY sanctioned shape (batch-writer pairing): +cast(on_behalf = envelope.mailbox_owner(), payload = BusDto { .. }) +``` + +- `SoaEnvelope::mailbox_owner() -> MailboxId` is the nominal stamp + (default `0` = bootstrap, zero-fallback ladder — dormant until minted). +- The envelope's `&self` views are the structural half: borrowing a view IS + borrowing from the owner, proven at compile time. +- **`BusDto` never grows ownership fields.** Cognitive provenance (what was + thought, how settled: converged, cycle_count) and write provenance (whose + lane, who may write) are orthogonal and are paired AT CAST, not merged + into one type. A PR adding `owner`/`mailbox`/`tenant_id` to `BusDto` (or + any Φ/Ψ/B DTO) is a defect — reject and route to the envelope stamp. + +## Why (the two directions of inheritance) + +- **Down (Lance provenance):** every persisted row is attributable to a + mailbox — the L4 learning loop (perturbation residue → tenant lane → + next cycle's template) only works if lanes are owner-keyed. +- **Up (consumer clarity):** a consumer never needs to know SoA internals; + it needs one MailboxId and the contract composers. Delegation questions + (may THIS caster write into THAT lane?) are the batch writer's delegation + cache, resolved at cast time — never the consumer's problem and never a + RBAC re-implementation in the consumer. + +## Consumer preflight (5 questions, 60 seconds) + +Before authoring any consumer write path: + +1. **Who is the owner?** Which mailbox does this write serve? If "none", + you are writing bootstrap (`0`) — is that intended, or are you missing a + mint? +2. **Where is the stamp?** Does the write route through an owner-stamped + envelope / the batch writer, or does it hit Lance/SoA directly? + Direct = defect (interim exception: bake pipelines, see below). +3. **Is the payload clean?** No ownership fields on the DTO; classids + composed via `contract::render_classid` / `ogar_vocab::app::*`, never + local bit math. +4. **Which tenant lane?** Named per `soa_layout/tenants.md`; new lanes need + the field-isolation matrix (envelope-auditor gate). +5. **Is the write idempotent per cycle?** `last_active_cycle` is the + same-cycle guard — respect it, don't reinvent it. + +## Interim reality (audited 2026-07-02; CORRECTED same day by the consumer audit) + +No consumer writes on-behalf yet — the batch writer does not exist +(INTEGRATION-PLAN W1). Almost all consumer writes are **bake pipelines** +(q2 `osint_scene.soa` / `fma.soa` / `body.soa`): offline, single-writer, +owner-less by construction — grandfathered as bootstrap-owner writes, +migrating in W5. + +**ONE exception, found by audit and named so it is never assumed away:** +smb-office-rs `LanceConnector::upsert` (smb-bridge/lance.rs:176-201, +live caller smb-woa/customer.rs:189-195) is an **online** Lance write — +no stamp, no envelope, no classid. It is W5's first live migration +target (`consumer-map.md` §2), explicitly flagged rather than silently +grandfathered. Do not add NEW online write paths without the stamp; do +not model new writers on the smb-office path. + +Cross-ref: `v3-substrate-primer.md` §2–3, `mailbox-kanban-model.md`, +`.claude/v3/soa_layout/consumer-map.md`, board `E-DTO-LADDER-OWNERSHIP-SPLIT`. diff --git a/.claude/v3/soa_layout/README.md b/.claude/v3/soa_layout/README.md new file mode 100644 index 000000000..e99a72029 --- /dev/null +++ b/.claude/v3/soa_layout/README.md @@ -0,0 +1,19 @@ +# soa_layout/ — the V3 byte-and-ownership contracts + +> Per-tenant + consumer documentation mapping, LE contract, and routing — +> the operator-requested layout home (2026-07-02). Read in this order: + +| Doc | Carries | Read when | +|---|---|---| +| **`le-contract.md`** | the 4+12 facet atom (`[domain\|appid\|classview] + 96-bit payload`), the L1–L8 payload catalogue + polymorphic (8:8) readings, slot purity ("labels and positions come from the ClassView"), the two-level LE contract + jc-pillar gate (§3b), classview-as-focus-lens + the 64-bit-cramp retirement, and the CODE ground truth (§5: FacetCascade/CascadeShape/hi-lo chains + the honest discrepancies) | touching any byte layout, facet, or payload reading | +| **`tenants.md`** | the 10 ValueTenant lanes with exact offsets/widths (ENVELOPE_LAYOUT_VERSION=2), ValueSchema presets, the classid→ReadMode registry, the in-RAM MailboxSoA mirror, and the four flagged seams (SoaEnvelope zero production impls; Meta/Plasticity width mismatches; MailboxId≠NiblePath; jc gate per lane) | reading/writing a tenant lane, adding a schema, wiring a consumer | +| **`consumer-map.md`** | the six-consumer audit: adoption tiers T1–T4, the warden write-path table (ONE live ORPHAN-WRITE: smb-office-rs), dispositioned defects, reference patterns, W5 consequences | any consumer-crate session; W5 planning | +| **`routing.md`** | address-as-router (canon-high clustered index, tier shift/mask, zero-fallback ladder), MailboxId/NiblePath routing, the cast→delegation→owner→board write route, read-mode aliasing, adoption-as-range-count | adding any lookup/scan/dispatch over V3 keys | + +Iron context (don't re-derive): `../knowledge/v3-substrate-primer.md` is +the one-page doctrine; board `E-V3-FACET-4-PLUS-12` / +`E-V3-CLASSVIEW-FOCUS-LENS` / `E-V3-TWO-LEVEL-LE-JC-GATE` are the +canonical ruling texts; `CLAUDE.md § CANON` locks the 512-byte node. +Gates: every layout diff → `v3-envelope-auditor`; every write path → +`v3-mailbox-warden`; every new lane consumer → jc pillars (ICC / Spearman +ρ / Cronbach α) before its reading backs a claim. diff --git a/.claude/v3/soa_layout/consumer-map.md b/.claude/v3/soa_layout/consumer-map.md new file mode 100644 index 000000000..aae787aec --- /dev/null +++ b/.claude/v3/soa_layout/consumer-map.md @@ -0,0 +1,80 @@ +# Consumer Map — who writes what, on whose behalf (audit 2026-07-02) + +> READ BY: v3-mailbox-warden, every consumer-crate session, W5 planners. +> Evidence: consumer-audit fleet pass over the six local checkouts, +> file:line-cited. The iron rule it audits against: `write-on-behalf.md`. + +## Status: FINDING — one live ORPHAN-WRITE found (smb-office-rs); everything else is bakes or pre-persistence + +--- + +## §1 The adoption tiers (classid/addressing) + +| Tier | Consumers | Pattern | +|---|---|---| +| **T1 — canonical resolvers** | openproject-nexgen-rs `op-canon` (reference quality: pure re-exports of `ogar_vocab::app::*`, bit math only in round-trip TEST asserts); MedCare-rs `auth_bridge` (pulls `0x0B01_0000` through the rbac membrane, "never hardcodes") | delegate to the ONE upstream composer | +| **T2 — canonical composer itself** | OGAR `ogar-vocab::app` (`render_classid/app_of/concept_of` — the single sanctioned home of the bit math); `ogar-from-ruff/mint.rs` (composes via it; unmapped models mint bootstrap `0`, tested) | the canon | +| **T3 — dep-free byte-identical hand-copies** (sanctioned interim, OGAR_CONSUMER_INTEGRATION §2.3) | q2 `fma/converge.rs` (the model), q2 `cpic` (Genetics `0x0E01_000N`, interim by its own doc), woa-rs `erp/canon.rs` (unwired module, zero callers yet, Phase-3 doc points at `render_classid`) | own the 16 bytes, assert byte-identity, skip the dep — three copies, zero shared code (M21) | +| **T4 — outside the ladder entirely** | smb-office-rs (ZERO classid/NodeGuid anywhere; addresses by `(namespace, table, EntityKey)` strings via `contract::repository`) | never entered the classid ladder — cannot use prefix routing / key-only scans | + +## §2 Write paths (the warden's table) + +| Consumer / path | What it writes | Ownership | Verdict | +|---|---|---|---| +| q2 `osint-bake` bins (body.rs:153, fma.rs:440), `fma/converge.rs:448` | `body.soa` / `fma.soa` / TSVs via `std::fs::write` — offline artifacts (Release assets, not git) | none — offline single-writer | **BOOTSTRAP-OK** (the documented interim exception) | +| q2 cockpit-server runtime | NO durable writes — `include_bytes!` embeds + tokio RwLock in-memory state only | n/a | clean | +| **smb-office-rs `LanceConnector::upsert`** (smb-bridge/lance.rs:176-201) ← called from smb-woa/customer.rs:189-195 | **LIVE `Dataset::write` to a real Lance dataset**, keyed `(namespace, "smb.customer", EntityKey)` | **none — no stamp, no envelope, no classid** | **ORPHAN-WRITE** — the first live migration target of W5; the ONLY online consumer write found fleet-wide | +| MedCare-rs | no writer exists yet — `soa_mapping.rs` is schema metadata for 7 entities; the `medcare-soa` writer crate is "forthcoming" | n/a | **day-one opportunity**: route through the stamp from the first line (don't repeat smb-office) | +| woa-rs | no SoA/Lance writes at all (K-steps write MySQL via sea-orm per its writer-parity rule); `erp/canon.rs` has zero callers | n/a | pre-adoption | +| openproject-nexgen-rs | no persistence in scope — pure classid resolution | n/a | pre-persistence | +| OGAR `ogar-from-ruff` | emits SOURCE TEXT (Rust/C#/Python codegen), no storage writes | n/a | n/a | + +## §3 Defects & drift found (dispositioned) + +1. **OGAR `emit.rs:260-265,324-329,382-387`** — three identical + `facet_classid() as u16` sites label the LOW half "(concept 0x…)" in + generated doc comments. Pre-flip that was the concept; **post-flip it's + the APP PREFIX** (`account.move` → prints `0x0002` instead of concept + `0x0202`). The `_CLASSID` const itself (full u32) is correct. Fix = + `ogar_vocab::app::concept_of(...)` at all three sites (1 line × 3); + propagates into every generated SDK until fixed. → queued as W5 row. +2. **q2 `data/osint-v3/osint_v3_codebook.json`** — stores PRE-flip order + (`0x1000_0700/0x1000_0701`); q2's own newer code (osint-bake + `0x0700_0000`, BodyV3.tsx dual-alias) already migrated. No reader of + the raw strings found → **latent**, but the exact I-LEGACY failure + shape if any future reader assumes canon-high. → collapse with the + dual-bake milestone (M22). +3. **woa-rs false positive on the V3 marker**: `festschreibung.rs:117`'s + `0x10000` is UTF-16 surrogate math, NOT the marker — recorded so a + grep-only pass never miscounts woa-rs as V3-marker-aware. + +## §4 Reference patterns (point consumers here) + +- **Classid resolution**: `op-canon/src/app.rs` — thin re-exports, test-only + bit math for round-trip verification. +- **Dual-alias read across the flip**: q2 `BodyV3.tsx:22-28,437-443` — + `FMA_V3_CLASSID` + `_LEGACY`, both checked at render time; the cleanest + V3-marker-aware code in the fleet. +- **Post-flip self-documentation**: q2 `osint_gotham.rs:507-513` — doc + comment warning that `classid & 0xFFFF` now reads the custom half. +- **Zero-fallback minting**: `ogar-from-ruff/mint.rs` — unmapped model → + bootstrap `0`, never a wrong stamp (tested). + +## §5 W5 consequences (feeds INTEGRATION-PLAN) + +1. smb-office-rs `LanceConnector::upsert` is **W5's first live migration** + (stamp + batch-writer routing when W1 lands; until then: explicitly + grandfather-or-flag, never silently assume it's a bake). +2. MedCare-rs `medcare-soa` writer: **born stamped** (design gate before + first merge). +3. OGAR emit.rs 3-line fix + regen check. +4. q2: collapse the two OSINT bakes (crates/osint-bake canon-high vs + data/osint-v3 stale pre-flip dual-GUID scheme) into one canon-high bake + (M22); cpic contract pull with mereology dissolves the interim scheme + (existing D-V3-W5b). +5. T3 hand-copies → one zero-dep `canon-node-bytes` extraction (M21) — + ends three-way byte-layout re-derivation. + +Cross-ref: `write-on-behalf.md` (corrected: "interim reality" now names +the smb-office exception), COMPONENT-MAP §7, ENTROPY-MILESTONES M21-M23, +board E-V3-FACET-4-PLUS-12. diff --git a/.claude/v3/soa_layout/le-contract.md b/.claude/v3/soa_layout/le-contract.md new file mode 100644 index 000000000..50b7ab292 --- /dev/null +++ b/.claude/v3/soa_layout/le-contract.md @@ -0,0 +1,229 @@ +# The V3 LE Contract — the 4+12 facet atom + +> READ BY: v3-envelope-auditor (mandatory), v3-mailbox-warden, anyone +> touching soa_envelope.rs / canonical_node.rs / tenant value schemas / +> bake pipelines. Routing semantics: `routing.md`. Lane meanings: +> `tenants.md`. Who writes what: `consumer-map.md`. + +## Status: OPERATOR-LOCKED (2026-07-02, verbatim spec) — board entry E-V3-FACET-4-PLUS-12 + +--- + +## §1 The atom: 4 + 12 bytes (96-bit payload) + +Every V3 unit is a **16-byte facet**: a 4-byte address prefix followed by a +96-bit payload. Little-endian throughout; nothing above the +`from_le_bytes` boundary cares about byte order. + +``` +byte 0 byte 1 bytes 2..3 bytes 4..15 +┌───────────┬───────────┬────────────────┬──────────────────────────────┐ +│ class/ │ appid │ classview │ payload — 96 bits, one of │ +│ domain │ (2 nibble)│ (u16, 4 nibble)│ the sanctioned layouts (§3) │ +│ (2 nibble)│ │ │ │ +└───────────┴───────────┴────────────────┴──────────────────────────────┘ +└────────── composed classid u32 ────────┘ + canon hi u16 = domain:appid custom lo u16 = classview +``` + +- The 4-byte prefix IS the composed classid (canon-high, #628): canon + hi u16 = `domain byte ++ appid byte` (e.g. `0x07:01` = OSINT:q2); + custom lo u16 = the **ClassView selector**. Today the classview u16 + hosts the `0x1000` V3-adoption monitor + the OGAR §2 app render + prefixes + interim kind slots; post-P4 it is the full 64k + ClassView/template catalogue. +- Compose/split ONLY via the contract helpers (`render_classid`, + `compose_classid`, `classid_canon`, `classid_canon_compat`) — the + byte spelling above is documentation, never license for bit math + (guardrails §1 rule 4). + +## §2 The slot-purity rule (operator: "never waste a slot") + +**Labels and positions come from the ClassView — NEVER from a slot in the +payload.** No name strings, no display labels, no layout positions, no +ordinal columns in any facet. The classview u16 resolves to the ClassView, +and the ClassView carries labels, field positions, and render order +(register-file model: the SoA is dumb bytes; the class makes them +meaningful). A proposed facet layout containing a label/position slot is a +LAYOUT-BREAK-class defect — reject at review. + +## §3 The sanctioned 96-bit payload layouts (operator-locked catalogue) + +Every 12-byte payload is exactly one of these; the classview selects which. + +| # | Layout | Shape | Semantics | Notes | +|---|---|---|---|---| +| L1 | rails | 6 × (8:8) | `part_of : is_a` | the V3 mereology:taxonomy key rails; one-byte refs per slot | +| L2 | rails | 6 × (8:8) | `memberof : members` | membership plane | +| L3 | rails | 6 × (8:8) | `mereology : taxonomy` | generic mereology:taxonomy plane (as dictated) | +| L4 | palette pairs | 6 × (8:8) | `palette256²` — **CAM_PQ "digital" new style** | each byte pair indexes the 256×256 palette distance/compose tables (bgz17 lineage); similarity = ONE table read | +| L5 | triplets | 4 × (8:8:8) | SPO-style triplets | four 3-byte triples | +| L6 | quads | 3 × (8:8:8:8) | odoo-shaped relations | **[H] semantics open** — operator marked "odoo ?"; do not implement semantics before a ruling | +| L7 | absolute location | 2 × 48-bit | `hhtl ++ helix` | hhtl(48) = HEEL\|HIP\|TWIG (3×u16); helix(48) = helix place code. Together = absolute location, **two hemispheres** — see q2 FMA for usage | +| L8 | location, old style | 2 × 48-bit | `helix ++ CAM_PQ` — **CAM_PQ "analog" old style** | the harvest facet `helix-place(6) \| cam-pq(6)` — the 6-byte canonical CAM-PQ, NOT the 16-byte turbovec residue | + +Byte accounting: every layout is exactly 12 bytes — 6×2, 4×3, 3×4, 2×6. +The 16-byte facet stride never changes; layouts differ only in how the +96 payload bits subdivide. + +### The (8:8) pair is polymorphic — the classview selects the reading + +Beyond L1–L4, a `6×(8:8)` plane admits these operator-sanctioned readings +(2026-07-02 extension): + +- **`area : location` in stacked exactness** — the six pairs stack as a + precision ladder: each pair refines the location within its area; + stacked levels = progressive exactness. +- **Second GUID (relationships):** when a node carries a second GUID + dedicated to relationships, its rail plane is ENCOURAGED to carry six + relations as **`basin : relationtype`** pairs (one-byte basin ref + + one-byte relation type). +- **Static-basin variant:** if the basins are **12 static**, the pair + upgrades to **`relationtype : relationtype_orthogonal`** — the basin is + implied by position/static table, freeing both bytes for two orthogonal + relation types. + +The reading is ALWAYS selected by the classview (slot purity §2) — never +by inspecting payload bytes, never by convention-in-code. + +### The classview is a FOCUS LENS (operator, 2026-07-02) + +The layout choice is not a storage convention — **the classview is the +focus lens that the DATA SHAPE wants**. A class whose data is relational +focuses rails; positional data focuses the location layouts; similarity +data focuses palette pairs. The lens follows the data, and the classview +carries that focus; code never second-guesses it. + +### Let go of the cramped 64-bit register (operator, 2026-07-02) + +The prior approach — cramming awareness into a 64-bit packed edge register +and *"hoping for a 3-bit mantissa to mean the whole awareness"* +(the CausalEdge64 inference-mantissa lineage, cf. the +I-LEGACY-API-FEATURE-GATED 5-instance catalogue those bits generated) — +is **let go**. Awareness/relation semantics get real width in the 96-bit +facet payloads, lens-selected per class. Consequences: + +- Do NOT extend CausalEdge64 bit fields to carry new awareness semantics; + new semantics land as facet layouts (L1–L8 + sanctioned readings). +- **[H] open:** CausalEdge64's residual role (wire/protocol/EdgeBlock + compatibility) vs full retirement — needs a scoping ruling; the + `edges[16B]` block in the CANON node is untouched by this (it is + one-byte SLOT refs, not packed mantissas). + +### CAM_PQ grounding (digital vs analog) + +CAM_PQ's codebook is the **DeepNSM 4096-word English-native-speaker +codebook** (`crates/deepnsm`, COCA vocabulary): similarity between codes +A and B is a **distance-table lookup, never a float** — the 4096² u8 +distance matrix (and the 256×256 palette tables at L4 granularity) IS the +similarity function. Two styles coexist: + +- **"digital" new style (L4):** discrete palette-code byte pairs; distance + composes through the 256×256 LUTs (palette semiring). +- **"analog" old style (L8):** 48-bit helix place codes + 6-byte CAM-PQ + codes; continuous-flavored place geometry, table-compared. + +### Open reconciliation items ([H] — flag, don't resolve locally) + +- **L7 helix(48) vs the CANON key tail `family(u24)++identity(u24)`:** + both are the trailing 48 bits of a 16-byte unit. Whether the CANON node + key is literally an L7 facet (payload = absolute location) or a sibling + layout is a ground-truth question for the envelope reconciliation — + do not unify silently in code. +- **L6 semantics** await an operator ruling (the "odoo ?" mark). + +## §3b Two-level LE contract + the jc-pillar validation gate (operator, 2026-07-02) + +**"32-bit class, 96-bit data"** — and the contract is TWO-LEVEL: + +- **Every TENANT has its own LE contract** (the facet layout it carries, + per §3), and +- **the SoA envelope has ITS LE contract** (the register-file descriptor: + ColumnDescriptor offsets/widths, `verify_layout()`, + `ENVELOPE_LAYOUT_VERSION`). + +The nesting is the point: the tenant contract is scoped INSIDE the +envelope contract, and both inherit the **single, compile-time-inherited +SoA write ownership** (owner-borrows structurally, +`mailbox_owner()` nominally). A tenant lane can never acquire a writer +the envelope doesn't know; an envelope can never write a lane whose +tenant contract it doesn't carry. Scopedness is the guarantee, not a +convention. + +**Consumer validation gate (jc pillars):** every payload layout is so +DISTINCT that consumer readings are validated LATER against the `jc` +crate pillars in lance-graph — the certification math: **ICC, Spearman ρ, +Cronbach α** (and siblings). A consumer that starts reading a tenant lane +owes a jc-pillar certification run (the certification-officer pattern: +real bytes, deterministic sampling, 4-decimal reporting) before its +reading is trusted in any downstream claim. This is the statistical +mirror of the field-isolation matrix: layout tests prove bytes don't +move; jc pillars prove the READING preserves the semantics. + +## §4 Relation to the CANON node and the envelope + +- The CANON node (`CLAUDE.md` § Minimal SoA node, locked 2026-06-13) + stays authoritative for the 512-byte row: `key(16) | edges(16) | + value(480)`. The facet atom is the unit INSIDE value lanes (and the key + itself is 16 bytes with the same 4+12 rhythm — see §3 open items). +- The 480-byte value slab holds facets per the tenant schema: + `classid_read_mode(c).value_schema` selects which lanes/layouts a class + carries (`tenants.md` catalogues them). +- `SoaEnvelope` is the register-file descriptor (ColumnDescriptor per + column; `verify_layout()` = ABI conformance; `ENVELOPE_LAYOUT_VERSION` + gates any byte movement). `SoaEnvelope::mailbox_owner()` stamps + ownership; it lives on the ENVELOPE, never in a facet slot (§2 applies + to ownership too). +- RESERVE-DON'T-RECLAIM: zeroed facets/lanes are dormant, never + compacted; layouts are selected by classview, never by stride change. + +## §5 Code ground truth (mapping fleet, 2026-07-02) + +**The facet atom is CODED.** `facet.rs`: `FacetTier{lo,hi}` (2 B) + +`FacetCascade{facet_classid: u32, tiers: [FacetTier;6]}` — 4+12=16 B, +`size_of == 16` const-asserted (facet.rs:31-100); LE wire order +`facet_classid@[0..4)` then 6×[lo,hi]. Slot purity is enforced by +construction: the cascade is content-blind; only the ClassView interprets +the 8:8. + +**Byte shapes vs the L1–L8 semantic catalogue:** the code implements +exactly 3 shapes + 1 lane (facet.rs:394-546, 207-223): + +| Code | Shape | Covers | +|---|---|---| +| `CascadeShape::G6D2` | 6 groups × 2 levels (shift `>>1`) | L1–L4 — differentiated ONLY by ClassView (slot purity, as §2 demands) | +| `CascadeShape::G4D3` | 4 × 3 (divide) | L5 triplets | +| `CascadeShape::G3D4` | 3 × 4 (shift `>>2`) | L6 quads / canonical GUID tiers | +| `hi_chain()/lo_chain()` | 2 × 48-bit | L7/L8 — "a SEPARATE lane … never dragged into ClassView shape selection" (module doc) | + +**Envelope:** `ENVELOPE_LAYOUT_VERSION = 2` (soa_envelope.rs:54; v2 = +HelixResidue 48 B→6 B right-sizing). `ColumnKind` (8 width-only LE kinds), +`ColumnDescriptor{name_id: u16, kind, elems_per_row: u16, row_offset: u32}`, +`verify_layout()` with 6 error paths incl. wasm-overflow checks. +`SoaEnvelope::mailbox_owner()` default 0 (soa_envelope.rs:170-197). +Tenant catalogue + ValueSchema presets + ReadMode registry: `tenants.md`. + +**Honest discrepancies (carried, not hidden):** + +1. **`SoaEnvelope` has NO production implementor** — only a test-only + TestEnvelope. `MailboxSoA` implements the sibling + `MailboxSoaView/MailboxSoaOwner` traits; `NodeRow` reads via the + `VALUE_TENANTS` table. Two parallel column-geometry systems share + ColumnDescriptor/ColumnKind by convention, not by trait + (ENTROPY-MILESTONES M7; W1 wiring decides the survivor). +2. **L7 open item sharpened:** `hi_chain/lo_chain` interleave one byte per + tier ACROSS 6 tiers; the V1 key tail is two CONTIGUOUS u24s + (family/identity). Structurally different bit-groupings — the code does + NOT silently unify them; the reconciliation stays [H] as flagged in §3. +3. **MailboxId ≠ NiblePath in code** — `MailboxId = u32` + (collapse_gate.rs:121), `NiblePath{path: u64, depth: u8}` (hhtl.rs:56); + no conversion, no shared trait, no code comment linking them. The + three-tier doc's "MailboxId IS the NiblePath" is a doc-only claim + awaiting a ruling or a wiring PR. +4. Persisted-vs-hot width mismatches (Meta 8 B/4 B, Plasticity 4 B/1 B) — + see `tenants.md` §7; parity test required before any 1:1 sync. + +Cross-ref: board `E-V3-FACET-4-PLUS-12` (canonical ruling text), +`routing.md` §1 (prefix routing), `tenants.md`, primer §2, +`.claude/plans/soa-value-tenant-migration-v2.md` (the 16 B facet lineage: +`facet_classid(4) | helix-place(6) | cam-pq(6)` = L8 with its prefix). diff --git a/.claude/v3/soa_layout/routing.md b/.claude/v3/soa_layout/routing.md new file mode 100644 index 000000000..6ef2326c0 --- /dev/null +++ b/.claude/v3/soa_layout/routing.md @@ -0,0 +1,110 @@ +# Routing — how an address finds its class, tenant, owner, and board + +> READ BY: v3-envelope-auditor, v3-kanban-executor-engineer, anyone adding a +> lookup/scan/dispatch over V3 keys. Byte layout itself: `le-contract.md`. + +## Status: FINDING (address canon operator-locked; kanban routing EXTENDS pending W1/W2) + +--- + +## 1. The address is the router (no lookup tables in the hot path) + +The canonical 16-byte LE key routes at every prefix depth +(CANON, `CLAUDE.md` § Minimal SoA node): + +``` +0..4 classid u32 [hi u16 CANON concept/domain:appid][lo u16 CUSTOM] +4..6 HEEL u16 ┐ +6..8 HIP u16 ├ cascade tiers (HHTL path; 256×256 centroid tiles) +8..10 TWIG u16 ┘ +10..13 family u24 ┐ basin-local key +13..16 identity u24 ┘ (masked load once the trie binds the prefix) +``` + +Routing consequences, in prefix order: + +| Prefix consumed | Routes to | Mechanism | +|---|---|---| +| canon hi-u16 | domain + app (`ConceptDomain` = `canon >> 8`) | range predicate over the **DECODED u32** — canon-high clusters by domain in VALUE order (E-CLASSID-CANON-HIGH-IS-A-CLUSTERED-INDEX). **Byte-order caveat (codex #629):** `NodeGuid` stores classid LE, so RAW key-byte prefixes order by the custom byte first — a byte-trie/raw-prefix scan does NOT walk domain-first; decode the u32 or use an order-preserving big-endian rendering for range keys | +| custom lo-u16 | render skin / (post-P4) template lens; `0x1000` = V3-adoption monitor | catalogue dispatch; monitor is a marker, never a semantic | +| classid (full) | `ClassView` + `classid_read_mode(c).value_schema` (tenant schema) | O(1) codebook; longest-prefix codebook binding (OGAR tier rule) | +| HEEL/HIP/TWIG | cascade position | shift/mask only (`tier = level >> 2`); tier distance = 3 table lookups | +| family | basin (neighborhood grouping) | dormant while 0 (zero-fallback ladder) | +| identity | the row | masked 6-byte `local_key()` | + +**Zero-fallback ladder:** a zero tier means *not consulted*, never +*compacted away* (RESERVE-DON'T-RECLAIM). Bootstrap addressing = classid 0 ++ family 0 + identity alone. + +## 2. Mailbox routing — MailboxId IS the NiblePath + +Per `docs/architecture/soa-three-tier-model.md` Tier 3: the `u32 mailbox_id` +is not a handle into a table — it IS the HHTL radix-trie key. + +- `NiblePath::is_ancestor_of` = prefix ancestry = class ancestry. +- Ontology resolution is O(1) for known classes; JITson for new ones. +- Consequence: per-row `entity_type: u16` is transitional and retires once + the O(1) path is sole (three-tier doc §Tier-3) — a routing entropy + milestone in its own right. +- **Thinking metric for free** (handover F4): `from_guid_prefix_v3` + + `family_hop_count` give O(depth), zero-value-decode graph distance — + the natural adjacency for AriGraph/episodic tissue. + +## 3. Write routing — cast → delegation cache → owner → board + +The V3 write path routes by OWNER, not by table (W1/W2 of the +INTEGRATION-PLAN; today only the stamp exists): + +``` +consumer/engine + │ cast(on_behalf = envelope.mailbox_owner(), payload = BusDto) + ▼ +batch writer ── delegation cache (cast id vs stamp: hit→proceed, miss→resolve once) + │ fires AHEAD KanbanMove at cast (never waits for the write) + ├────────────► owner actor (supervisor kanban_actor) ── MailboxSoaOwner::advance_phase [SOLE mutator] + ▼ +Lance columnar I/O (LE bytes from the in-place store — the only byte writer) +``` + +Routing rules: +- Moves route to the mailbox's OWNER actor; nothing else mutates phase. +- A missing/late update never gates a thinking cycle (standing async plan); + updates only reprioritize (StepMask). +- Delegation is resolved AT the batch writer — consumers never route + "may I write?" questions themselves. + +## 4. Read-mode routing — legacy forms resolve forever + +Stored corpora carry pre-flip classids and V1/V2 tails. Readers route +through: + +- `classid_canon(id)` — strict, new mints; +- `classid_canon_compat(id)` — surfaces serving BOTH stored forms (RBAC + grants, un-re-baked corpora); +- `BUILTIN_READ_MODES` `CLASSID_*_LEGACY` alias keys — persisted old-form + ids resolve without re-baking (mint-forward, never reinterpretation). + +Alias retirement routes through the corpus proof only (W6). FORBIDDEN +discriminators on the composed u32: `as u16`, `& 0xFFFF`, `>> 8`, `>> 16` +(`/v3-audit` check 1). + +## 5. Monitor routing — adoption is a range count + +Because canon-high clusters by domain, both governance metrics are +key-range counts over the same index — ONE two-metric scanner (W6a): + +- **adoption%** = rows whose custom half carries `0x1000` (V3 substrate) + vs total, per domain; +- **corpus proof** = count of old-form rows — ALL THREE legacy shapes + (codex #629): `0x0000_DDCC` (zero-prefix), `0x1000_DDCC` (pre-flip V3 + marker high), AND `0xAAAA_DDCC` (legacy app/render prefix high, e.g. + `0x0005_0901`) — i.e. exactly the set `classid_canon_compat` routes + through the CanonLow fallback. Scanning only the first two can falsely + prove the corpus clean while un-rebaked render rows remain. Zero across + all three ⇒ alias retirement unlocks; adoption 100% ⇒ P4 trigger + (operator checkpoint) ⇒ marker deprecates ⇒ custom half opens for the + render/template catalogue. + +Cross-ref: `le-contract.md` (bytes), `tenants.md` (what the value lanes +mean), `consumer-map.md` (who writes what), primer §5, +board E-V3-MARKER-IS-A-MONITOR. diff --git a/.claude/v3/soa_layout/tenants.md b/.claude/v3/soa_layout/tenants.md new file mode 100644 index 000000000..419a75344 --- /dev/null +++ b/.claude/v3/soa_layout/tenants.md @@ -0,0 +1,119 @@ +# Tenant Lanes — the value-slab catalogue (code ground truth 2026-07-02) + +> READ BY: v3-envelope-auditor (mandatory), anyone reading/writing a tenant +> lane, adding a ValueSchema, or wiring a consumer. Byte atom + payload +> catalogue: `le-contract.md`. Who writes what: `consumer-map.md`. +> Ground truth source: mapping-fleet pass over +> `crates/lance-graph-contract/src/{canonical_node,soa_envelope,facet,kanban,soa_view}.rs` +> + `crates/cognitive-shader-driver/src/mailbox_soa.rs`. + +## Status: FINDING (byte-accurate, file:line-cited; two flagged seams at the end) + +--- + +## §1 The persisted row and its slab + +`NodeRow` = 512 B: `key(16) | edges(16) | value(480)`. +`VALUE_SLAB_ROW_OFFSET = 32`, `VALUE_SLAB_LEN = 480` +(canonical_node.rs:718-720). **`ENVELOPE_LAYOUT_VERSION = 2`** +(soa_envelope.rs:54) — v2 = HelixResidue right-sized 48 B → 6 B, shifting +every downstream tenant offset. Every tenant below carries its OWN LE +contract nested in the envelope's (le-contract.md §3b). + +## §2 The 10 value tenants (`ValueTenant`, canonical_node.rs:729-849) + +Discriminant = FieldMask bit = VALUE_TENANTS index (compile-asserted). +Offsets are FULL-ROW; subtract 32 for slab-relative. + +| # | Tenant | Kind × n | Width | Row range | Carries | +|---|---|---|---|---|---| +| 0 | Meta | U64 × 1 | 8 B | [32,40) | MetaWord (thinking/awareness/NARS/free-energy bits) | +| 1 | Qualia | U64 × 1 | 8 B | [40,48) | QualiaI4_16D — 16 signed-4-bit channels | +| 2 | MaterializedEdges | U64 × 4 | 32 B | [48,80) | 4 out-of-family CausalEdge64 | +| 3 | Fingerprint | U8 × 32 | 32 B | [80,112) | 32 B identity print (not the 16 Kbit plane) | +| 4 | HelixResidue | U8 × 6 | 6 B | [112,118) | 48-bit helix place (2× 24-bit equal-area hemisphere, Signed360) | +| 5 | TurbovecResidue | U8 × 16 | 16 B | [118,134) | PQ32x4 residue (16 B turbovec — NOT the 6 B canonical CAM-PQ) | +| 6 | Energy | F32 × 1 | 4 B | [134,138) | spatio-temporal accumulator | +| 7 | Plasticity | U32 × 1 | 4 B | [138,142) | persisted plasticity | +| 8 | EntityType | U16 × 1 | 2 B | [142,144) | OGIT class ordinal (1-based registry index) | +| 9 | Kanban | U64 × 1 | 8 B | [144,152) | `phase(u8) \| exec(u8) \| reserved(u16) \| cycle(u32)` (KanbanTenant::to/from_bytes, canonical_node.rs:1385-1409) | + +`ValueSchema::Full` uses 152 B of 480 — **328 B headroom, +RESERVE-DON'T-RECLAIM** (compile-asserted ≤ 480, canonical_node.rs:974). + +## §3 ValueSchema presets (canonical_node.rs:894-970) + +| Preset | Tenants | Use | +|---|---|---| +| Bootstrap = 0 (default) | none (FieldMask::EMPTY) | zero-fallback ladder | +| Cognitive = 1 | Meta, Qualia, Fingerprint, Energy, Plasticity, EntityType, Kanban (7) | thinking rows | +| Compressed = 2 | Fingerprint, HelixResidue, TurbovecResidue, EntityType (4) | baked/search rows (q2 bakes) | +| Full = 3 | all 10 | superset | + +## §4 The classid → tenant resolution (ReadMode registry) + +`classid_read_mode(classid) -> ReadMode { tail_variant, value_schema, +edge_codec }` via `BUILTIN_READ_MODES` (canonical_node.rs:1041-1227): + +- `TailVariant`: V1 `family(u24)·identity(u24)` (default) / V2 + `leaf·family·identity (3×u16)` (feature `guid-v2-tail`) / V3 + cascade-key `(part_of:is_a)` 8:8 tile (feature `guid-v3-tail`). +- OSINT/FMA/PROJECT/ERP = {V1, Cognitive|Compressed}; `*_V3` classids + (OSINT_V3/FMA_V3/CPIC_V3) = {V3, …}. `DEFAULT = {V1, Full, CoarseOnly}` + — documented TEMPORARY. +- Unmapped classids fall through to DEFAULT; legacy `_LEGACY` alias keys + keep pre-flip forms resolving forever (retirement = corpus-proof-gated, + W6). + +This registry IS the "classview selects the reading" mechanism at its +current maturity: today it selects tail + schema + codec; the full +64k-ClassView focus-lens (le-contract §3, E-V3-CLASSVIEW-FOCUS-LENS) +lands post-P4. + +## §5 The facet lane (Phase-2 target) + +`FacetCascade { facet_classid: u32, tiers: [FacetTier; 6] }` = the coded +4+12 atom (facet.rs:31-100, `size_of == 16` const-asserted). Byte shapes: +`CascadeShape::{G6D2, G4D3, G3D4}` = the L1–L4 / L5 / L6 readings; +`hi_chain()/lo_chain()` (facet.rs:207-223) = the L7/L8 2×48-bit lane +("separate lane … never dragged into ClassView shape selection"). +Phase 2 of `soa-value-tenant-migration-v2` re-reads HelixResidue + +canonical 6 B CAM-PQ as the ONE contained 16 B facet +`facet_classid(4) | helix-place(6) | cam-pq(6)` — a ClassView READING +over existing presets, no enum variant, no layout bump. + +## §6 In-RAM mirror: MailboxSoA columns (mailbox_soa.rs:58-207) + +Per-mailbox hot columns: `energy[f32]`, `plasticity_counter[u8]`, +`last_active_cycle[u32]`, `last_write_cycle[u32]`, `edges[CausalEdge64]`, +`qualia[QualiaI4_16D]`, `meta[MetaWord=u32]`, `entity_type[u16]`, +`temporal[u64]`, `expert[u16]`, `sigma[u8]`, heap planes +content/topic/angle (256×u64 each), + `phase: KanbanColumn` (owner-only). +Zero-copy per-column views via repr(transparent) reinterprets +(`edges_raw()`, `meta_raw()`). `DefaultMailboxSoA = MailboxSoA<1024>`. + +## §7 Seams every session must know (flagged, not resolved) + +1. **SoaEnvelope trait has NO production implementor** — MailboxSoA + implements `MailboxSoaView/MailboxSoaOwner` (soa_view.rs); NodeRow + reads via the VALUE_TENANTS table + hand accessors. Two parallel + column-geometry systems share ColumnDescriptor/ColumnKind but not the + trait. Wiring `mailbox_owner()` provenance into the PRODUCTION path = + INTEGRATION-PLAN W1; collapsing the two systems is an entropy + milestone (ENTROPY-MILESTONES.md). +2. **Width mismatches, persisted vs hot:** Meta 8 B (slab) vs 4 B + (MetaWord u32); Plasticity 4 B (slab U32) vs 1 B (saturating u8 + counter). No slab↔MailboxSoA parity test exists (only + MailboxSoA↔BindSpace, mailbox_soa.rs:1144). Any 1:1 sync needs an + explicit shim + parity test first (envelope-auditor gate). +3. **MailboxId ≠ NiblePath in code.** `MailboxId = u32` + (collapse_gate.rs:121); `NiblePath{path:u64, depth:u8}` (hhtl.rs:56). + The three-tier doc's "MailboxId IS the NiblePath" is DOC-ONLY — no + conversion, no shared trait. Needs an operator/architecture ruling + before any code assumes the identity. +4. **jc-pillar gate applies per lane** (le-contract §3b): a consumer + starting to read any tenant above owes an ICC/Spearman/Cronbach + certification run before its reading backs any downstream claim. + +Cross-ref: `le-contract.md`, `routing.md` §4, `consumer-map.md`, +board E-V3-TWO-LEVEL-LE-JC-GATE, `.claude/plans/soa-value-tenant-migration-v2.md`. diff --git a/CLAUDE.md b/CLAUDE.md index b2fa1eb32..fc72fc3b2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,6 +22,40 @@ workspace is local — prefer the local/fork source over the registry, always. - crates.io is permitted ONLY for crates that have no AdaWorldAPI fork / no local source. +## ★ V3 SUBSTRATE — NEW ENTRY POINT (2026-07-02): `.claude/v3/` + +**Any session touching SoA rows, tenants, mailbox ownership, kanban, +thinking templates, classids, or the DTO ladder starts at +`.claude/v3/README.md`** (or invokes the `/v3` skill — same bootload). +The V3 folder is the consolidated home for what is NEW since the +mailbox-kanban ruling + classid canon-high flip (both operator-ruled and +fleet-shipped 2026-07-02): + +- `.claude/v3/README.md` — orientation + doc map (start here) +- `.claude/v3/INTEGRATION-PLAN.md` — the W0–W6 wave plan +- `.claude/v3/COMPONENT-MAP.md` — every subsystem: reuse / repurpose / retire +- `.claude/v3/ENTROPY-MILESTONES.md` — the systematic N→1 collapse ledger +- `.claude/v3/MODULE-TABLE.md` — per-file census of core / contract / planner +- `.claude/v3/soa_layout/` — LE contract, tenant lanes, consumer map, routing +- `.claude/v3/knowledge/` — V3 doctrine docs (`READ BY:` headers) +- `.claude/v3/agents/BOOT.md` — the four V3 cards (`v3-mailbox-warden`, + `v3-envelope-auditor`, `v3-kanban-executor-engineer`, `v3-template-smith`) +- `.claude/v3/knowledge/sonnet-worker-guardrails.md` — MANDATORY in every + Sonnet worker brief (§1 preamble pasted verbatim; §2 vocabulary + disambiguation; §5 STOP+report triggers). No grindwork spawn without it. +- `/v3-audit` command — mechanical conformance greps before any commit + +Headline rulings the folder carries (canonical text on the board): +**no singleton CollapseGate** (one mailbox = one kanban board as tenant); +**SoaEnvelope LE ownership** (`mailbox_owner()`, write-on-behalf iron rule); +**compiled thinking templates** (elixir-template × StepMask, Rig as oracle); +**classid canon-high** with the `0x1000` V3-adoption monitor; +**PerturbationDto/Resonance split** (D-PERT-1). Sections of THIS file that +predate these rulings (e.g. CollapseGate wording below) are read through +`.claude/v3/knowledge/v3-substrate-primer.md` §6 "must not be reinvented". + +--- + > **Updated**: 2026-04-21 (categorical-algebraic inference click) > **Role**: The obligatory spine — query engine, codec stack, semantic transformer, and orchestration contract > **Status**: 22 crates, 7 in workspace, 15 excluded (standalone/DTO), Phases 1-2 DONE, Phases 6-7 DONE (grammar + governance), Phase 3 IN PROGRESS diff --git a/crates/lance-graph-contract/src/soa_envelope.rs b/crates/lance-graph-contract/src/soa_envelope.rs index e6a5ce5a9..a9b5479e1 100644 --- a/crates/lance-graph-contract/src/soa_envelope.rs +++ b/crates/lance-graph-contract/src/soa_envelope.rs @@ -147,6 +147,26 @@ pub enum EnvelopeError { /// the already-resident backing bytes and *what cycle stamp* the store carries. /// The read-only view here mirrors `MailboxSoaView` vs `MailboxSoaOwner`: /// mutation lives on the owner type, never on this trait. +/// +/// # Ownership inheritance — up and down (operator, 2026-07-02) +/// +/// The LE contract IS the ownership carrier, in both directions: +/// +/// - **Structurally (compile time):** every view this trait hands out +/// ([`as_le_bytes`](SoaEnvelope::as_le_bytes) / [`row_le`](SoaEnvelope::row_le) +/// / [`column_le`](SoaEnvelope::column_le)) is a `&self` borrow OF the +/// implementing owner — a view cannot outlive or alias the mailbox that +/// owns the backing store, and a batch-writer cast (`&mut` on the owner) +/// cannot begin while any view is live. Rust's borrow rules ARE the +/// inheritance; nothing is checked at runtime. +/// - **Nominally (provenance):** [`mailbox_owner`](SoaEnvelope::mailbox_owner) +/// stamps WHICH mailbox owns these bytes, so the ownership survives the +/// two places borrows cannot reach — DOWN into Lance (the tombstone +/// records whose mailbox wrote the packet) and UP to consumers (every +/// consuming crate writes ON BEHALF OF this id, never directly — the +/// fleet-wide write-on-behalf rule; a write cast naming a different +/// mailbox than the envelope's stamp is the delegation case the batch +/// writer's cache logic resolves at cast time). pub trait SoaEnvelope { /// Layout version this implementor's geometry conforms to. const LAYOUT_VERSION: u8 = ENVELOPE_LAYOUT_VERSION; @@ -166,6 +186,16 @@ pub trait SoaEnvelope { /// coherent "packet at cycle N". fn cycle(&self) -> u32; + /// The mailbox that OWNS this envelope's backing store — the nominal half + /// of the up/down ownership inheritance (see the trait docs). `0` is the + /// bootstrap/unowned stamp per the zero-fallback ladder (RESERVE, DON'T + /// RECLAIM: default = not consulted, never absent); a real mailbox + /// overrides with its [`MailboxId`](crate::collapse_gate::MailboxId). + /// Consumers write on behalf of THIS id, never directly. + fn mailbox_owner(&self) -> crate::collapse_gate::MailboxId { + 0 + } + /// The whole packet as contiguous LE bytes, zero-copy. Length MUST be /// `row_stride() * n_rows()`. fn as_le_bytes(&self) -> &[u8]; @@ -315,6 +345,38 @@ mod tests { } } + #[test] + fn mailbox_owner_defaults_to_bootstrap_and_is_overridable() { + // Zero-fallback ladder: the default stamp is 0 (bootstrap/unowned — + // reserved, never absent), so every existing implementor is already + // conformant; a real mailbox overrides with its id. + let e = two_col_envelope(1); + assert_eq!(e.mailbox_owner(), 0, "default = bootstrap/unowned"); + + struct Owned; + impl SoaEnvelope for Owned { + fn columns(&self) -> &[ColumnDescriptor] { + &[] + } + fn row_stride(&self) -> usize { + 0 + } + fn n_rows(&self) -> usize { + 0 + } + fn cycle(&self) -> u32 { + 0 + } + fn as_le_bytes(&self) -> &[u8] { + &[] + } + fn mailbox_owner(&self) -> crate::collapse_gate::MailboxId { + 42 + } + } + assert_eq!(Owned.mailbox_owner(), 42, "owner stamp inherits up/down"); + } + #[test] fn kind_widths() { assert_eq!(ColumnKind::U8.elem_bytes(), 1);