diff --git a/.claude/knowledge/ast-as-partof-isa-address.md b/.claude/knowledge/ast-as-partof-isa-address.md new file mode 100644 index 00000000..e88d5edd --- /dev/null +++ b/.claude/knowledge/ast-as-partof-isa-address.md @@ -0,0 +1,176 @@ +# AST-as-(part_of:is_a)-address — sinking compiled semantics into the GUID + +> **READ BY:** integration-lead, truth-architect, core-first-architect, +> family-codec-smith, baton-handoff-auditor +> **Status:** CONJECTURE (design; the **carrier is now SHIPPED** — see V3 +> alignment below — only the rank-minter is unbuilt/unmeasured). +> **Cross-ref:** `crates/lance-graph-contract/src/facet.rs` (the **SHIPPED** +> `FacetCascade` substrate, #613/#614), `canonical_node.rs` +> (`TailVariant::V3` / `mint_for` / `CLASSID_OSINT_V3`, #615), +> `guid-canon-and-prefix-routing.md` (the GUID canon), +> `core-first-transcode-doctrine.md` (harvest → ClassView → codegen), +> OGAR `SURREAL-AST-AS-ADAPTER.md` + `SURREAL-AST-TRAP-PREFLIGHT.md` +> (DDL is an adapter, never the spine), `encoding-ecosystem.md`. + +> **V3 alignment (2026-06-26).** This doc was first drafted without awareness that +> the V3 substrate **already shipped** (#613/#614 `FacetCascade`, #615 `mint_for`). +> Three corrections, applied throughout: +> 1. **The slot-count "open gate" is CLOSED.** `facet.rs::FacetCascade` = +> `facet_classid(4) | 6×(8:8) = 16 B` — **6 tiers** (`HEEL·HIP·TWIG·LEAF·family· +> identity`), `const _`-asserted. That IS the full-key 6-pair / 12-slot answer; +> the *key* carries only the 4-tier routing prefix +> (`NiblePath::from_guid_prefix_v3`), the complete 6-pair address lives in the +> `FacetCascade` **value facet**. Nothing left to ratify. +> 2. **The carrier is NOT missing.** `FacetCascade` is **content-blind** and +> already lists `(part_of:is_a)` as a consumer projection: `hi_chain()` = +> part_of, `lo_chain()` = is_a, with `hi_distance`/`lo_distance` the two +> orthogonal prefix metrics. AST-as-(part_of:is_a) is one reading of this shipped +> substrate; the only genuinely-new brick is the deterministic **rank-minter**. +> 3. **The classid row is `0x1000_0700`-shaped** (shipped `CLASSID_OSINT_V3`: V3 +> marker in the HIGH u16, domain routed on the LOW u16). Its `(part_of:is_a)` +> *ordering* is **pending the operator's Canon:Custom correction** (canon→high) — +> flagged on the row, not settled here. + +## The claim + +The structural AST of a transcode *source* (C#/Python/C++/Ruby) can be stored +**as the (part_of:is_a) GUID address itself**, in the lance-graph SoA — not as a +SurrealQL AST/DDL, and not as a raw syntax tree. The GUID *is* the AST node's +structural identity; the value columns + `CausalEdge64` edges hold the behavior. +This closes the loop from the `ruff_*_spo` harvest to the OGAR Core, and makes +an LSP (`ruff-lsp`) the natural read/serve surface. + +``` +source (C#/…) ──ruff_*_spo harvest──► SPO triples ──► AR-shaped Model / ClassView + │ rank-mint (NEW brick) + ▼ + (part_of:is_a) GUID ──► lance-graph SoA + │ serve + ▼ + ruff-lsp ──► editor +``` + +## Why this is the convergence, not a detour + +1. **An AST has exactly two structural relations, and they ARE the two tile axes.** + - **is_a** (taxonomy / typing): `Patient is_a DbBase`, `kdnr is_a Property`, + `Save is_a Function` ← harvest `inherits_from` + `rdf:type` ← the **is_a + byte (TISSUE / what)** of a tier. + - **part_of** (mereology / membership): `kdnr part_of Patient`, + `Patient part_of MedCare.Models` ← harvest `has_field` / `has_function` + (inverted) ← the **part_of byte (PLACE / where)** of a tier. + +2. **SurrealQL is an adapter, not the spine.** Storing the AST as + `DEFINE TABLE`/`DEFINE FIELD` DDL is the "negative-beauty hijack" + `SURREAL-AST-AS-ADAPTER.md` §0 rejects — DDL can't carry the behavioral arm + and it makes the schema the spine. The (part_of:is_a) GUID + lance SoA is the + spine; SurrealQL is at most a query projection over it. + +## The class wrapper + the rails-shaped (declarative) AST + +Two requirements, one insight: + +- **Class wrapper** = the OGAR `ClassView` / the `ruff_spo_triplet::Model` IR. + The GUID is its *address*; the ClassView is the resolved declaration set the + address points at ("the key prerenders nodes, zero value decode"). +- **Rails-shaped, not syntax-tree.** You do NOT sink a raw `CSharpSyntaxTree` + (imperative, positional — wrong shape). You sink the **declarative class-body + shape** — exactly what `ruff_ruby_spo` harvests as the ActiveRecord shape: a + class flattened to a *bag of typed declarations*, every one of which is a + part_of or is_a edge. That is why `ruff_spo_triplet`'s IR is a `Model` with + sibling declaration `Vec<…>` fields rather than a syntax tree — it is the + language-agnostic, already-(part_of:is_a)-shaped class wrapper that every + frontend (Python/C++/Ruby/C#) fills. + +## The GUID decomposition — 6×(part_of:is_a) (RESOLVED — the shipped `FacetCascade`) + +Operator framing (session): the GUID carries **6 (part_of:is_a) pairs = 12 +slots**, read across the *whole* key, giving six levels of (composition × type) +resolution — enough to encode a deep AST node's full structural path, each level +capturing both where it sits (part_of) and what it is (is_a): + +| GUID region | proposed (part_of : is_a) reading | +| --- | --- | +| `classid` (4B) | **shipped** as hi u16 : lo u16 = custom/render : canon/concept (`CLASSID_OSINT_V3 = 0x1000_0700` — V3 marker hi, domain routed on lo). **OPEN (Canon:Custom):** the operator's correction flips this to canon(hi):custom(lo) so the prefix sorts by shared concept, not render skin — so the classid `(part_of:is_a)` half-order is **not settled** (orthogonal to the per-tier minting). | +| `HEEL` / `HIP` / `TWIG` (2B each) | namespace·root-type / class·base / member-slot·member-kind | +| `basin·leaf` + `identity` (6B) | basin `po_rank` : `ia_rank` (OGAR `family = (po_rank3<<8)|ia_rank3`) | + +**Reconciliation — RESOLVED by shipped code** (was framed as "the gate before any +packer"). `facet.rs::FacetCascade` settles it: `facet_classid(4) | 6×(8:8)` = +**6 tiers** (`HEEL·HIP·TWIG·LEAF·family·identity`), i.e. the **full-key 6-pair / +12-slot** reading — *not* path-only. The "path = 6 bytes = CAM-PQ 6×256 = 3 tiers" +canon describes the **key routing prefix** (`NiblePath::from_guid_prefix_v3`, +4-tier); the *complete* 6-pair address is the 16-byte `FacetCascade` **value +facet** (it does not fit the 64-bit key — facet.rs says so explicitly). So +"path-only vs full-key" is answered **both**: the key carries the routing prefix, +the FacetCascade carries the full address. The rank-minter therefore targets the +6 `FacetCascade` tiers (`tier.hi` = part_of chain, `tier.lo` = is_a chain) — no +allocation is left to ratify, and the only open ordering is the classid half-order +above (Canon:Custom), which is orthogonal to per-tier packing. + +## The missing brick — a deterministic part_of/is_a rank-minter + +Between the SPO harvest and the GUID is the **one** genuinely-new component — the +carrier (`FacetCascade`) is **already shipped**, so this is the only brick to +build: a pure-Rust, dependency-free rank-minter. Given the corpus's part_of edges ++ is_a edges, assign each node its `(po_rank, ia_rank)` at each tier and write +them into the 6 `FacetCascade` tiers (`tier.hi = po_rank`, `tier.lo = ia_rank`); +`FacetCascade::to_bytes()` is then the 16-byte facet and `hi_chain()`/`lo_chain()` +the two prefix-routable hierarchies — no new layout, no new type. + +- **part_of tree** (namespace → class → member): deterministic sibling/ + topological rank. +- **is_a lattice** (class → base, member → kind): deterministic type rank. +- For a **finite, known** AST this is deterministic assignment — **not** learned + PQ centroids — so it is exact and roundtrip-lossless (no quantization error on + a known class graph). Iron-rule clean per **I-VSA-IDENTITIES**: it encodes + *identity positions* (which class, which base, which slot), never bundles + content. + +## The boundary — skeleton in the address, muscle in the edges + +The (part_of:is_a) address holds the **THINK arm**: the class/member/type graph, +the ClassView method-resolution manifest — precisely the harvest's *structural* +predicates. It does **not** hold the **DO arm**: method bodies, control flow, the +transcode logic. Those are not part_of/is_a relations; they live in +`ActionDef`/`KausalSpec` and the harvest's behavioral edges (`reads_field`, +`raises`, `traverses_relation`) as `CausalEdge64`, **keyed by** the GUID, not +encoded in it. (Lance compresses the value/edges arbitrarily; the key stays +transparent — compression never costs addressability.) + +## The serve surface — ruff-lsp (and it's language-agnostic) + +`AdaWorldAPI/ruff-lsp` today is a vanilla fork of the deprecated Python +ruff-lsp (no SPO/lance wiring) — a clean slate for the *read* end. The core LSP +operations **are** part_of/is_a queries: + +| LSP request | graph query | axis | +| --- | --- | --- | +| `textDocument/typeHierarchy` | walk the is_a lattice | **is_a** | +| `textDocument/definition` | resolve symbol → ClassView node (GUID) | address lookup | +| `references` / `callHierarchy` | walk part_of / behavioral edges | **part_of** + edges | +| `documentSymbol` / `workspace/symbol` | the class→member part_of tree | **part_of** | + +Backed by the (part_of:is_a) lance store, an LSP is no longer a Python-only +linter surface — it is a **language-agnostic semantic-navigation surface** over +whatever frontend filled the graph (Python / C++ / **C#-MedCare** / Ruby), +because at that layer it is all the same `Model`/ClassView keyed by GUIDs. + +## Next bricks (ordered; each gated on the prior) + +1. **Slot allocation — LOCKED (shipped).** The 6-pair / 12-slot layout is the + shipped `FacetCascade` (#613/#614); no ratification needed. The ONLY remaining + ordering decision is the classid `(part_of:is_a)` half-order (the operator's + Canon:Custom correction) — orthogonal to per-tier ranking, so it does **not** + block brick 2. +2. **Build the deterministic rank-minter** (`ruff_spo_address`, pure std): SPO + graph → `(po_rank, ia_rank)` per level → packed slots. Verifiable in + isolation. +3. **Probe on MedCare**: `ruff_csharp_spo` harvest → mint → lance SoA → + `typeHierarchy`/`definition` query → diff the class graph against the C# + original, with `MedCareV2` as the parity oracle. + +The per-tier layout is **locked** (the shipped `FacetCascade`), so brick 2 (the +rank-minter) can proceed now — it writes into existing tiers, inventing no type. +Only the classid half-order (Canon:Custom) remains a decision, and it is +orthogonal to per-tier packing, so it does not gate the minter.