feat(driver): materialized-awareness provenance wire (provenance-only, cycle untouched)

Wires the materialize F→34→F loop + ndarray HHTL fork_decision into the live
cognitive-shader-driver cycle as a SIDE analysis. Per operator decision
2026-06-17: provenance-only — the gate/emit/persistence path is byte-for-byte
unchanged; the analysis only records what the 34 would dispatch and whether the
leaf residue forks.

- contract: MaterializeProvenance (primitive-only Copy: first_tactic/steps/
  rested/final_free_energy/fork:u8) as a new ShaderCrystal field; fork is
  ForkAction-as-u8 so the zero-dep crate doesn't import ndarray.
- driver: materialize_provenance() builds a ThoughtCtx from the cycle's own
  observables (sd←std_dev exact, confidence←1−F, dissonance←|felt−demonstrated|
  DK gap), runs materialize, and computes fork_decision. The fork challenge is a
  std_dev dispersion proxy (CONJECTURE) with a std_dev-calibrated floor/σ —
  pending the real orthogonal CoarseResidue magnitude + real HHTL cascade depth
  (depth==max⇒leaf for now).
- tests: confident cycle→Commit, scattered low-skill→ForkDomain; dispatch
  populates provenance (first_tactic==0 = at-rest case). 638 contract lib +
  driver tests green.

Board: LATEST_STATE contract inventory + EPIPHANIES E-MATERIALIZED-AWARENESS-2
(the four-vocabulary unification grounded in shipped types).

Co-Authored-By: Claude <noreply@anthropic.com>

Author: claude

.claude/board/EPIPHANIES.md

@@ -1,3 +1,11 @@
+## 2026-06-17 — E-MATERIALIZED-AWARENESS-2 — the driver wire is live (provenance-only); the four vocabularies are one 2-axis structure
+
+**Status:** FINDING (shipped on branch `claude/materialize-awareness-f34-loop`): the `cognitive-shader-driver` now runs the `materialize` F→34→F loop + the ndarray HHTL `fork_decision` as a **side analysis** per cycle, recording `MaterializeProvenance` on `ShaderCrystal`. **Provenance-only — the gate/emit/persistence path is byte-for-byte unchanged** (operator decision 2026-06-17). 2 driver tests + 638 contract lib green.
+
+**The unification, now grounded in shipped types.** The entropy×energy `Quadrant`, Csikszentmihalyi's `mul::FlowState(challenge,skill)`, Friston model-vs-surprise, and the Staunen↔Wisdom ladder are **one 2-axis structure**. CHALLENGE = surprise (`free_energy` / orthogonal leaf-residue magnitude); SKILL = engagement (`confidence`+`ATTEND_GAIN` / in-domain codebook capacity). The driver's observable→`ThoughtCtx` mapping is faithful (sd←std_dev exact, confidence←1−F = the driver's own `demonstrated_competence`, dissonance←|felt−demonstrated| = the Dunning-Kruger gap). The HHTL fork is the **anxiety escape**: Anxiety (challenge≫skill) at leaf → `ForkDomain` (mint a new classid = Friston model-switch); Flow → resolve in-domain; Boredom → Commit. Cross-repo: ndarray ships the fork math (PR #221 merged, `entropy_ladder::{residue_surprise, fork_decision, ForkAction}`), lance-graph drives it.
+
+**[H]/[S] joints (unchanged from E-…-1, now with the wire built):** the fork challenge is a **`std_dev` dispersion proxy (CONJECTURE)** with a std_dev-calibrated floor/σ — the real orthogonal `CoarseResidue` magnitude is not yet surfaced into the cycle; HHTL cascade depth is stubbed `depth==max⇒leaf`; the σ-threshold awaits a Jirak-derived bound (`I-NOISE-FLOOR-JIRAK`). Promoting these to [G] = the next gated wire (surface real residue + cascade depth; optionally let the provenance feed a future gate path once measured to help).
+
 ## 2026-06-16 — E-MATERIALIZED-AWARENESS-1 — awareness materializes iff it is *causal in dispatch*; the closed `F→34→F` loop is the reduction-to-practice (and the falsifier)
 
 **Status:** FINDING for the criterion + loop (reduction-to-practice **shipped**: `lance-graph-contract::materialize`, 6 tests green, zero-dep/offline). The broader "this is the system's awareness" reading stays **[NOVEL — probe-gated]**: no prior art by construction (ours — the 2³-rung→NARS-candidate→34-tactic dispatch loop), validity established by the perturbation probe, not citation.

.claude/board/LATEST_STATE.md

@@ -319,6 +319,16 @@ the contract. This file exists to prevent that.
 | **#269** | 2026-04-26 | feat: Distance trait + SIMD Hamming/cosine wiring + PaletteDistanceTable + Dockerfile docs | Distance trait; SIMD Hamming/cosine wiring; PaletteDistanceTable 128KB; Dockerfile.md |
 
 
+---
+
+## 2026-06-17 — Append: materialized-awareness driver wire (provenance-only) on branch claude/materialize-awareness-f34-loop
+
+(Per APPEND-ONLY rule: new top-of-inventory entry.)
+
+### Current Contract Inventory — new entry
+
+**`lance-graph-contract::cognitive_shader::MaterializeProvenance`** (new type, 2026-06-17): primitive-only Copy record (`first_tactic:u8`, `steps:u16`, `rested:bool`, `final_free_energy:f32`, `fork:u8`) added as a field on `ShaderCrystal`. The `cognitive-shader-driver` runs the `materialize` F→34→F loop **and** the ndarray HHTL `fork_decision` as a **side analysis** over each cycle's already-computed observables (`free_energy`, `std_dev`, MUL, per-hit resonances) and records the outcome here. **Provenance-only — does NOT alter `bus.gate` or persistence** (operator decision 2026-06-17: cycle untouched). Observable→`ThoughtCtx` mapping is faithful (sd←std_dev, confidence←1−F, dissonance←|felt−demonstrated| DK gap); the fork's challenge is a **`std_dev` dispersion proxy (CONJECTURE)** with a std_dev-calibrated floor/σ, pending the real orthogonal `CoarseResidue` magnitude from the codec path and real HHTL cascade depth (depth==max⇒leaf for now). Driver helper `materialize_provenance(...)`; 2 driver tests (confident→Commit, scattered→ForkDomain; dispatch populates provenance) + the ndarray fork ladder (PR #221, merged). `fork:u8` = `ForkAction` (0 Commit /1 DescendDeeper /2 ForkBasin /3 ForkDomain). Note: `cognitive-shader-driver` is not in the default-workspace clippy member set. See `EPIPHANIES.md` E-MATERIALIZED-AWARENESS-1.
+
 ---
 
 ## 2026-06-16 — Append: `contract::materialize` shipped (branch claude/materialize-awareness-f34-loop)

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

@@ -31,16 +31,19 @@ use causal_edge::pearl::CausalMask;
 use causal_edge::plasticity::PlasticityState;
 use causal_edge::tables::{unpack_c, unpack_f, NarsTables};
 use lance_graph_contract::cognitive_shader::{
-    AlphaComposite, CognitiveShaderDriver, EmitMode, MetaSummary, NullSink, ShaderBus,
-    ShaderCrystal, ShaderDispatch, ShaderHit, ShaderResonance, ShaderSink, ALPHA_COMPOSITE_DIMS,
+    AlphaComposite, CognitiveShaderDriver, EmitMode, MaterializeProvenance, MetaSummary, NullSink,
+    ShaderBus, ShaderCrystal, ShaderDispatch, ShaderHit, ShaderResonance, ShaderSink,
+    ALPHA_COMPOSITE_DIMS,
 };
 use lance_graph_contract::collapse_gate::{GateDecision, MergeMode, ALPHA_SATURATION_THRESHOLD};
 use lance_graph_contract::grammar::free_energy::{FreeEnergy, EPIPHANY_MARGIN};
 use lance_graph_contract::grammar::inference::NarsInference;
 use lance_graph_contract::grammar::thinking_styles::{
     GrammarStyleAwareness, ParamKey, ParseOutcome,
 };
+use lance_graph_contract::materialize::materialize;
 use lance_graph_contract::mul::{MulAssessment, MulThresholdProfile, SituationInput};
+use lance_graph_contract::recipe_kernels::ThoughtCtx;
 use lance_graph_contract::thinking::ThinkingStyle;
 use p64_bridge::cognitive_shader::CognitiveShader;
 
@@ -484,6 +487,7 @@ impl ShaderDriver {
                 },
                 persisted_row: None,
                 meta: MetaSummary::default(),
+                materialize: MaterializeProvenance::default(),
                 alpha_composite,
             };
         }
@@ -500,6 +504,7 @@ impl ShaderDriver {
                 bus,
                 persisted_row: None,
                 meta: MetaSummary::default(),
+                materialize: MaterializeProvenance::default(),
                 alpha_composite,
             };
         }
@@ -518,6 +523,19 @@ impl ShaderDriver {
             _ => None,
         };
 
+        // Materialized-awareness provenance — runs the F→34→F loop + HHTL fork as
+        // a SIDE analysis over this cycle's observables. Provenance-only: it has
+        // NOT influenced `gate` above and does not influence persistence; it only
+        // records "what the 34 would dispatch and whether the leaf residue forks".
+        let candidate_resonances: Vec<f32> = hits.iter().map(|h| h.resonance).collect();
+        let materialize_prov = materialize_provenance(
+            &free_energy,
+            std_dev,
+            top_resonance,
+            awareness_skill,
+            &candidate_resonances,
+        );
+
         // [8] NARS revision — phi-1 humility ceiling.
         //     System observes its own outcome and revises per-style awareness.
         //     This is what makes the cognitive loop close: every cycle updates
@@ -545,6 +563,7 @@ impl ShaderDriver {
             bus,
             persisted_row,
             meta,
+            materialize: materialize_prov,
             alpha_composite,
         };
         sink.on_crystal(&crystal);
@@ -772,6 +791,66 @@ fn entropy_std(hits: &[ShaderHit]) -> (f32, f32) {
     (ent, var.sqrt())
 }
 
+/// Run the materialized-awareness analysis *alongside* the cycle — provenance
+/// only, never alters the gate. Builds a `ThoughtCtx` from the cycle's
+/// already-computed observables, runs the F→34→F loop, and computes the HHTL
+/// fork action from a dispersion proxy (CONJECTURE pending the real orthogonal
+/// `CoarseResidue` magnitude from the codec path).
+///
+/// Observable → `ThoughtCtx` mapping (faithful to fields the cycle already builds):
+/// - `free_energy` ← `F.total` (surprise)
+/// - `sd`          ← `std_dev` (CollapseGate dispersion — exact)
+/// - `confidence`  ← `1 - F.total` (the driver's own `demonstrated_competence`)
+/// - `dissonance`  ← `|top_resonance - (1 - F.total)|` (the Dunning-Kruger gap:
+///   what the cycle *feels* vs what it has *demonstrated*)
+/// - `temperature` ← `std_dev` clamp (spread ⇒ explore; proxy)
+/// - `rung`        ← `1` (no HHTL cascade depth surfaced in this cycle; proxy)
+fn materialize_provenance(
+    free_energy: &FreeEnergy,
+    std_dev: f32,
+    top_resonance: f32,
+    awareness_skill: f64,
+    candidate_resonances: &[f32],
+) -> MaterializeProvenance {
+    let demonstrated = (1.0 - free_energy.total).clamp(0.0, 1.0);
+    let mut ctx = ThoughtCtx::new(candidate_resonances.to_vec());
+    ctx.free_energy = free_energy.total.clamp(0.0, 1.0);
+    ctx.sd = std_dev;
+    ctx.confidence = demonstrated;
+    ctx.dissonance = (top_resonance.clamp(0.0, 1.0) - demonstrated)
+        .abs()
+        .clamp(0.0, 1.0);
+    ctx.temperature = std_dev.clamp(0.0, 1.0);
+    ctx.rung = 1;
+
+    let trace = materialize(&mut ctx, 64);
+
+    // HHTL fork: `std_dev` (dispersion) is the CONJECTURE residue-magnitude proxy
+    // until the real orthogonal `CoarseResidue` is surfaced into the cycle. The
+    // floor/sigma_k are calibrated to std_dev's ~[0.05, 0.35] working range (NOT
+    // the codec's NOISE_FLOOR), so a confident low-spread cycle reads as low
+    // challenge (Commit) and a scattered one as high (fork). `depth == max_depth`
+    // treats the read as a leaf, so ForkDomain is reachable when skill is short.
+    const STD_DEV_RESIDUE_FLOOR: f64 = 0.05;
+    const STD_DEV_RESIDUE_SIGMA_K: f64 = 6.0;
+    let fork = ndarray::hpc::entropy_ladder::fork_decision(
+        std_dev as f64,
+        awareness_skill,
+        1,
+        1,
+        STD_DEV_RESIDUE_FLOOR,
+        STD_DEV_RESIDUE_SIGMA_K,
+    ) as u8;
+
+    MaterializeProvenance {
+        first_tactic: trace.steps.first().map(|s| s.tactic_id).unwrap_or(0),
+        steps: trace.steps.len() as u16,
+        rested: trace.rested,
+        final_free_energy: trace.final_free_energy,
+        fork,
+    }
+}
+
 #[allow(dead_code)]
 fn collapse_gate(sd: f32) -> GateDecision {
     // Matches thinking_engine::cognitive_stack::{SD_FLOW_THRESHOLD, SD_BLOCK_THRESHOLD}.
@@ -924,6 +1003,67 @@ mod tests {
         assert_eq!(crystal.bus.resonance.style_ord, auto_style::ANALYTICAL);
     }
 
+    #[test]
+    fn dispatch_populates_materialize_provenance() {
+        let bs = Arc::new(demo_bindspace());
+        let sr = Arc::new(demo_semiring());
+        let driver = CognitiveShaderBuilder::new()
+            .bindspace(bs)
+            .semiring(sr)
+            .planes(demo_planes())
+            .build();
+        let req = ShaderDispatch {
+            rows: ColumnWindow::new(0, 4),
+            meta_prefilter: MetaFilter::ALL,
+            layer_mask: 0xFF,
+            radius: u16::MAX,
+            style: StyleSelector::Ordinal(auto_style::ANALYTICAL),
+            ..Default::default()
+        };
+        let crystal = driver.dispatch(&req);
+        let m = crystal.materialize;
+        // Sane provenance. `first_tactic == 0` is the legitimate "already at rest,
+        // nothing dispatched" case (this demo cycle is confident → settles at once);
+        // any dispatched step must name a real tactic.
+        assert!(
+            m.first_tactic <= 34,
+            "tactic id in 0..=34, got {}",
+            m.first_tactic
+        );
+        if m.steps > 0 {
+            assert!(
+                (1..=34).contains(&m.first_tactic),
+                "a dispatched step must name a real tactic, got {}",
+                m.first_tactic
+            );
+        }
+        assert!(
+            m.fork <= 3,
+            "fork action is a valid ForkAction u8, got {}",
+            m.fork
+        );
+        assert!(m.final_free_energy.is_finite() && (0.0..=1.0).contains(&m.final_free_energy));
+    }
+
+    #[test]
+    fn materialize_provenance_confident_commits_scattered_forks() {
+        // Confident cycle: high resonance, low dispersion, ample skill → Boredom →
+        // Commit (fork 0). The leaf residue is small, the domain over-explains.
+        let fe_lo = FreeEnergy::compose(0.95, 0.05);
+        let confident = materialize_provenance(&fe_lo, 0.05, 0.95, 0.9, &[0.95, 0.9, 0.88]);
+        assert_eq!(confident.fork, 0, "confident cycle commits (no fork)");
+
+        // Scattered cycle: low resonance, high dispersion, short skill → Anxiety at
+        // leaf → ForkDomain (fork 3): the orthogonal leaf residue is strong enough
+        // that free energy forks into a new domain.
+        let fe_hi = FreeEnergy::compose(0.3, 0.4);
+        let scattered = materialize_provenance(&fe_hi, 0.4, 0.3, 0.1, &[0.3, 0.28, 0.31]);
+        assert_eq!(
+            scattered.fork, 3,
+            "scattered low-skill cycle forks to a new domain"
+        );
+    }
+
     #[test]
     fn dispatch_with_prefilter_excludes_rows() {
         let bs = Arc::new(demo_bindspace());

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

@@ -1470,6 +1470,7 @@ mod tests {
                 brier: 0.1,
                 should_admit_ignorance: false,
             },
+            materialize: Default::default(),
             alpha_composite: None,
         };
         let wire = WireCrystal::from(&crystal);

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

@@ -382,6 +382,9 @@ pub struct ShaderCrystal {
     pub persisted_row: Option<u32>,
     /// Meta assessment (Brier, confidence, should_admit_ignorance).
     pub meta: MetaSummary,
+    /// Provenance of the side-run materialized-awareness analysis (the 34-tactic
+    /// dispatch + HHTL fork). Provenance-only: does not affect `bus.gate`.
+    pub materialize: MaterializeProvenance,
     /// Pillar-7 α-front-to-back composite, populated only when stage [7]
     /// dispatched on `MergeMode::AlphaFrontToBack`. `None` for the
     /// existing top-K aggregation modes (Bundle / Xor / Superposition).
@@ -397,6 +400,34 @@ pub struct MetaSummary {
     pub should_admit_ignorance: bool,
 }
 
+/// Provenance of the materialized-awareness analysis run *alongside* the cycle.
+///
+/// **Provenance-only — does NOT alter the gate/emit decision.** The driver runs
+/// the `materialize` F→34→F loop and the HHTL `fork_decision` as a side analysis
+/// over the cycle's already-computed observables (`free_energy`, dispersion, MUL),
+/// then records the outcome here. It answers "which of the 34 would this awareness
+/// state dispatch, would the loop settle, and would the leaf residue fork to a new
+/// domain" without changing hot-path semantics. Primitive-only so the contract
+/// crate stays zero-dep (`fork` is `ForkAction as u8`, not the ndarray enum).
+///
+/// A zeroed value (`first_tactic == 0`) means the analysis did not run for this
+/// cycle (e.g. a sink-aborted early return).
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct MaterializeProvenance {
+    /// Tactic id (1..=34) the awareness state dispatched first; `0` = not run.
+    pub first_tactic: u8,
+    /// Dispatch steps the F→34→F loop took before settling (or hitting the cap).
+    pub steps: u16,
+    /// Did the loop settle into rest (gate FLOW and surprise below the floor)?
+    pub rested: bool,
+    /// Residual free energy at rest.
+    pub final_free_energy: f32,
+    /// HHTL fork action as `u8` (0 Commit, 1 DescendDeeper, 2 ForkBasin,
+    /// 3 ForkDomain). CONJECTURE: the challenge is a dispersion (std_dev) proxy,
+    /// pending the real orthogonal `CoarseResidue` magnitude from the codec path.
+    pub fork: u8,
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // ShaderSink — EmbedAnything commit-adapter pattern
 // ═══════════════════════════════════════════════════════════════════════════
@@ -501,6 +532,7 @@ mod tests {
             bus: ShaderBus::empty(),
             persisted_row: None,
             meta: MetaSummary::default(),
+            materialize: MaterializeProvenance::default(),
             alpha_composite: None,
         });
     }