feat(contract): ValueSchema value-slab presets (Full/Cognitive/Compressed/Bootstrap)

The value-side analog of EdgeCodecFlavor: per-class presets for which tenants the
480-byte NodeRow::value slab materialises. Closes the SoA-extension dilution gap —
helix-48 was the one element still only a TODO comment in the value slab; it is now
a first-class tenant alongside turbovec-Pq32x4 + signed-CoarseResidue.

- ValueTenant: 9 stable append-only positions (discriminant == FieldMask bit ==
  VALUE_TENANTS index) — Meta/Qualia/MaterializedEdges/Fingerprint/HelixResidue/
  TurbovecResidue/Energy/Plasticity/EntityType.
- VALUE_TENANTS: stable row-relative carve [32,186) (reserve-don't-reclaim,
  contiguous, compile-time asserted <= 480).
- ValueSchema presets via FieldMask: Bootstrap (EMPTY default) / Cognitive (58 B) /
  Compressed (98 B) / Full (154 B = all 9 tenants).
- ClassView::value_schema() defaulted to Bootstrap (non-breaking; mirrors
  edge_codec_flavor).
- Layout-preserving: carves WITHIN the reserved slab, NODE_ROW_STRIDE=512 untouched,
  no ENVELOPE_LAYOUT_VERSION bump.

Reuses class_view::FieldMask (presence) + soa_envelope::ColumnDescriptor (carve) —
no new presence type. +6 tests + 3 compile-time canon asserts; fmt + clippy -D
warnings + test -p lance-graph-contract green (611 lib tests). Board: LATEST_STATE
Contract Inventory + AGENT_LOG updated same commit.

https://claude.ai/code/session_01D2WSmezQBNC3bUdHuGfGmo

Author: claude

.claude/board/AGENT_LOG.md

@@ -1,3 +1,11 @@
+## 2026-06-14 — `ValueSchema` value-slab presets (Full + Cognitive/Compressed/Bootstrap) — closes the helix-48 dilution gap
+
+**Main thread.** Operator: *"create different Schema presets, the 'full' is one of the options."* Context: after confirming the SoA-extension ((12+4) edges + turbovec residue + signed) was already locked as `EdgeCodecFlavor` (commit `920671d`) on #489's `EdgeBlock`, **helix-48** was the one element still only a TODO-comment in the `value(480)` slab — the dilution risk the operator flagged.
+
+**Shipped (contract, additive, build-verified):** `canonical_node::{ValueSchema, ValueTenant, VALUE_TENANTS}` — the value-side analog of `EdgeCodecFlavor`. 9 stable append-only `ValueTenant`s (discriminant == `FieldMask` bit == `VALUE_TENANTS` index) carving the value slab contiguously `[32,186)` (154 of 480 B; reserve-don't-reclaim). Four presets via `FieldMask`: `Bootstrap` (EMPTY default), `Cognitive` (58 B), `Compressed` (98 B), `Full` (154 B = all tenants). `ClassView::value_schema()` defaulted to `Bootstrap` (non-breaking, mirrors `edge_codec_flavor`). Layout-preserving (no stride change, no `ENVELOPE_LAYOUT_VERSION` bump). **helix-48 + turbovec-`Pq32x4` + signed-`CoarseResidue` are now all first-class tenants — the dilution gap is closed.**
+
+**Reused, not duplicated** (operator's "refactor into what exists"): `class_view::FieldMask` (presence) + `soa_envelope::ColumnDescriptor` (carve) — no new presence type. +6 tests + 3 compile-time canon asserts; `cargo fmt` / `clippy -D warnings` / `test -p lance-graph-contract` all green (611 lib tests). Pushed to #495 (safe fallback intact). `EdgeCodecFlavor` (operator's earlier idea, `920671d`) untouched.
+
 ## 2026-06-14 — Doc-sweep: stale `lance 6.0.0 / lancedb 0.29.0` → canonical `7.0.0 / 0.30.0` across CLAUDE.md + plans + boards
 
 **Main thread.** Operator: *"it's 7.0.0 + 0.30, please update all plans boards accordingly"* + *"update the .claude/board ledgers epiphany technical debt implemented plans phases etc"*. Swept every stale `lance =6.0.0 / lancedb =0.29.0` reference to the canonical stack the workspace already runs.

.claude/board/LATEST_STATE.md

@@ -520,5 +520,6 @@ PR sequence: #360 → #361 → post-#360 substrate-sweep (this PR).
 ### Current Contract Inventory — new entry
 
 - **`canonical_node::EdgeCodecFlavor`** (NEW; re-exported from `lib.rs`). Per-class selector for how a node's 16-byte `EdgeBlock` (+ optional value-slab residue) is *interpreted* — `CoarseOnly` (1 B palette index, the canon zero-fallback default), `CoarseResidue` (1 + ⌈D/2⌉ B, value-slab signed-4-bit residue), `Pq32x4` (16 B = 32×4-bit product code, the turbovec PQ model). `bytes_per_vector(dim)` + `is_layout_preserving()` (always `true`). **Iron invariant:** the flavor is interpretation, NOT layout — every variant leaves `NODE_ROW_STRIDE = 512` untouched, so adoption needs no `ENVELOPE_LAYOUT_VERSION` bump (canon "registry-resolved via `classid → ClassView`"). Default `CoarseOnly` matches the all-zero bootstrap. Selection surface: new defaulted `ClassView::edge_codec_flavor(&self, ClassId) -> EdgeCodecFlavor` (non-breaking — `RegistryClassView` inherits the default; per-class override is the follow-up wiring in `lance-graph-ontology`). +3 tests; contract lib 609 green; clippy `-D warnings` clean.
+- **`canonical_node::ValueSchema` + `ValueTenant` + `VALUE_TENANTS`** (NEW; re-exported from `lib.rs`). The **value-side analog of `EdgeCodecFlavor`**: per-class presets for which tenants the 480-byte `NodeRow::value` slab materialises. `ValueTenant` = 9 stable append-only positions (discriminant == `FieldMask` bit == `VALUE_TENANTS` index): Meta(`MetaWord`) · Qualia(`QualiaI4_16D`) · MaterializedEdges(4×`CausalEdge64`) · Fingerprint(32 B) · **HelixResidue(48 B)** · **TurbovecResidue(`Pq32x4` 16 B)** · Energy(f32) · Plasticity(u32) · EntityType(u16). `VALUE_TENANTS` = the stable row-relative byte carve `[32,186)` (reserve-don't-reclaim, contiguous, compile-time asserted ≤ 480). Presets: `Bootstrap` (EMPTY, zero-fallback **default**) · `Cognitive` (58 B: hot SoA columns, no codec residues) · `Compressed` (98 B: codec stack + fingerprint, no hot lifecycle) · `Full` (154 B: all 9 tenants). Built on existing `class_view::FieldMask` (presence) + `soa_envelope::ColumnDescriptor` — **no new presence type** (per "refactor into what exists"). `is_layout_preserving()` always `true` (carves WITHIN the reserved slab; `NODE_ROW_STRIDE=512` untouched → no `ENVELOPE_LAYOUT_VERSION` bump). Selection surface: defaulted `ClassView::value_schema(&self, ClassId) -> ValueSchema` (default `Bootstrap`, non-breaking — mirrors `edge_codec_flavor`). **Closes the SoA-extension dilution gap**: the formerly-comment-only helix-48 is now a first-class tenant alongside turbovec-`Pq32x4` + signed-`CoarseResidue`. +6 tests + 3 compile-time canon asserts; contract lib 611 green; clippy `-D warnings` + fmt clean.
 - **Encode/measure kernels live in `ndarray` (the hardware layer), not the contract:** `ndarray::hpc::edge_codec` (Codebook k-means, `CoarseResidueCodec`, `ProductQuantizer`, `reconstruct_coarse`) + `ndarray::hpc::reliability` (Pearson r, Spearman ρ, Cronbach α, ICC(2,1), `FidelityReport`). Harness `examples/edge_codec_compare` measures all flavors × {blob, continuous} regimes. **Measured:** CoarseResidue dominates agreement (ICC 0.97–0.99, ρ 0.98, α 0.99); Pq32x4 keeps rank (ρ 0.60–0.67) but not absolute distance (ICC 0.11–0.29); CoarseOnly collapses on continuous (ICC 0.003); AMX `matmul_i8_to_i32` assign 100% vs scalar, 24–28 GMAC/s. ndarray commit `d3b608f`.
 - **Deferred (flagged):** turbovec PQ4 *throughput* path (the FastScan nibble-LUT for the Pq32x4 flavor) blocked on the **#493 P2** build break — `lance-graph-turbovec` requests the `ndarray-simd` turbovec feature that was REMOVED (turbovec commit `7fa217c`); the polyfill fns are gone. turbovec's API is end-to-end (owns encode+scan), so it is a *PQ4 flavor*, not a residue-nibble-scan primitive. Fidelity (what ICC/Pearson/α measure) is independent of the fast kernel, so this is throughput-only follow-up.

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

@@ -259,6 +259,7 @@ const _: () = assert!(core::mem::size_of::<NodeRow>() == 512);
 
 // ── SoaEnvelope binding for [NodeRow] ────────────────────────────────────────
 
+use crate::class_view::FieldMask;
 use crate::soa_envelope::{ColumnDescriptor, ColumnKind, SoaEnvelope};
 
 /// Stable column-id ordinals for [`NodeRow`]'s three top-level slots.
@@ -304,6 +305,230 @@ pub const NODE_ROW_COLUMNS: &[ColumnDescriptor] = &[
 /// Row stride for [`NodeRow`] in bytes — equal to `size_of::<NodeRow>()`.
 pub const NODE_ROW_STRIDE: usize = 512;
 
+// ── Value-slab schema presets: which tenants a class materialises ─────────────
+
+/// Full-row byte offset of the value slab (key 16 + edges 16).
+pub const VALUE_SLAB_ROW_OFFSET: usize = 32;
+/// Bytes available in the [`NodeRow::value`] slab.
+pub const VALUE_SLAB_LEN: usize = 480;
+
+/// A named tenant of the 480-byte [`NodeRow::value`] slab.
+///
+/// Stable, append-only positions — the canon "reserve, don't reclaim" rule and
+/// the [`FieldMask`] N3 contract: a tenant's presence bit and its byte offset in
+/// [`VALUE_TENANTS`] never move once instances persist, and retired tenants are
+/// never reused. **The discriminant IS the [`FieldMask`] bit position** and the
+/// index into [`VALUE_TENANTS`] (asserted at compile time below).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[repr(u8)]
+pub enum ValueTenant {
+    /// `MetaWord` — thinking / awareness / NARS / free-energy bits.
+    Meta = 0,
+    /// `QualiaI4_16D` — 16 signed-4-bit chroma channels.
+    Qualia = 1,
+    /// The 4 out-of-family edges materialised as full `CausalEdge64`.
+    MaterializedEdges = 2,
+    /// `Fingerprint<256>` — 32-byte identity print.
+    Fingerprint = 3,
+    /// helix golden-spiral Place/Residue (48 B).
+    HelixResidue = 4,
+    /// turbovec PQ residue ([`EdgeCodecFlavor::Pq32x4`], 16 B).
+    TurbovecResidue = 5,
+    /// Spatio-temporal accumulator (`f32`).
+    Energy = 6,
+    /// Hebbian plasticity counter + last-active stamp.
+    Plasticity = 7,
+    /// OGIT entity-type / class discriminator (`u16`).
+    EntityType = 8,
+}
+
+/// Stable byte carve of the value slab. Offsets are **row-relative** (within one
+/// row packet, in the value region `[32, 512)`) — consistent with
+/// [`NODE_ROW_COLUMNS`], one level finer. Contiguous, in [`ValueTenant`]
+/// discriminant order, no gaps; the Full set fits the slab (all asserted at
+/// compile time below). This is the per-class carve the canon defers to
+/// `ClassView`; it is NOT surfaced as its own top-level envelope column.
+pub const VALUE_TENANTS: &[ColumnDescriptor] = &[
+    ColumnDescriptor {
+        name_id: ValueTenant::Meta as u16,
+        kind: ColumnKind::U64,
+        elems_per_row: 1,
+        row_offset: 32,
+    },
+    ColumnDescriptor {
+        name_id: ValueTenant::Qualia as u16,
+        kind: ColumnKind::U64,
+        elems_per_row: 1,
+        row_offset: 40,
+    },
+    ColumnDescriptor {
+        name_id: ValueTenant::MaterializedEdges as u16,
+        kind: ColumnKind::U64,
+        elems_per_row: 4,
+        row_offset: 48,
+    },
+    ColumnDescriptor {
+        name_id: ValueTenant::Fingerprint as u16,
+        kind: ColumnKind::U8,
+        elems_per_row: 32,
+        row_offset: 80,
+    },
+    ColumnDescriptor {
+        name_id: ValueTenant::HelixResidue as u16,
+        kind: ColumnKind::U8,
+        elems_per_row: 48,
+        row_offset: 112,
+    },
+    ColumnDescriptor {
+        name_id: ValueTenant::TurbovecResidue as u16,
+        kind: ColumnKind::U8,
+        elems_per_row: 16,
+        row_offset: 160,
+    },
+    ColumnDescriptor {
+        name_id: ValueTenant::Energy as u16,
+        kind: ColumnKind::F32,
+        elems_per_row: 1,
+        row_offset: 176,
+    },
+    ColumnDescriptor {
+        name_id: ValueTenant::Plasticity as u16,
+        kind: ColumnKind::U32,
+        elems_per_row: 1,
+        row_offset: 180,
+    },
+    ColumnDescriptor {
+        name_id: ValueTenant::EntityType as u16,
+        kind: ColumnKind::U16,
+        elems_per_row: 1,
+        row_offset: 184,
+    },
+];
+
+// Compile-time canon: VALUE_TENANTS is discriminant-ordered, contiguous within the
+// value slab, and the Full carve fits the 480-byte slab.
+const _: () = {
+    let mut i = 0usize;
+    let mut prev_end = VALUE_SLAB_ROW_OFFSET;
+    while i < VALUE_TENANTS.len() {
+        let c = &VALUE_TENANTS[i];
+        assert!(
+            c.name_id as usize == i,
+            "ValueTenant discriminant must equal its VALUE_TENANTS index"
+        );
+        assert!(
+            c.row_offset as usize == prev_end,
+            "VALUE_TENANTS must be contiguous within the value slab (no gaps/overlap)"
+        );
+        prev_end = c.row_offset as usize + c.col_bytes_per_row();
+        i += 1;
+    }
+    assert!(
+        prev_end <= NODE_ROW_STRIDE,
+        "value tenants must fit within the 512-byte row"
+    );
+    assert!(
+        prev_end - VALUE_SLAB_ROW_OFFSET <= VALUE_SLAB_LEN,
+        "value tenants must fit the 480-byte slab"
+    );
+};
+
+/// Which value-slab schema a class materialises — the value-side analog of
+/// [`EdgeCodecFlavor`]. A preset is a presence [`FieldMask`] over [`ValueTenant`]
+/// positions; a class selects it via
+/// [`ClassView::value_schema`](crate::class_view::ClassView::value_schema).
+///
+/// **Layout-preserving:** every preset carves WITHIN the reserved 480-byte value
+/// slab, so the choice never changes [`NODE_ROW_STRIDE`] (no
+/// `ENVELOPE_LAYOUT_VERSION` bump — canon "registry-resolved via
+/// `classid → ClassView`", never a stride change). [`Bootstrap`] is the
+/// zero-fallback default: value all zero, only key + edges meaningful.
+///
+/// [`Bootstrap`]: ValueSchema::Bootstrap
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
+#[repr(u8)]
+pub enum ValueSchema {
+    /// Empty value slab — the canon zero-fallback (key + edges only).
+    #[default]
+    Bootstrap = 0,
+    /// Hot self-thinking set: Meta + Qualia + Fingerprint + Energy + Plasticity +
+    /// EntityType. No materialised edges, no codec residues.
+    Cognitive = 1,
+    /// Cold / compressed codec stack: Fingerprint + Helix-48 + turbovec residue +
+    /// EntityType. No hot lifecycle columns.
+    Compressed = 2,
+    /// Every [`ValueTenant`] materialised — the densest node.
+    Full = 3,
+}
+
+impl ValueSchema {
+    /// The presence [`FieldMask`] over [`ValueTenant`] positions for this preset.
+    pub const fn field_mask(self) -> FieldMask {
+        match self {
+            ValueSchema::Bootstrap => FieldMask::EMPTY,
+            ValueSchema::Cognitive => FieldMask::from_positions(&[
+                ValueTenant::Meta as u8,
+                ValueTenant::Qualia as u8,
+                ValueTenant::Fingerprint as u8,
+                ValueTenant::Energy as u8,
+                ValueTenant::Plasticity as u8,
+                ValueTenant::EntityType as u8,
+            ]),
+            ValueSchema::Compressed => FieldMask::from_positions(&[
+                ValueTenant::Fingerprint as u8,
+                ValueTenant::HelixResidue as u8,
+                ValueTenant::TurbovecResidue as u8,
+                ValueTenant::EntityType as u8,
+            ]),
+            ValueSchema::Full => FieldMask::from_positions(&[
+                ValueTenant::Meta as u8,
+                ValueTenant::Qualia as u8,
+                ValueTenant::MaterializedEdges as u8,
+                ValueTenant::Fingerprint as u8,
+                ValueTenant::HelixResidue as u8,
+                ValueTenant::TurbovecResidue as u8,
+                ValueTenant::Energy as u8,
+                ValueTenant::Plasticity as u8,
+                ValueTenant::EntityType as u8,
+            ]),
+        }
+    }
+
+    /// Does this preset materialise `tenant`?
+    #[inline]
+    pub const fn has(self, tenant: ValueTenant) -> bool {
+        self.field_mask().has(tenant as u8)
+    }
+
+    /// Total bytes this preset occupies in the value slab (Σ present tenants).
+    pub const fn tenant_bytes(self) -> usize {
+        let mask = self.field_mask();
+        let mut total = 0usize;
+        let mut i = 0usize;
+        while i < VALUE_TENANTS.len() {
+            let c = &VALUE_TENANTS[i];
+            if mask.has(c.name_id as u8) {
+                total += c.col_bytes_per_row();
+            }
+            i += 1;
+        }
+        total
+    }
+
+    /// Every preset carves within the reserved 480-byte slab — none changes
+    /// [`NODE_ROW_STRIDE`], so none forces an `ENVELOPE_LAYOUT_VERSION` bump.
+    #[inline]
+    pub const fn is_layout_preserving(self) -> bool {
+        true
+    }
+}
+
+// Compile-time canon: the densest preset fits the slab; Full covers every tenant;
+// Bootstrap is empty.
+const _: () = assert!(ValueSchema::Full.tenant_bytes() <= VALUE_SLAB_LEN);
+const _: () = assert!(ValueSchema::Full.field_mask().count() as usize == VALUE_TENANTS.len());
+const _: () = assert!(ValueSchema::Bootstrap.field_mask().is_empty());
+
 /// Zero-copy [`SoaEnvelope`] wrapper over a contiguous slice of [`NodeRow`].
 ///
 /// `NodeRow` is `#[repr(C, align(64))]` with the locked 16/16/480 byte
@@ -660,4 +885,90 @@ mod tests {
         // verify_layout exercises that gate.
         assert!(pkt.verify_layout().is_ok());
     }
+
+    // ── Value-slab schema presets ────────────────────────────────────────────
+
+    #[test]
+    fn value_tenants_contiguous_within_slab() {
+        let mut prev_end = VALUE_SLAB_ROW_OFFSET;
+        for (i, c) in VALUE_TENANTS.iter().enumerate() {
+            assert_eq!(c.name_id as usize, i, "discriminant == index");
+            assert_eq!(c.row_offset as usize, prev_end, "no gap before {c:?}");
+            prev_end = c.row_offset as usize + c.col_bytes_per_row();
+        }
+        assert!(prev_end <= NODE_ROW_STRIDE);
+        assert_eq!(
+            prev_end - VALUE_SLAB_ROW_OFFSET,
+            154,
+            "current Full carve uses 154 of 480 B"
+        );
+        assert!(prev_end - VALUE_SLAB_ROW_OFFSET <= VALUE_SLAB_LEN);
+    }
+
+    #[test]
+    fn value_schema_default_is_bootstrap_empty() {
+        assert_eq!(ValueSchema::default(), ValueSchema::Bootstrap);
+        assert!(ValueSchema::Bootstrap.field_mask().is_empty());
+        assert_eq!(ValueSchema::Bootstrap.tenant_bytes(), 0);
+    }
+
+    #[test]
+    fn value_schema_full_covers_every_tenant() {
+        let full = ValueSchema::Full;
+        assert_eq!(full.field_mask().count() as usize, VALUE_TENANTS.len());
+        for t in [
+            ValueTenant::Meta,
+            ValueTenant::Qualia,
+            ValueTenant::MaterializedEdges,
+            ValueTenant::Fingerprint,
+            ValueTenant::HelixResidue,
+            ValueTenant::TurbovecResidue,
+            ValueTenant::Energy,
+            ValueTenant::Plasticity,
+            ValueTenant::EntityType,
+        ] {
+            assert!(full.has(t), "Full must materialise {t:?}");
+        }
+    }
+
+    #[test]
+    fn value_schema_byte_budgets_are_locked() {
+        assert_eq!(ValueSchema::Bootstrap.tenant_bytes(), 0);
+        assert_eq!(ValueSchema::Cognitive.tenant_bytes(), 58);
+        assert_eq!(ValueSchema::Compressed.tenant_bytes(), 98);
+        assert_eq!(ValueSchema::Full.tenant_bytes(), 154);
+        for s in [
+            ValueSchema::Bootstrap,
+            ValueSchema::Cognitive,
+            ValueSchema::Compressed,
+            ValueSchema::Full,
+        ] {
+            assert!(s.tenant_bytes() <= VALUE_SLAB_LEN);
+            assert!(s.is_layout_preserving());
+        }
+    }
+
+    #[test]
+    fn value_schema_presets_carry_expected_tenants() {
+        // Cognitive: hot columns, no codec residues, no materialised edges.
+        let c = ValueSchema::Cognitive;
+        assert!(c.has(ValueTenant::Meta) && c.has(ValueTenant::Qualia));
+        assert!(c.has(ValueTenant::Energy) && c.has(ValueTenant::EntityType));
+        assert!(!c.has(ValueTenant::HelixResidue));
+        assert!(!c.has(ValueTenant::TurbovecResidue));
+        assert!(!c.has(ValueTenant::MaterializedEdges));
+        // Compressed: codec residues, no hot lifecycle.
+        let z = ValueSchema::Compressed;
+        assert!(z.has(ValueTenant::HelixResidue) && z.has(ValueTenant::TurbovecResidue));
+        assert!(z.has(ValueTenant::Fingerprint));
+        assert!(!z.has(ValueTenant::Energy) && !z.has(ValueTenant::Meta));
+    }
+
+    #[test]
+    fn value_schema_preserves_node_stride() {
+        // A preset is an interpretation of the reserved value slab, never a
+        // stride change — same canon invariant as EdgeCodecFlavor.
+        assert_eq!(NODE_ROW_STRIDE, core::mem::size_of::<NodeRow>());
+        assert_eq!(VALUE_SLAB_ROW_OFFSET + VALUE_SLAB_LEN, NODE_ROW_STRIDE);
+    }
 }

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

@@ -218,6 +218,21 @@ pub trait ClassView {
     fn edge_codec_flavor(&self, _class: ClassId) -> crate::canonical_node::EdgeCodecFlavor {
         crate::canonical_node::EdgeCodecFlavor::CoarseOnly
     }
+
+    /// Which value-slab schema preset this class materialises in
+    /// [`NodeRow::value`](crate::canonical_node::NodeRow::value).
+    ///
+    /// Default is
+    /// [`ValueSchema::Bootstrap`](crate::canonical_node::ValueSchema::Bootstrap)
+    /// — the canon zero-fallback (value all zero; only key + edges meaningful). An
+    /// implementor overrides this to declare a denser preset (`Cognitive` /
+    /// `Compressed` / `Full`). Selection only: every preset carves within the
+    /// reserved 480-byte value slab, so the choice never changes `NODE_ROW_STRIDE`
+    /// (canon "registry-resolved via `classid → ClassView`", never a stride change).
+    #[inline]
+    fn value_schema(&self, _class: ClassId) -> crate::canonical_node::ValueSchema {
+        crate::canonical_node::ValueSchema::Bootstrap
+    }
 }
 
 /// One populated field to render — the late-resolved `label` + its `predicate` key.