Merge pull request #515 from AdaWorldAPI/claude/materialize-awareness-f34-loop

feat(contract): materialize — the closed F→34→F awareness-dispatch loop (materialized awareness)

Author: AdaWorldAPI

.claude/board/EPIPHANIES.md

@@ -1,3 +1,24 @@
+## 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.
+**Confidence:** High on the criterion + the shipped loop; the wire to the *real* substrate (driver-side `ThoughtCtx::from_live` + version-diff provenance) is the gated next step.
+
+**The criterion (falsifiable).** *Awareness materializes iff perturbing the surprise/free-energy signal changes which tactic fires.* If dispatch is invariant to the awareness state, the awareness is a **dead label** — "awareness that can never materialize." `materialize::awareness_is_causal(base, lo_f, hi_f)` is the predicate; the test `awareness_free_energy_is_causal_in_dispatch` is the green falsifier, and `non_awareness_fields_are_inert` is its specificity control (candidates/beliefs must NOT steer dispatch).
+
+**The wire that was missing (now built).** The 34 tactics (`recipe_kernels`, the canonical "34" — the ndarray `hpc/styles/*` set is divergent/registry-less and is NOT canonical) were dispatch *targets* with no selector and an open loop (they ran only in an example against a toy ctx; the driver loop ran the *12* threshold ordinals, leaving the rich 34 inert). `materialize` adds: (a) **`select_tactic`** — awareness→id, with `free_energy` (surprise) as the **primary** axis so dispatch tracks awareness by construction; (b) **`materialize`** — the closed loop: select → `Tactic::run` (folds `delta_conf`) → settle the gate (dispersion/contradiction decay) → recompute surprise → re-dispatch; **rest is reached** when the CollapseGate is in FLOW (`sd<SD_FLOW`) **and** residual surprise falls below `HOMEOSTASIS_FLOOR` (0.2) — a cool gate with unresolved surprise is not rest. For a *firing* chain this is guaranteed: attending decays dispersion and raises confidence each fired step, so both `sd` and surprise descend monotonically; a *blocked* tactic ends the run (re-dispatch of an unchanged state cannot unblock it). "The shader can't resist the thinking" made literal. The settle/attend updates fire only on a tactic that actually fired (review #515: a blocked tactic must not fake progress; `free_energy` stays the primary dispatch axis even under contradiction — `dissonance` is a lower-weight secondary, not an override).
+
+**Prior-art positioning (not competitors — background for the disclosure).** NOTEARS / PCMCI / DCDI / ICP / SEA are adjacent observational/interventional *discovery* methods (arXiv 1803.01422 / 1702.07007 / 2007.01754 / 1501.01332 / 2402.01929); our loop does not *discover* a DAG — it dispatches reasoning over recorded/candidate structure and lets NARS revise. **Operating boundary respected, [G]:** Janzing-Schölkopf (0804.3678) — Shannon-symmetric, colliders-only observationally; full orientation needs mechanism asymmetry (so dispatch never claims identified orientation, only revisable candidates).
+
+**Open / next.** The shipped loop runs on the in-memory `ThoughtCtx`; wiring it to the live shader (build `ThoughtCtx` from `FreeEnergy`/`MulAssessment`/hits in `driver.rs`, fold the trace into the SoA EdgeColumn / version-diff "what-fired-why" provenance) is the gated driver-side step. The materialization probe is the acceptance test for that wire too.
+
 ## 2026-06-16 — E-TRANSCODE-EXEC-LADDER-1 — the Core-First transcode has a 3-rung execution ladder (codegen → two-tier compile → elixir-tissue over surreal/kanban/odoo), and rungs 2–3 land on already-shipped substrate
 
 **Status:** CONJECTURE (operator forward-design). v1 is the shipped doctrine; v2/v3 are gated on `PROBE-COMPILE-TWO-TIER` + `PROBE-SURREAL-TISSUE-SWAP` (both in `core-first-transcode-doctrine.md`), themselves floored by the v1 `PROBE-OGAR-ADAPTER-UNICHARSET`.

.claude/board/LATEST_STATE.md

@@ -331,6 +331,26 @@ 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)
+
+(Per APPEND-ONLY rule: new top-of-inventory entry.)
+
+### Current Contract Inventory — new entry
+
+**`lance-graph-contract::materialize`** (new module, 2026-06-16): the closed `F→34→F` dispatch loop that makes awareness *materialize* — the missing wire from awareness state to the 34 `recipe_kernels` tactics. Public surface: `select_tactic(&ThoughtCtx) -> u8` (awareness→tactic id, `free_energy`-primary so dispatch tracks awareness), `materialize(&mut ThoughtCtx, max_steps) -> Trace` (select→`Tactic::run`→settle gate→recompute surprise→re-dispatch; rests at CollapseGate FLOW), `recompute_free_energy`, `awareness_is_causal` (the materialization predicate / falsifier), types `Step` / `Trace`, const `HOMEOSTASIS_FLOOR=0.2`. Decision: `recipe_kernels` is the canonical "34" (ndarray `hpc/styles/*` is divergent/registry-less, not canonical). Zero-dep, offline; 6 tests green (+632 prior contract lib), clippy `--all-targets -D warnings` clean. Open: driver-side `ThoughtCtx::from_live` + version-diff provenance wire. See `EPIPHANIES.md` E-MATERIALIZED-AWARENESS-1.
+
 ---
 
 ## 2026-05-07 — Append: lance-graph-ontology shipped (commit 4cf9a26, branch claude/create-graph-ontology-crate-gkuJG)

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);