feat(shader-driver): unbreak with-engine + F32-17D bit-exact qualia tenant (S-series 1+2)

.claude/board/AGENT_LOG.md

@@ -1,3 +1,14 @@
+## 2026-06-18 — S-series Step 1+2: unbreak --features with-engine + F32-17D bit-exact qualia tenant
+
+**Main thread (Opus) + panel.** Branch `claude/with-engine-build-fix`. Two commits: (1) import `QUALIA_DIMS` to unbreak `--features with-engine` (engine_bridge.rs:259 used it unimported — the entire dispatch/unbind lab surface was dormant); (2) restore an F32-17D bit-exact qualia tenant.
+
+**Fix:** added `BindSpace.qualia_f32: Box<[QualiaVector]>` (`#[cfg(with-engine)]`, singleton only, ~278KB on 4096 rows) + `qualia_f32_row`/`set_qualia_f32` accessors. `dispatch_busdto` writes it alongside the i4 column; `unbind_busdto` reads it (bit-exact). MailboxSoA hot path UNCHANGED (i4 only — no 64k blowup). codebook_index rides q[9]-f32 (lossless). The i4 column stays the production carrier (C7: the ±0.15 i4-tolerance tests untouched). `QUALIA_DIMS` import gated to with-engine (no default unused-import). See `E-QUALIA-F32-LAB-TENANT`.
+
+**The 3 round-trip tests pass un-ignored + UNMODIFIED** (bit-exact assertions are the spec; not weakened). Added C8 corner corpus. singleton 6/6, mailbox-arm 5/5, default lib 20/20, fmt clean.
+
+**Note (not in this PR):** CI does not clippy-gate `cognitive-shader-driver` or `lance-graph-ontology` (style.yml scopes to contract/lance-graph/deepnsm). `lance-graph-ontology` carries 12 pre-existing `-D warnings` clippy errors (oxrdf deprecation + doc-list + `to_vec`, from #530/#533) — cap-lints-allowed as a dep, not a CI gate, not this PR's scope. My crate's pre-existing clippy debt (bindspace:475, engine_bridge:780, test helpers) is likewise out of scope and not introduced here.
+
+**Next (S3):** flip ShaderDriver off the Arc<BindSpace> singleton onto the mailbox set; the F32 tenant is now the bit-exact anchor to diff every migration step against.
 ## 2026-06-18 — D-MBX-A2 board reconciliation (carrier shipped; S2 ~80% pre-absorbed) — 5+3 council
 
 **Main thread (Opus) + 5+3 council**, branch `claude/dmbxa2-board-reconciliation`. Operator asked for "D-MBX-A2 ⟷ S-series together"; the council (integration-lead, preflight-drift-auditor, iron-rule-savant, dto-soa-savant, truth-architect + brutal critics brutally-honest-tester, baton-handoff-auditor, firewall-warden) unanimously found D-MBX-A2's column carrier is **already shipped** (landed after the 2026-06-13 reconciliation snapshot the boards were trusting) and the engine_bridge "S2" re-home is ~80% pre-absorbed by the W4a `BackingStore`/`BackingStoreWrite` shim. brutally-honest-tester: "land the board reconciliation, not S2." So this PR is the honest D-MBX-A2 closure (docs only).

.claude/board/EPIPHANIES.md

@@ -1,3 +1,14 @@
+## 2026-06-18 — E-QUALIA-F32-LAB-TENANT — i4 qualia is lossy for codebook_index + energies; the F32-17D BindSpace tenant is the migration's bit-exact anchor
+
+**Status:** FINDING (operator-directed "wire F32; one exactness to measure against during the migration"; 3-agent panel LAND — dto-soa FITS-COLUMN, iron-rule LAND-with-AP1-guard, truth-architect PASS-able — supplementing the earlier 8-agent S-series council).
+
+**The bug (latent, unmasked by the with-engine build fix).** `engine_bridge::dispatch_busdto` stored the BusDto headline `codebook_index` in `q[9]` and the energies in `q[0..9]`, then quantized via `QualiaI4_16D::from_f32_17d` — which `clamp(-1,1)` + i4-rounds. So `codebook_index 42 → 1`, `energy 0.1 → 0.143`. The "round-trips losslessly through f32" doc was stale: true when qualia was an f32 column, FALSE since **D-CSV-5b** made qualia i4. The 3 `with-engine` round-trip tests (`busdto_round_trip_{dense,sparse,zero}`) had been dead-and-red (uncompiled while `with-engine` was broken on `QUALIA_DIMS`).
+
+**The fix (operator's "2 tenants", F32 chosen).** Restore a **bit-exact F32-17D qualia tenant** — `qualia_f32: Box<[QualiaVector]>` ([f32;17]/row) — on the **BindSpace singleton ONLY**, `#[cfg(feature="with-engine")]`-gated. `dispatch_busdto` writes it (in addition to the i4 column, which stays the hot-path carrier for general consumers); `unbind_busdto` reads it (bit-exact). `MailboxSoA` keeps ONLY i4 (no `+68 B/row × 64k` hot-envelope blowup), so this is NOT a D-CSV-5b reversal — it's the second tenant (i4 hot + f32 lab). `codebook_index` in `q[9]`-f32 is lossless (f32 exact to 2^24 ⊇ u16) and I-VSA-IDENTITIES-clean (register-as-store, not a bundled identity). AP1 guard honored: separately-named accessor (`qualia_f32_row`/`set_qualia_f32`), production layout byte-unchanged.
+
+**Why it matters beyond the bug:** the F32-17D tenant is the **single bit-exact ground-truth** the rest of the SoA migration (S3 driver-flip, future quantization tiers bf16/i4) measures against — every step can diff against it. Alternatives (bf16/f16-17D) are deferred; bf16 is integer-exact only to 256, f16 to 2048, and neither is f32-bit-exact, so they could not satisfy the bit-exact tests as the anchor.
+
+**Tests:** singleton `--features with-engine` 6/6 (the 3 un-ignored + 2 + the C8 corner corpus `codebook_index ∈ {0,255,256,1234,4095,65535}`); mailbox-arm `--features with-engine,mailbox-thoughtspace` 5/5 (headline+energy bit-exact via the f32 tenant; non-headline top_k=0 by design, C5/D-DIST-5 preserved); default lib 20/20 (cfg field absent — no hot-path change). fmt clean; my code clippy-clean.
 ## 2026-06-18 — E-ODOO-VIRTUALLY-OVERRIDES-COMPUTED — the wishlist's last item is a *derived* ClassView relation, not harvest predicate #6
 
 **Status:** FINDING. `virtually_overrides` — the one open odoo-rs wishlist item — lands as a **computed** Core/ClassView capability (`odoo_blueprint::mro`), closing the wishlist consistently with the Core-first correction (E-ODOO-CORE-FIRST-STRUCTURAL) directly above. Per the doctrine the `(has_function / inherits_from / virtually_overrides)` triad is the ClassView method-resolution manifest: `has_function` + `inherits_from` are *facts*; `virtually_overrides` is the **derivation** (`M.m` overrides `B.m` iff `M` declares `m`, `B` is up `M`'s `_inherit` chain, and `B` also declares `m`). Adding a `virtually_overrides` AST pass to `spo_enrich.py` would have been the drift; computing it from the manifest is the Core-correct move.

crates/cognitive-shader-driver/src/bindspace.rs

@@ -14,6 +14,13 @@ use std::sync::Arc;
 
 use lance_graph_contract::cognitive_shader::{ColumnWindow, MetaFilter, MetaWord};
 use lance_graph_contract::qualia::QualiaI4_16D;
+// Lab-only bit-exact qualia tenant (see the `qualia_f32` field on `BindSpace`).
+// `QualiaVector = [f32; 17]` is the canonical contract type. NOTE: the contract's
+// `QUALIA_DIMS` is 17; this module's local `QUALIA_DIMS` const is 18 (the old
+// padded scheme) — the tenant is sized off the contract `QualiaVector`, not the
+// local const.
+#[cfg(feature = "with-engine")]
+use lance_graph_contract::qualia::QualiaVector;
 use lance_graph_ontology::OntologyRegistry;
 
 pub const WORDS_PER_FP: usize = 256;
@@ -256,6 +263,16 @@ pub struct BindSpace {
     /// Canonical qualia column (i4-16D, D-CSV-5b). Returns `QualiaI4_16D` by value.
     /// The old `QualiaColumn` (f32) was retired in D-CSV-5b; see `QualiaColumn` docs.
     pub qualia: QualiaI4Column,
+    /// **Lab bit-exact qualia tenant** (`with-engine` only). NOT a D-CSV-5b
+    /// reversal: the canonical hot column is `qualia` (i4, `QualiaI4_16D`); this
+    /// `[f32; 17]`-per-row tenant exists solely as the bit-exact ground-truth for
+    /// the `engine_bridge` `dispatch_busdto` / `unbind_busdto` round-trip during
+    /// the SoA migration (one exactness to measure every migration step against).
+    /// Production builds and `MailboxSoA` carry ONLY the i4 column — this tenant is
+    /// absent unless `with-engine` is on. 68 B/row on the singleton only.
+    /// See `E-QUALIA-F32-LAB-TENANT`.
+    #[cfg(feature = "with-engine")]
+    pub qualia_f32: Box<[QualiaVector]>,
     pub meta: MetaColumn,
     pub temporal: Box<[u64]>,
     pub expert: Box<[u16]>,
@@ -306,6 +323,9 @@ impl BindSpace {
             fingerprints: FingerprintColumns::zeros(len),
             edges: EdgeColumn::zeros(len),
             qualia: QualiaI4Column::zeros(len),
+            // Lab bit-exact tenant: one QualiaVector ([f32; 17]) per row, zeroed.
+            #[cfg(feature = "with-engine")]
+            qualia_f32: vec![[0.0f32; 17]; len].into_boxed_slice(),
             meta: MetaColumn::zeros(len),
             temporal: vec![0u64; len].into_boxed_slice(),
             expert: vec![0u16; len].into_boxed_slice(),
@@ -314,6 +334,27 @@ impl BindSpace {
         }
     }
 
+    /// Read the lab bit-exact qualia tenant row (`with-engine` only).
+    ///
+    /// Returns the full-fidelity `[f32; 17]` qualia for `row` — the ground-truth
+    /// the i4 `qualia` column quantizes. Used by `unbind_busdto` so the BusDto
+    /// round-trip is bit-exact (the i4 column clamps to ±1 and would corrupt
+    /// `codebook_index` / energies).
+    #[cfg(feature = "with-engine")]
+    pub fn qualia_f32_row(&self, row: usize) -> &QualiaVector {
+        &self.qualia_f32[row]
+    }
+
+    /// Write the lab bit-exact qualia tenant row (`with-engine` only).
+    ///
+    /// Stores the full-fidelity `[f32; 17]`. The canonical i4 `qualia` column is
+    /// written separately (and stays the hot-path representation); this tenant is
+    /// additive lab ground-truth, never the production carrier.
+    #[cfg(feature = "with-engine")]
+    pub fn set_qualia_f32(&mut self, row: usize, q: &QualiaVector) {
+        self.qualia_f32[row] = *q;
+    }
+
     /// Attach a read-only ontology registry handle. Phase 7 (v4 plan).
     ///
     /// The registry is shared via `Arc` — multiple `BindSpace` instances and

crates/cognitive-shader-driver/src/engine_bridge.rs

@@ -32,6 +32,11 @@ use lance_graph_contract::cognitive_shader::{
 
 use crate::bindspace::{BindSpace, WORDS_PER_FP};
 use lance_graph_contract::qualia::QualiaI4_16D;
+// QUALIA_DIMS is referenced only inside `dispatch_busdto` (which is
+// `#[cfg(feature = "with-engine")]`); gate the import so default builds don't
+// warn on an unused import under clippy `-D warnings`.
+#[cfg(feature = "with-engine")]
+use lance_graph_contract::qualia::QUALIA_DIMS;
 
 #[cfg(feature = "with-engine")]
 use thinking_engine::dto::BusDto;
@@ -246,7 +251,7 @@ pub fn dispatch_busdto(bs: &mut BindSpace, row: usize, bus: &BusDto, style_ord:
     //     qualia[0]   = headline energy
     //     qualia[1..9] = top_k energies (positions 1-based to keep dim 0 = headline)
     //     qualia[9]   = codebook_index headline (codex P2 fix 2026-05-07)
-    //     qualia[10..18] = zeroed (reserved for downstream qualia / classification dist)
+    //     qualia[10..17] = zeroed (reserved for downstream qualia / classification dist)
     //
     // The codebook_index headline goes into qualia[9] explicitly so the
     // round-trip is bit-exact even when codebook_index collides with or
@@ -263,10 +268,15 @@ pub fn dispatch_busdto(bs: &mut BindSpace, row: usize, bus: &BusDto, style_ord:
     }
     q[9] = bus.codebook_index as f32;
     // D-CSV-5b: engine still produces f32; convert at the bridge boundary.
-    // from_f32_17d expects [f32; 17]; q is [f32; QUALIA_DIMS=18].
+    // from_f32_17d expects [f32; 17]; q is [f32; QUALIA_DIMS=17].
     let mut q17 = [0.0f32; 17];
     q17.copy_from_slice(&q[..17]);
+    // Canonical i4 column (hot-path representation; lossy — general qualia consumers).
     bs.qualia.set(row, QualiaI4_16D::from_f32_17d(&q17));
+    // Lab bit-exact tenant: store the full f32-17D so `unbind_busdto` round-trips
+    // exactly. The i4 column above clamps to ±1, which corrupts `codebook_index`
+    // (q[9]) and the energies — the D-CSV-5b regression this tenant repairs.
+    bs.set_qualia_f32(row, &q17);
 
     // [3] meta column — packed dispatch state.
     //     thinking = caller's style ordinal
@@ -339,8 +349,10 @@ pub fn unbind_busdto(bs: &BindSpace, row: usize) -> BusDto {
     // D-CSV-5b: bs.qualia is now QualiaI4Column; convert to f32 at the read site.
     // codex P2 fix (2026-05-07): the headline is stored explicitly in qualia[9]
     // at encode, so it round-trips bit-exact regardless of cycle-plane state.
-    let q_i4 = bs.qualia.row(row);
-    let q = q_i4.to_f32_17d(); // [f32; 17] — sufficient for dims 0..9
+    // Read the bit-exact f32 tenant — NOT the i4 `qualia` column, which clamps
+    // to ±1 and would corrupt codebook_index (q[9]) and the energies (the
+    // D-CSV-5b regression). The f32 tenant is the migration's exactness anchor.
+    let q = *bs.qualia_f32_row(row); // [f32; 17] — bit-exact ground-truth
     let energy = q[0];
     let codebook_index = q[9] as u16;
     let mut top_k = [(0u16, 0.0f32); 8];

crates/cognitive-shader-driver/tests/busdto_bridge_test.rs

@@ -287,3 +287,33 @@ fn busdto_mailbox_arm_recovers_headline_only_nonheadline_idx_zero() {
     assert_eq!(recovered.cycle_count, 5);
     assert_eq!(recovered.converged, true);
 }
+
+/// C8 (truth-architect addendum) — headline `codebook_index` round-trips
+/// bit-exact across the full u16 corner corpus, on BOTH builds.
+///
+/// The fix stores `codebook_index` in the **f32 qualia tenant** (`q[9]`); f32
+/// represents every integer in `[0, 2^24]` exactly, so every u16 survives. The
+/// corner values pin the regression boundaries: `255→256` is where
+/// `MetaWord.nars_f = codebook_index & 0xFF` aliases (a future refactor that
+/// reconstructed the headline from `nars_f` would collapse 256/512/0), and
+/// `65535` is the u16 max. The i4 column this tenant supersedes clamped every
+/// value ≥ 1 to 1 — this test is the proof that the f32 tenant repairs it.
+#[test]
+fn busdto_codebook_index_corner_corpus_round_trips_bit_exact() {
+    for &idx in &[0u16, 255, 256, 1234, 4095, 65535] {
+        let mut bs = BindSpace::zeros(1);
+        let bus = BusDto {
+            codebook_index: idx,
+            energy: 0.5,
+            top_k: [(idx, 0.5); 8],
+            cycle_count: 1,
+            converged: true,
+        };
+        dispatch_busdto(&mut bs, 0, &bus, 0);
+        let recovered = unbind_busdto(&bs, 0);
+        assert_eq!(
+            recovered.codebook_index, idx,
+            "codebook_index {idx} must round-trip bit-exact via the f32 qualia tenant",
+        );
+    }
+}