basin-IS-a-node: members/memberof navigation + GUID self-routing + field-perturbation probe

.claude/board/EPIPHANIES.md

@@ -1,3 +1,55 @@
+## 2026-06-19 — E-GUID-SELF-ROUTES-THE-BASIN-TREE — `memberof` needs no coarse-fingerprint table: the HHTL nibbles ALREADY IN the GUID (classid·HEEL·HIP·TWIG) are the basin-tree route; the parent's address = HHTL-tier truncation of the child's own GUID, so every ancestor's route key derives from one key by truncation, zero lookups for addresses
+
+**Status:** FINDING **[G]** for the truncation-is-route identity (pure key arithmetic; `NiblePath::parent`/`from_guid_prefix` already wired). Operator sharpening ("what about using the HHTL in the guid") — resolves the open cross-shard `memberof` question raised at `E-BASIN-IS-A-NODE` and corrects this session's own "hand the parent to a separate coarse-fingerprint table" framing. Sharpens `E-COARSE-QUANTIZER-IS-SCALE-FREE-ROUTER` and `E-TENANT-ANGLE-RANK-IS-CAM-PQ-ADC`.
+
+**The correction:** I had proposed resolving a cross-shard `memberof` by handing the parent to "the 1024-fingerprint coarse table." Wrong framing — there is no separate table to consult. **The HHTL is already in the GUID.** `classid·HEEL·HIP·TWIG` (key bytes 0..10) ARE the cascade tiers; the parent basin = **drop the deepest populated HHTL tier** (`NiblePath::parent`, equivalently `from_guid_prefix(guid).prefix(d−1)`). That truncated prefix **IS the route key** — `E-COARSE-QUANTIZER` already established the HHTL prefix is simultaneously the CLAM cluster key, the IVF cell, AND the shard key. So the "1024 coarse fingerprints" **are HHTL prefixes, not learned centroids**; routing is prefix arithmetic, never centroid distance.
+
+**The GUID is self-routing.** Every node's key contains, by successive HHTL truncation, the *route keys* of all its ancestors up to the root. Computing the entire `memberof` chain to the root needs **zero lookups for the addresses** — they're in the one key — only row-fetches to materialize the nodes. The two halves of cross-shard `memberof` separate cleanly:
+
+| sub-question | resolved by | cost |
+|---|---|---|
+| *which shard holds the parent?* | parent HHTL prefix = truncate the GUID → prefix router | key-only, zero decode, **no fingerprint table** |
+| *which row in that shard?* | path→row in that shard's View (today the scan; future a path→row index) | key-only |
+
+The local-scan `memberof` (#this-branch) is the **in-mailbox special case** of "route the parent prefix" where the prefix routes back to the same mailbox.
+
+**Wiring (this commit):** `memberof` returns `Option<BasinOf>` where `BasinOf::Local(row)` = parent materialized here, `BasinOf::Route(NiblePath)` = parent elsewhere addressed by its HHTL prefix (route it; never `None` for a node that HAS a parent — an unmaterialized parent is a *Route*, not an absence). `None` only at the top tier (a top basin has no parent). The parent prefix is the GUID's HHTL surfaced via `hhtl_path_at` (the View populates it through `from_guid_prefix`), so it is GUID-derived by construction. Cross-refs: `E-BASIN-IS-A-NODE` (the navigation), `E-COARSE-QUANTIZER-IS-SCALE-FREE-ROUTER` (HHTL prefix = shard key), `E-PANCAKES-IS-RADIX-IS-HHTL` (the keys ARE the tree), `hhtl::NiblePath::{parent, from_guid_prefix}`, canon node 512 B.
+
+---
+
+## 2026-06-19 — E-FAMILY-NODE-IS-META-AWARENESS — the family/basin node, being the parent one level up in the Morton/Walsh pyramid, structurally IS the coarse-band (low-pass / coarse-Walsh) summary of its members' field; so meta-awareness is not a column or service — it is what a family node already carries by sitting above its mailbox
+
+**Status:** FINDING **[G]** for the pyramid-parent = coarse-band identity; the "awareness / free-energy proxy" framing is inherited from `E-WHT-META-AWARENESS-AND-KRONECKER-LOOKUP` Claim 1 (graded there). Operator click ("the cool thing is the family node becomes meta awareness node") — the capstone that closes `E-BASIN-IS-A-NODE` into the active-inference loop.
+
+**The identity:** in a Morton/Walsh tile pyramid the **parent tile = low-pass downsample of its 4 children** = the **coarse Walsh band** (DC / low-sequency term = the average over the children). `E-BASIN-IS-A-NODE` made the basin the parent node in that pyramid; therefore the basin/family node, sitting **one pyramid level above** its members, **naturally carries the coarse Walsh coefficients of its members' field in its own 480 B value** — which is exactly `walsh_pyramid_energy`'s coarse fraction = the per-basin spectral-concentration / free-energy proxy from `E-WHT-META-AWARENESS` Claim 1.
+
+**The payoff:** meta-awareness is **NOT a new SoA column, trait, or service** (respects the AGI-as-glove four-column discipline) — it is **what a family node IS, structurally**, by virtue of being the parent in the tree. Read the family node → you have the basin's predictability/surprise summary **without scanning the 16K members**. The recursion lifts cleanly: each parent summarizes its subtree, so the **root node is the global meta-awareness**, and every interior basin-node is the meta-awareness of everything below it. This closes the active-inference loop at the structural level — high fine-sequency energy in a basin (surprise) is visible **at the parent alone**, so the gate/dispatch acts on one family node, not a sweep. Cross-refs: `E-BASIN-IS-A-NODE` (the parent IS the basin), `E-WHT-META-AWARENESS-AND-KRONECKER-LOOKUP` Claim 1 (pyramid energy = meta-awareness), `E-COARSE-QUANTIZER-IS-SCALE-FREE-ROUTER` (the basin-node = IVF coarse centroid = the same parent), `perturbation-sim::sketch::walsh_pyramid_energy`, canon node 512 B.
+
+---
+
+## 2026-06-19 — E-BASIN-IS-A-NODE — a basin IS a GUID-keyed Node owning a MailboxSoA of its members; the substrate is a tree of MailboxSoAs; distance is IMPLICIT as hop count (= the already-wired `node_distance(PrefixDepth)` tree-hop), and the 4-ary basin fan-out IS the Morton tile pyramid, so the mailbox distribution is a perturbation-learnable field
+
+**Status:** the *distance=hop=PrefixDepth* identity is **FINDING [G]** (already wired, #544); the *basin-IS-a-node SoA-ownership recursion* is **CONJECTURE** (structural commitment, deserves a 5+3 council before heavy wiring); the *Morton-pyramid ⇒ field-perturbation-learning* deepening is **[G]** for the bit-interleave identity, **[H]** for "distribution modeled via pyramid perturbation," **CONJECTURE** for "field perturbation learning." Operator synthesis ("a basin is a node would be super clean … the distance is implicit with hopcount … directly feed in the L1-L4 propagation in your electricity-outage perturbation HHTL" + "4x4 overlaps directly with the morton tile pyramid … distribution between mailboxes modeled via pyramid perturbation → field perturbation learning"). Resolves the stuck out-family-slot thread.
+
+**The recursion (basin-IS-a-node):** drop the distinction between "a basin" and "a node." Each **basin is itself a GUID-keyed `Node`** whose 480 B value owns (or points at) a `MailboxSoA` of its member nodes; its 16 B `EdgeBlock` 12-in-family / 4-out-of-family slots point at **sibling basin-nodes**. So `1 → 4 basins`, each basin `1 → 4 nodes` = **16 reachable in 2 hops** (expandable: 4ᵏ in k hops). The substrate stops being "a mailbox + an edge table" and becomes a **tree of MailboxSoAs** — which is exactly `E-PANCAKES-IS-RADIX-IS-HHTL` made physical: the radix-trie subtree IS the basin, the basin IS a node, the node owns the next-level mailbox.
+
+**Distance becomes implicit (the load-bearing payoff):** with basins as tree nodes, you don't *compute* a distance — you **count hops**. And the hop count is **already the wired metric**: `node_distance(PrefixDepth)` = `(depth_a − cpd) + (depth_b − cpd)` over `NiblePath::common_prefix_depth` (#544) — the radix tree-hop, a genuine metric (d(x,x)=0, symmetric, tree triangle inequality). Basin-tree walk hop = PrefixDepth tree-hop. No new distance function; the GUID-key arithmetic already gives it, **zero value decode**.
+
+**Out-family resolution (subsumes the 3 options):** the operator's three out-family-slot options collapse —
+- **Options 1+2** (OGAR/OGIT-defined families inherited via `classid → ClassView` + adapter-supplied basin passthru) resolve **which sibling basin-node** an out-family slot points to — `ClassView` inheritance gives the passthru properties for free.
+- **Option 3** (4× global edges) is subsumed: a "global" edge is just a **basin-tree walk** (ref-escape up/over/down the tree), NOT a 16-byte-block widening. The key stays 512 B; reach grows by hops, never by field-widening — consistent with `RESERVE, DON'T RECLAIM` and the OGAR "depth beyond native levels = the hierarchy's job (registry resolve + ref-escape)."
+
+**The 4×4 ⇒ Morton tile pyramid ⇒ perturbation-learnable field (the deepening):**
+- **[G]** Each HHTL tier (4 nibbles = 16 bit) is read as a **256×256 centroid tile** with x/y nibble-interleaved (OGAR canon) — that interleave **IS Morton/Z-order**. The 4-ary basin fan-out (1→4, fan-out 4 per level) is **quadtree subdivision** = one Morton level (2 bits = 4 quadrants); two levels = **4×4 = 16 tiles**. So the basin-tree and the Morton tile pyramid are the **same subdivision**, not an analogy.
+- **[H]** Therefore **distributing nodes across mailboxes = a Morton tile-pyramid subdivision**, and `perturbation-sim`'s pyramid (`walsh_pyramid_energy` dyadic levels; the `simulate_outage` L1-L4 cascade) **models the distribution directly**: cascade round k = nodes at hop-distance k from the seed; Weyl bounds the *magnitude* per round, hop-count bounds the *reach*. The electricity-outage cascade IS hop-count propagation over the basin-tree.
+- **CONJECTURE → MEASURED (probe green 2026-06-19).** Because the distribution IS a pyramid field, you can run **field perturbation ON the distribution to LEARN it** — inject a delta at a seed mailbox, watch the L1-L4 cascade, and adjust placement (which basin a node lives in) so the cascade matches a target. "Field perturbation learning" = learning the node→basin assignment by perturbation, with the Morton pyramid as the field. **Probe `perturbation-sim/examples/basin_placement_learning.rs`:** on a planted-community grid (4×8 nodes, 76 similar pairs), the **perturbation-derived placement** (`hhtl_keys` = recursive Cheeger/Fiedler bisection = the dominant Laplacian perturbation eigenmode at each tier) gives **mean tree-hop 1.00 over similar pairs vs 4.13 random — 75.8 % tighter** (gate ≥ 15 %, asserts). So the mechanism is **measured FINDING [G]**: the spectral perturbation finds a basin placement that clusters similar items at far lower `node_distance(PrefixDepth)` hop than random — the substrate CAN represent similarity as hop-distance and the field perturbation locates it. The *full iterative learner* (inject delta → minimise cascade surprise → re-place online) stays future work; this proves its precondition.
+
+**Three threads are ONE structure:** basin-tree (1→4→16…) = Morton tile pyramid (quadtree subdivision) = `perturbation-sim` L1-L4 cascade levels = the field perturbation-learning runs over. Distance = hop count = pyramid level = cascade round — **one number, three readings**.
+
+**Wiring (gated on the 5+3 council for the SoA-ownership commitment):** add `row_for_member_index` to the contract (basin-node → member row); wire the EdgeBlock out-family slot → sibling basin-node via ClassView (Options 1+2); reclassify **CHAODA as a unary `node_anomaly`** (point↔manifold LFD), NOT a pairwise `DistanceMeans` — it never belonged in the hop-distance dispatch. The `node_distance(PrefixDepth)` tree-hop is already the basin-tree distance; no new means needed for the structural tier. Cross-refs: `E-PANCAKES-IS-RADIX-IS-HHTL` (radix subtree = basin), `E-COARSE-QUANTIZER-IS-SCALE-FREE-ROUTER` (basin-node = IVF coarse centroid = parent SoA), `E-CLAM-IS-THE-MANIFOLD-ENGINE` (CHAODA = unary anomaly), `E-WHT-META-AWARENESS-AND-KRONECKER-LOOKUP` (pyramid energy = the field summary), `E-GUID-IS-THE-GRAPH`, canon node 512 B, `perturbation-sim::{sketch::walsh_pyramid_energy, chaoda}`, OGAR "256×256 centroid tile" + "perturbation = (exponent, location, phase, magnitude)".
+
+---
+
 ## 2026-06-18 — E-COARSE-QUANTIZER-IS-SCALE-FREE-ROUTER — the 1024 HHTL coarse fingerprints route a query in-RAM (IVF probe) AND cross-server (shard route) with one lookup; the GUID-key substrate shards on the prefix, value-slab compresses in Lance, durability via SurrealDB-on-TiKV/Raft
 
 **Status:** FINDING (deployment-tier; operator capacity+distribution synthesis). Grounded in `E-TENANT-ANGLE-RANK-IS-CAM-PQ-ADC` (IVF coarse ≡ HHTL prefix), `E-GUID-IS-THE-GRAPH` (key = address), canon node = 512 B. Theorem-checker on the arithmetic.

.claude/board/LATEST_STATE.md

@@ -10,6 +10,8 @@
 
 ---
 
+> **2026-06-19 — IN PR (branch `claude/edge-distance-basin-node-epiphany`)** — **basin-IS-a-node: the substrate is a virtual tree of MailboxSoAs, navigated by pure key arithmetic.** New `graph::mailbox_scan::{members, memberof, BasinOf}` — one-to-many (`members` = direct children one HHTL tier down) / many-to-one (`memberof` = parent via `NiblePath::parent`, returns `BasinOf::Local(row)` or `BasinOf::Route(NiblePath)` when the parent lives in another shard — the HHTL prefix IS the route key, **no coarse-fingerprint table**; `None` only at the top tier). Realizes `E-BASIN-IS-A-NODE` with **no ownership restructure** — the tree is the radix trie of the keys, the SoA stays flat, the zero-copy/Lance-tombstone invariant is untouched; all navigation is **zero value decode** (F2-guarded). 16/16 mailbox_scan tests, clippy clean. **Probe (perturbation-sim `basin_placement_learning.rs`): field-perturbation placement learns the basin tree — green, mean tree-hop 1.00 vs 4.13 random (75.8 % tighter)**, promoting the one CONJECTURE in `E-BASIN-IS-A-NODE` to measured FINDING [G]. **Three epiphanies this arc:** `E-BASIN-IS-A-NODE` (basin=node; distance=hop=`node_distance(PrefixDepth)`; 4-ary fan-out = Morton tile pyramid = perturbation-learnable field), `E-FAMILY-NODE-IS-META-AWARENESS` (the parent node IS the coarse Walsh band of its subtree — meta-awareness is structural, not a column), `E-GUID-SELF-ROUTES-THE-BASIN-TREE` (HHTL-tier truncation of the GUID = every ancestor's route key; the GUID self-routes). **Capstone:** one 512 B key, read five ways — representation / ontology / compute (Morton pyramid) / learning / meta-awareness — four of the five are key-resident zero-decode. Builds on #544/#545/#548 (mailbox_scan facets) + `E-COARSE-QUANTIZER-IS-SCALE-FREE-ROUTER`.
+>
 > **2026-06-18 — branch work** — **OGAR → lance-graph-ontology wiring closed.** `OntologyRegistry::class_id_for_guid(&NodeGuid) -> Option<ClassId>` composes the canon GUID→NiblePath fold (`contract::hhtl::NiblePath::from_guid_prefix`) with the registry's `NiblePath ↔ entity_type` bijection — the single missing join an audit this session surfaced (both halves were built with **ZERO callers**). A node carrying a classid now resolves its ontology class → `RegistryClassView` (fields/labels/template/DOLCE). Round-trip test pins the `classid_lo ↔ entity_type` consistency the audit flagged; zero-fallback (unbound → None) + lossy-fold refusal (high classid u16 → None). Completes the third "classid → X" axis reachable from a GUID (read-mode ✅ ocr.rs, methods ✅ unicharset keystone, ontology-shape ✅ now); aligns with `E-ODOO-CORE-FIRST-STRUCTURAL` (Core-side resolution, no new predicate/type). 16 ontology tests green; `registry.rs` clippy-clean + fmt clean. EPIPHANIES `E-OGAR-ONTOLOGY-WIRED-1`. Pre-existing `lance-graph-ontology` clippy debt noted (`TD-ONTOLOGY-LINT`).
 >
 > **2026-06-17 — IN PR (branch `claude/odoo-spo-fk-target-deep-reads`)** — Odoo SPO corpus enrichment (odoo-rs `UPSTREAM_WISHLIST` P1 + coupled P0). The corpus `crates/lance-graph/src/graph/spo/odoo_ontology.spo.ndjson` now carries **two new predicate families** (was 7 predicates: `depends_on / emitted_by / has_function / raises / rdf:type / reads_field / traverses_relation`): **`target`** (618) + **`inverse_name`** (102) — the relational comodel/inverse keyed by the relation IRI, ruff#18 sibling-triple shape `(odoo:account_move.line_ids, target, "account.move.line")`; and **+736 deep `reads_field`** (so `reads_field` 2 095 → 2 831) — each `@api.depends('rel.leaf', …)` resolved through the new target map and lifted onto the field's emitting method as a transitive read. Corpus 22 245 → **23 701** triples. New stdlib-only generator `tools/odoo-blueprint-extractor/odoo_blueprint_extractor/spo_enrich.py` (+14 unit tests) reads `/home/user/odoo/addons` (the same source the ORM extractor parses) to build the `(model, field) → (comodel, inverse)` map; additive, deterministic, idempotent. `odoo_ontology.rs` doc + tests updated (count 23 701, histogram incl. new predicates, 2 new enrichment tests); `action_emitter`/`spo` unaffected (function count 3 328 unchanged). **Cross-repo finding (verified, not faked):** the deep reads make the cross-model recompute-ordering edge `account_move_line._compute_amount_residual → account_move._compute_amount` *visible* to `od_ontology::RecomputeDag` (baseline: 0 cross-model compute edges → enriched: 27), delivering the wishlist's P0 ask — but the audit's MISSED-1 is a unidirectional *ordering edge*, NOT a cycle, so odoo-rs's `slice_2_compute_subset_no_cross_model_cycle` no-cycle assertion legitimately still holds (the "circularity" is semantic, not a `reads_field`↔`emitted_by` back-edge). The corpus's original generator (`emit_ontology2.py`/`methods.parquet`) is absent from the tree — only its output is committed; enrichment runs at the correct additive stage over the shipped corpus + present source. See `EPIPHANIES.md` E-ODOO-FK-DEEP-READS.