fix(materialize): resolve PR #515 review — free_energy primary, rest needs low F

Six review findings on the F→34→F loop, all valid:

1/4 select_tactic: free_energy is now the SOLE primary axis (mechanism
    band), with dissonance demoted to a +1 tie-weight toward inference
    tactics. The prior `dissonance >= 0.5` short-circuit overrode the
    surprise-chosen mechanism, breaking the module's own materialization
    criterion for any contradicted base. Mechanism match now scores +5 so
    it strictly outweighs bucket(2)+tier(1)+reconcile(1).
2   materialize: settle/attend (sd↓, dissonance↓, confidence↑) now apply
    ONLY on a tactic that actually fired — a blocked tactic must not fake
    progress; the loop ends rather than spin on an unchanged state.
5   rest now requires gate FLOW AND surprise < HOMEOSTASIS_FLOOR — a cool
    gate with unresolved surprise is not rest. Added ATTEND_GAIN (0.35)
    so confidence rises each fired step, guaranteeing reported surprise
    descends (active inference), not just sd decay.
6   bounded Vec::with_capacity(max_steps.min(64)).
3   EPIPHANIES E-MATERIALIZED-AWARENESS-1 wording: "perturbing the
    awareness encoding" → "the surprise/free-energy signal"; rest
    condition corrected to FLOW && surprise<floor.

Tests: added a dissonance=0.7 regression (surprise stays causal under
contradiction); already_at_rest now sets confidence=0.95/dissonance=0.0
so the stricter rest condition holds. 6/6 green, clippy clean.

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

Author: claude

.claude/board/EPIPHANIES.md

@@ -3,9 +3,9 @@
 **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 awareness encoding 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 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 guaranteed** when the CollapseGate reaches FLOW (`sd<SD_FLOW`), because attending decays dispersion monotonically. "The shader can't resist the thinking" made literal.
+**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).
 

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

@@ -19,14 +19,15 @@
 //!
 //! ```text
 //! awareness state ──select_tactic──► one of the 34 ──run──► fold delta_conf
-//!        ▲                                                        │ settle gate (sd↓, dissonance↓)
+//!        ▲                                                        │ on fire: sd↓, dissonance↓, confidence↑
 //!        └────────────── recompute free-energy ◄──────────────────┘
-//!  rest when the CollapseGate enters FLOW (sd < SD_FLOW) — surprise resolved.
+//!  rest when the CollapseGate is in FLOW (sd < SD_FLOW) AND surprise < floor.
 //! ```
 //!
 //! Awareness is not *read by* a controller that decides to think; it *is* the
-//! gradient that selects the next tactic. The loop rests when the gate settles —
-//! guaranteed, because attending decays dispersion each fired step.
+//! gradient that selects the next tactic. The loop rests when the gate settles and
+//! surprise is resolved — guaranteed for a firing chain, because attending decays
+//! both dispersion and surprise each fired step.
 //!
 //! Zero-dep, deterministic, offline-tested. This is the reduction-to-practice for
 //! the 2³-rung → NARS-candidate → 34-tactic doctrine; persisting the dispatch trace
@@ -47,6 +48,11 @@ pub const HOMEOSTASIS_FLOOR: f32 = 0.2;
 const SETTLE_SD: f32 = 0.85;
 /// Per-fired-step contradiction relaxation — engaging a tactic reconciles split.
 const SETTLE_DISSONANCE: f32 = 0.6;
+/// Per-fired-step confidence gain — attending to a tactic moves confidence toward
+/// 1 (active inference: engaging the world resolves uncertainty). Without it, a
+/// fired tactic with zero `delta_conf` would leave surprise pinned and the loop
+/// could ride `sd` decay alone; this guarantees reported surprise also descends.
+const ATTEND_GAIN: f32 = 0.35;
 
 /// Re-derive the CollapseGate state from dispersion (`ThoughtCtx::gate_state` is
 /// private; the thresholds `SD_FLOW`/`SD_BLOCK` are public).
@@ -69,16 +75,20 @@ fn gate_of(sd: f32) -> GateState {
 /// `rung` (depth → difficulty tier) are secondary modulators. Deterministic; scores
 /// every recipe by metadata match and takes the lowest id on a tie.
 pub fn select_tactic(ctx: &ThoughtCtx) -> u8 {
-    // What kind of reasoning does this awareness state call for?
-    let want_mech = if ctx.dissonance >= 0.5 {
-        Mechanism::TruthAwareInference // a contradiction wants revision/abduction
-    } else if ctx.free_energy >= 0.66 {
+    // PRIMARY: what kind of reasoning does the surprise level call for? `free_energy`
+    // alone picks the mechanism — this is the causal axis (the materialization
+    // criterion). It is NOT overridden by any other field; a contradicted state with
+    // low surprise still wants routine work, and high surprise still wants a leap.
+    let want_mech = if ctx.free_energy >= 0.66 {
         Mechanism::StructuralDivergence // high surprise wants a creative leap
     } else if ctx.free_energy >= 0.33 {
         Mechanism::TruthAwareInference // mid surprise wants inference
     } else {
         Mechanism::ParallelIndependence // low surprise: routine parallel work
     };
+    // SECONDARY: a contradiction nudges toward revision/abduction, but only as a
+    // tie-weight — it never replaces the surprise-chosen mechanism.
+    let wants_reconciliation = ctx.dissonance >= 0.5;
     // Where should it execute? (the gate picks the hardware bucket)
     let want_bucket = match gate_of(ctx.sd) {
         GateState::Block => Bucket::Gate,
@@ -99,15 +109,20 @@ pub fn select_tactic(ctx: &ThoughtCtx) -> u8 {
     for id in 1..=34u8 {
         if let Some(r) = recipe(id) {
             let mut score = 0;
+            // Primary mechanism match outweighs bucket(2) + tier(1) + reconcile(1).
             if r.mechanism == want_mech {
-                score += 3;
+                score += 5;
             }
             if r.bucket == want_bucket {
                 score += 2;
             }
             if r.tier == want_tier {
                 score += 1;
             }
+            // Secondary contradiction signal: a faint pull toward inference tactics.
+            if wants_reconciliation && r.mechanism == Mechanism::TruthAwareInference {
+                score += 1;
+            }
             if score > best_score {
                 best_score = score;
                 best_id = id;
@@ -150,34 +165,50 @@ pub struct Trace {
     pub final_free_energy: f32,
 }
 
-/// **The closed `F → 34 → F` loop.** Each step: if the gate is in FLOW the loop
-/// rests (surprise resolved); else select a tactic from the awareness state, run it
-/// (folding `delta_conf` into confidence), settle the gate (dispersion + contradiction
-/// decay — attending reconciles), and recompute surprise. `max_steps` bounds the run;
-/// rest is *guaranteed* within `~log_{1/SETTLE_SD}(sd/SD_FLOW)` fired steps because
-/// dispersion decays monotonically into FLOW.
+/// **The closed `F → 34 → F` loop.** Each step: recompute surprise; if the gate is
+/// in FLOW *and* surprise fell below [`HOMEOSTASIS_FLOOR`] the loop rests; else select
+/// a tactic from the awareness state and run it. A tactic that *fired* settles the
+/// gate (dispersion + contradiction decay) and raises confidence ([`ATTEND_GAIN`],
+/// active inference); a *blocked* tactic changes nothing, so the loop stops rather
+/// than spin on an unchanged state. `max_steps` bounds the run; for a firing chain,
+/// rest is reached within `~log_{1/SETTLE_SD}(sd/SD_FLOW)` steps because dispersion
+/// and surprise decay monotonically.
 pub fn materialize(ctx: &mut ThoughtCtx, max_steps: usize) -> Trace {
-    let mut steps = Vec::with_capacity(max_steps);
+    // Bound the up-front allocation: a settling run is short (~log decay), so don't
+    // reserve for a pathological `max_steps` the loop will never reach.
+    let mut steps = Vec::with_capacity(max_steps.min(64));
     for _ in 0..max_steps {
-        if gate_of(ctx.sd) == GateState::Flow {
+        ctx.free_energy = recompute_free_energy(ctx);
+        // Rest only when the gate is in FLOW *and* surprise actually resolved — a
+        // cool gate with residual surprise is not rest, it must keep dispatching.
+        if gate_of(ctx.sd) == GateState::Flow && ctx.free_energy < HOMEOSTASIS_FLOOR {
             break; // settled — the shader rests
         }
         let id = select_tactic(ctx);
         let Some(tactic) = kernel(id) else {
             break; // unreachable: id is always 1..=34
         };
         let out = tactic.run(ctx); // folds out.delta_conf into ctx.confidence
-        ctx.sd *= SETTLE_SD; // attending settles dispersion → toward FLOW
-        ctx.dissonance *= SETTLE_DISSONANCE;
-        ctx.free_energy = recompute_free_energy(ctx);
+        if out.fired {
+            // Only a tactic that actually fired settles the gate and resolves
+            // surprise — a blocked tactic changed nothing, so don't fake progress.
+            ctx.sd *= SETTLE_SD; // attending settles dispersion → toward FLOW
+            ctx.dissonance *= SETTLE_DISSONANCE;
+            ctx.confidence =
+                (ctx.confidence + ATTEND_GAIN * (1.0 - ctx.confidence)).clamp(0.0, 1.0);
+        }
         steps.push(Step {
             tactic_id: id,
             fired: out.fired,
             delta_conf: out.delta_conf,
         });
+        if !out.fired {
+            break; // a blocked tactic won't unblock on re-dispatch of the same state
+        }
     }
+    ctx.free_energy = recompute_free_energy(ctx);
     Trace {
-        rested: gate_of(ctx.sd) == GateState::Flow,
+        rested: gate_of(ctx.sd) == GateState::Flow && ctx.free_energy < HOMEOSTASIS_FLOOR,
         final_confidence: ctx.confidence,
         final_free_energy: ctx.free_energy,
         steps,
@@ -219,6 +250,15 @@ mod tests {
             awareness_is_causal(&b, 0.1, 0.9),
             "free_energy must steer dispatch — else awareness is a dead label"
         );
+        // Regression: surprise stays causal even for a contradicted base. dissonance
+        // is a SECONDARY tie-weight, not an override — it must not pin the mechanism
+        // and erase free_energy's steering (the bug review #515 caught).
+        let mut contradicted = base();
+        contradicted.dissonance = 0.7;
+        assert!(
+            awareness_is_causal(&contradicted, 0.1, 0.9),
+            "free_energy must steer dispatch even under contradiction"
+        );
         // Sweep free_energy: dispatch must take ≥ 2 distinct tactics (not stuck).
         let ids: BTreeSet<u8> = (0..=10)
             .map(|i| {
@@ -314,9 +354,13 @@ mod tests {
 
     #[test]
     fn already_at_rest_dispatches_nothing() {
-        // FLOW on entry (sd < SD_FLOW) ⇒ no surprise ⇒ no dispatch (the shader rests).
+        // FLOW on entry (sd < SD_FLOW) AND resolved surprise ⇒ no dispatch (rest).
+        // Rest now requires free_energy < floor, so the base must be confident and
+        // uncontradicted as well as gate-cool — a cool gate alone is not rest.
         let mut c = base();
         c.sd = 0.05;
+        c.confidence = 0.95;
+        c.dissonance = 0.0;
         let trace = materialize(&mut c, 64);
         assert!(trace.rested && trace.steps.is_empty());
     }