feat(graph+contract): CLAM containment + CAKES nearest over HHTL prefixes (Inc 0, the manifold facet)

panCAKES == radix trie == HHTL (E-PANCAKES-IS-RADIX-IS-HHTL): the CLAM cluster
tree IS the radix trie of the classid·HEEL·HIP·TWIG nibble paths already in the
keys, so the structural neighborhood is pure prefix arithmetic, zero value decode.

- NiblePath::common_prefix_depth (contract) — the radix-trie nearest-neighbor
  measure; longest-common-prefix = CAKES attraction. +1 unit test.
- MailboxSoaView::hhtl_path_at (contract) — per-row HHTL NiblePath, deferred-
  binding default None (canon NodeRow already carries key(16); the override
  exposes what's there).
- graph::mailbox_scan::clam_contained (is_ancestor_of = the radix subtree =
  CLAM cluster) + cakes_nearest (common_prefix_depth ranking, k-NN). Both
  key-only, zero value decode.
- Tests: containment = radix subtree (rows 0,1,2 under 1·2; leaf narrows to 0);
  CAKES ranks by shared depth [(0,3),(1,2),(2,2)]; deferred-None yields nothing
  (coarser-facet fallback); F2 zero-value-decode extended to CLAM/CAKES (the
  GuardedSoa value columns still panic-guarded). 7/7 mailbox_scan + 21/21 hhtl
  green, clippy clean.

This is the first dispatch-table facet beyond the classid node-match: proximity/
neighborhood resolves on the key (CLAM/CAKES), free, per E-CLAM-IS-THE-MANIFOLD-
ENGINE. Edge-deref (EdgeBlock) + helix exact-location (value decode) are the
next tiers.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CcpLeEC3XK8Eye53GKBVvi

Author: claude

.claude/board/EPIPHANIES.md

@@ -1,3 +1,23 @@
+## 2026-06-18 — E-PANCAKES-IS-RADIX-IS-HHTL — panCAKES ≡ radix trie ≡ HHTL: the CLAM cluster tree is NOT a separate structure, it IS the radix trie of the HHTL prefixes already in the keys; so CLAM/CAKES = prefix arithmetic on the GUID, zero value decode
+
+**Status:** FINDING (operator-stated identity; wired this commit). The unification that makes the manifold-geometry facet (`E-CLAM-IS-THE-MANIFOLD-ENGINE`) *free*: there is no CLAM tree to build and store — the tree IS the radix trie of the `classid·HEEL·HIP·TWIG` nibble paths that already live in every GUID key.
+
+**The three are one structure seen three ways:**
+- **HHTL** = the cascade tiers in the key (`NiblePath` over `classid·HEEL·HIP·TWIG`).
+- **radix trie** = prefix tree; routing = bit-shift on the nibble path, not hash.
+- **panCAKES** = the compressed CLAM tree — and a CLAM cluster IS a radix-trie subtree (shared prefix = same cluster); the cluster structure IS the codec.
+
+**Operational consequence (the wiring):** the CLAM/CAKES operations reduce to pure prefix arithmetic on the key, **zero value decode** —
+- **CLAM containment** (which cluster / subtree) = `NiblePath::is_ancestor_of` — the radix subtree under the query prefix.
+- **CAKES nearest** (ranked similar) = `NiblePath::common_prefix_depth` (added this commit) — longest-common-prefix ranking IS the entropy-scaling NN over the cluster tree; deeper shared prefix ⇒ same deeper cluster ⇒ nearer.
+- **panCAKES compression** = the trie itself (shared prefixes are the dedup).
+
+No separate index, no scent-vector tree materialization for the *structural* neighborhood — the keys are the tree. (CAKES over *content scent vectors* in `ndarray::hpc::clam` remains the metric-space path for non-prefix similarity; this identity covers the HHTL-prefix structural neighborhood, the free tier.)
+
+**Wired:** `NiblePath::common_prefix_depth`; `MailboxSoaView::hhtl_path_at` (deferred-binding, default `None`); `graph::mailbox_scan::{clam_contained, cakes_nearest}` over the View — all key-only, F2 zero-value-decode-guarded (#544). Cross-refs: `E-CLAM-IS-THE-MANIFOLD-ENGINE`, `E-ADJACENCY-IS-KEY-AND-EDGECODEC`, `E-GUID-IS-THE-GRAPH`, `hhtl::NiblePath`, `ndarray::hpc::clam` (CAKES/panCAKES/CHAODA).
+
+---
+
 ## 2026-06-18 — E-CLAM-IS-THE-MANIFOLD-ENGINE — the CLAM facet is not a containment check; it is the CAKES+CHAODA+LFD ensemble (ndarray `clam.rs`): containment + ranked-NN + anomaly + compression, one tree, one geometric measure
 
 **Status:** FINDING (operator-stated, grounded in `ndarray/src/hpc/clam.rs` — CAKES arXiv:2309.05491 Partition Alg 1 / ρ-NN Alg 4 / DFS-sieve Alg 6, panCAKES Alg 2, **CHAODA Phase 4 `anomaly_scores` from the LFD distribution**; + `lance-graph/crates/perturbation-sim/src/chaoda.rs` CHAODA-lite which names ndarray's `ClamTree` as the production path). Enriches `E-ADJACENCY-IS-KEY-AND-EDGECODEC`: the "HHTL/CLAM neighborhood" facet is a whole geometry engine, not `is_ancestor_of`.

crates/lance-graph-contract/src/hhtl.rs

@@ -238,6 +238,35 @@ impl NiblePath {
         })
     }
 
+    /// The depth of the **longest common prefix** with `other` — the radix-trie
+    /// nearest-neighbor measure. Larger ⇒ the two paths share more cascade tiers
+    /// ⇒ they sit in the same deeper CLAM cluster ⇒ they are nearer.
+    ///
+    /// This is the operational form of `panCAKES ≡ radix trie ≡ HHTL`
+    /// (`E-PANCAKES-IS-RADIX-IS-HHTL`): CAKES nearest-neighbor over the cluster
+    /// tree is *longest-common-prefix ranking* over the HHTL nibble paths — no
+    /// separate tree to build, the keys ARE the tree. Pure prefix arithmetic on
+    /// the key; never touches the value slab.
+    #[must_use]
+    pub const fn common_prefix_depth(self, other: Self) -> u8 {
+        let max = if self.depth < other.depth {
+            self.depth
+        } else {
+            other.depth
+        };
+        let mut d = 0u8;
+        // Walk depth-by-depth while the aligned prefixes agree. `prefix(d)` is
+        // `Some` for every d ≤ depth, so the unwraps below cannot fail.
+        while d < max {
+            let next = d + 1;
+            match (self.prefix(next), other.prefix(next)) {
+                (Some(a), Some(b)) if a.path == b.path && a.depth == b.depth => d = next,
+                _ => break,
+            }
+        }
+        d
+    }
+
     /// Lower a [`NodeGuid`](crate::canonical_node::NodeGuid) prefix to a 16-nibble
     /// `NiblePath`, the routing-path counterpart of the GUID's
     /// `classid · HEEL · HIP · TWIG` cascade (identity-architecture v1 §3).
@@ -456,6 +485,24 @@ mod tests {
         );
     }
 
+    #[test]
+    fn common_prefix_depth_is_the_radix_nn_measure() {
+        let a = NiblePath::root(1).child(2).child(3);
+        let b = NiblePath::root(1).child(2).child(4);
+        let c = NiblePath::root(1).child(2);
+        let d = NiblePath::root(9);
+        assert_eq!(a.common_prefix_depth(a), 3, "self ⇒ full depth");
+        assert_eq!(a.common_prefix_depth(b), 2, "1·2 shared, leaf differs");
+        assert_eq!(a.common_prefix_depth(c), 2, "ancestor ⇒ min depth");
+        assert_eq!(a.common_prefix_depth(d), 0, "different basin ⇒ 0");
+        assert_eq!(
+            a.common_prefix_depth(b),
+            b.common_prefix_depth(a),
+            "symmetric"
+        );
+        assert_eq!(NiblePath::EMPTY.common_prefix_depth(a), 0);
+    }
+
     #[test]
     fn is_ancestor_of_is_cheap_prefix_reachability() {
         let mammal = NiblePath::root(0x0).child(0x3); // Endurant → …mammal

crates/lance-graph-contract/src/soa_view.rs

@@ -88,6 +88,24 @@ pub trait MailboxSoaView {
         None
     }
 
+    /// The HHTL routing path ([`NiblePath`](crate::hhtl::NiblePath)) of `row`'s
+    /// GUID key — the `classid·HEEL·HIP·TWIG` cascade lowered to a nibble path.
+    /// This is the **radix-trie / CLAM cluster address** of the node
+    /// (`panCAKES ≡ radix trie ≡ HHTL`): containment = `is_ancestor_of`,
+    /// CAKES nearest = `common_prefix_depth`, both pure key arithmetic, **zero
+    /// value decode**.
+    ///
+    /// **Default = `None` (zero-fallback, deferred binding)** — same discipline as
+    /// [`row_for_local_key`](MailboxSoaView::row_for_local_key): a view that has
+    /// not materialized a per-row key/HHTL column returns `None`, and a CLAM/CAKES
+    /// scan over it yields nothing (the consumer falls back to a coarser facet).
+    /// An owner that carries the GUID key per row overrides this (the canon
+    /// `NodeRow` already holds `key(16)`, so the override exposes what is there).
+    #[inline]
+    fn hhtl_path_at(&self, _row: usize) -> Option<crate::hhtl::NiblePath> {
+        None
+    }
+
     // NOTE (follow-up): the qualia column (`QualiaI4_16D`) accessor is intentionally omitted —
     // add `fn qualia(&self) -> &[crate::qualia::QualiaI4_16D]` when the first consumer
     // (planner strategy selection) needs it; keep the read surface minimal until then.

crates/lance-graph/src/graph/mailbox_scan.rs

@@ -34,6 +34,7 @@
 //! lookup (via [`MailboxSoaView::row_for_local_key`]); edge dispatch lands once
 //! the representation boundary is resolved.
 
+use lance_graph_contract::hhtl::NiblePath;
 use lance_graph_contract::soa_view::MailboxSoaView;
 
 use crate::graph::graph_router::Backend;
@@ -87,6 +88,55 @@ pub fn match_node_by_local_key<V: MailboxSoaView>(view: &V, local_key: u64) -> O
     })
 }
 
+/// **CLAM containment** — the rows in `query`'s subtree: every row whose HHTL
+/// path is a descendant-or-equal of `query` (`query.is_ancestor_of(path)`).
+///
+/// This is the `panCAKES ≡ radix trie ≡ HHTL` neighborhood (`E-CLAM-IS-THE-MANIFOLD-ENGINE`
+/// / `E-PANCAKES-IS-RADIX-IS-HHTL`): the CLAM cluster is the radix-trie subtree
+/// under the query prefix. Pure key arithmetic — **zero value decode**. Rows with
+/// no materialized HHTL path (`hhtl_path_at == None`) are skipped.
+pub fn clam_contained<V: MailboxSoaView>(view: &V, query: NiblePath) -> Vec<NodeMatch> {
+    (0..view.n_rows())
+        .filter(|&row| view.hhtl_path_at(row).is_some_and(|p| query.is_ancestor_of(p)))
+        .map(|row| NodeMatch {
+            row,
+            backend: Backend::MailboxSoa,
+        })
+        .collect()
+}
+
+/// **CAKES nearest** — the `k` rows nearest `query` by longest-common-prefix
+/// depth (descending), the radix-trie nearest-neighbor over the HHTL paths.
+///
+/// Returns `(NodeMatch, shared_depth)`; deeper shared prefix ⇒ nearer (same deeper
+/// CLAM cluster). Ties keep ascending row order (stable). Pure key arithmetic —
+/// **zero value decode**; rows without a materialized HHTL path are skipped. This
+/// is CAKES "attraction" expressed as `NiblePath::common_prefix_depth`
+/// (`E-CLAM-IS-THE-MANIFOLD-ENGINE`).
+pub fn cakes_nearest<V: MailboxSoaView>(
+    view: &V,
+    query: NiblePath,
+    k: usize,
+) -> Vec<(NodeMatch, u8)> {
+    let mut scored: Vec<(NodeMatch, u8)> = (0..view.n_rows())
+        .filter_map(|row| {
+            view.hhtl_path_at(row).map(|p| {
+                (
+                    NodeMatch {
+                        row,
+                        backend: Backend::MailboxSoa,
+                    },
+                    query.common_prefix_depth(p),
+                )
+            })
+        })
+        .collect();
+    // Descending by shared depth; stable sort preserves ascending row order on ties.
+    scored.sort_by(|a, b| b.1.cmp(&a.1));
+    scored.truncate(k);
+    scored
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -100,6 +150,7 @@ mod tests {
         class_ids: Vec<u16>,
         edges: Vec<u64>,
         keyed_rows: Vec<(u64, usize)>,
+        paths: Vec<Option<NiblePath>>,
     }
 
     impl MailboxSoaView for GuardedSoa {
@@ -141,6 +192,9 @@ mod tests {
                 .find(|(k, _)| *k == local_key)
                 .map(|(_, r)| *r)
         }
+        fn hhtl_path_at(&self, row: usize) -> Option<NiblePath> {
+            self.paths.get(row).copied().flatten()
+        }
     }
 
     fn sample() -> GuardedSoa {
@@ -149,6 +203,15 @@ mod tests {
             class_ids: vec![7, 9, 7, 9, 7],
             edges: vec![0; 5],
             keyed_rows: vec![(0xABCD, 3), (0x1234, 0)],
+            // HHTL radix-trie paths (root basin 1):
+            //   row0: 1·2·3   row1: 1·2·4   row2: 1·2   row3: 1·5   row4: 9 (other basin)
+            paths: vec![
+                Some(NiblePath::root(1).child(2).child(3)),
+                Some(NiblePath::root(1).child(2).child(4)),
+                Some(NiblePath::root(1).child(2)),
+                Some(NiblePath::root(1).child(5)),
+                Some(NiblePath::root(9)),
+            ],
         }
     }
 
@@ -193,9 +256,55 @@ mod tests {
     #[test]
     fn f2_zero_value_decode_the_scan_never_panics_on_value_columns() {
         // The GuardedSoa panics if energy()/meta_raw() are read. If this test
-        // completes, the classid node-match touched ONLY the class column.
+        // completes, the classid node-match + CLAM/CAKES touched ONLY the
+        // class/HHTL key columns, never the value slab.
         let soa = sample();
         let _ = match_nodes_by_class(&soa, 7);
         let _ = match_node_by_local_key(&soa, 0x1234);
+        let _ = clam_contained(&soa, NiblePath::root(1).child(2));
+        let _ = cakes_nearest(&soa, NiblePath::root(1).child(2).child(3), 3);
+    }
+
+    #[test]
+    fn clam_contained_is_the_radix_subtree() {
+        // query = 1·2 ⇒ its CLAM cluster = the radix subtree under 1·2:
+        // rows 0 (1·2·3), 1 (1·2·4), 2 (1·2 itself). NOT 3 (1·5) or 4 (other basin 9).
+        let soa = sample();
+        let rows: Vec<usize> = clam_contained(&soa, NiblePath::root(1).child(2))
+            .iter()
+            .map(|m| m.row)
+            .collect();
+        assert_eq!(rows, vec![0, 1, 2]);
+        // a deeper query narrows the subtree to the exact leaf.
+        let leaf: Vec<usize> = clam_contained(&soa, NiblePath::root(1).child(2).child(3))
+            .iter()
+            .map(|m| m.row)
+            .collect();
+        assert_eq!(leaf, vec![0]);
+    }
+
+    #[test]
+    fn cakes_nearest_ranks_by_longest_common_prefix() {
+        // query = 1·2·3 (row 0). Shared-prefix depths:
+        //   row0 1·2·3 →3, row1 1·2·4 →2, row2 1·2 →2, row3 1·5 →1, row4 9 →0.
+        let soa = sample();
+        let near = cakes_nearest(&soa, NiblePath::root(1).child(2).child(3), 3);
+        let ranked: Vec<(usize, u8)> = near.iter().map(|(m, d)| (m.row, *d)).collect();
+        assert_eq!(ranked, vec![(0, 3), (1, 2), (2, 2)], "nearest-3 by shared depth");
+        assert!(near.iter().all(|(m, _)| m.backend == Backend::MailboxSoa));
+        // k larger than n returns all rows, still depth-sorted descending.
+        let all = cakes_nearest(&soa, NiblePath::root(1).child(2).child(3), 99);
+        let depths: Vec<u8> = all.iter().map(|(_, d)| *d).collect();
+        assert_eq!(depths, vec![3, 2, 2, 1, 0]);
+    }
+
+    #[test]
+    fn clam_cakes_skip_rows_with_no_materialized_path() {
+        // A view with all-None hhtl paths (the deferred-binding default) yields
+        // nothing — the consumer falls back to a coarser facet, never a wrong row.
+        let mut soa = sample();
+        soa.paths = vec![None; 5];
+        assert!(clam_contained(&soa, NiblePath::root(1)).is_empty());
+        assert!(cakes_nearest(&soa, NiblePath::root(1), 5).is_empty());
     }
 }