@mindot/will 0.8.0 → 0.10.0

package/src/cognition/cache/deliberation.cache.ts

@@ -0,0 +1,219 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/cache/deliberation.cache.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * DeliberationCache — deterministic fast-path for executive reasoning.
+ *
+ * Stores past (fingerprint, output) pairs and composes a new output by
+ * interpolating neighbors of the *query* fingerprint. Pure, R2-safe, bounded.
+ *
+ * Determinism discipline:
+ *   - Patterns live in a flat array; retrieval is a linear scan (k is small and
+ *     the array is bounded, so determinism beats micro-optimisation).
+ *   - The similarity that drives confidence, weighting and competence updates is
+ *     always computed against the query fingerprint the caller passes in — never
+ *     a self-similarity proxy.
+ *   - Sort keys are scalars; ties break on storedAtTick (older first).
+ *   - No hash maps over fingerprints, no Set iteration, no wall-clock, no RNG.
+ */
+
+import type { ExecutiveOutputFull } from '#faculties/executive.engine/types'
+import type { Tick } from '#core/types'
+import type {
+  DeliberationCacheConfig,
+  CachePattern,
+  CacheResult,
+  ScoredNeighbor,
+  DeliberationCacheSnapshot,
+} from './types'
+import { FINGERPRINT_VERSION, fingerprintSimilarity } from './fingerprint'
+import { composeOutput } from './composition'
+
+const DEFAULT_CONFIG: Required<DeliberationCacheConfig> = {
+  maxPatterns: 5000,
+  k: 5,
+  minSimilarity: 0.75,
+  theta: 0.70,
+  tau: 0.5,
+  eta: 0.1,
+  decayPerCycle: 0.999,
+  verifyEveryNHits: 5,
+  scopes: [ 'actions' ],
+}
+
+export class DeliberationCache {
+  readonly name = 'deliberation-cache'
+
+  private _patterns: CachePattern[] = []
+  private _config: Required<DeliberationCacheConfig>
+  private _hitCount = 0
+  private _missCount = 0
+  private _verifyCounter = 0
+
+  constructor( config: DeliberationCacheConfig = {} ){
+    this._config = { ...DEFAULT_CONFIG, ...config }
+  }
+
+  get size(): number { return this._patterns.length }
+  get hitCount(): number { return this._hitCount }
+  get missCount(): number { return this._missCount }
+
+  // ── Retrieval + composition ──────────────────────────────
+
+  /**
+   * Retrieve neighbors of `queryFp` and, if confident, compose an output.
+   * Confidence ρ = max over neighbors of (competence × similarity), per the
+   * research sketch §2.2 — a diffuse cloud of weak matches never triggers a hit.
+   */
+  retrieve( queryFp: Float32Array, _tick: Tick ): CacheResult {
+    const neighbors = this._retrieveNeighbors( queryFp )
+    if( neighbors.length === 0 ){
+      this._missCount++
+      return { output: null, confidence: 0, neighbors: [], hit: false }
+    }
+
+    let confidence = 0
+    for( const n of neighbors ){
+      const score = n.pattern.competence * n.similarity
+      if( score > confidence ) confidence = score
+    }
+
+    const hit = confidence >= this._config.theta
+    if( hit ) this._hitCount++
+    else this._missCount++
+
+    const output = hit
+      ? composeOutput( neighbors, this._config.tau, this._config.scopes )
+      : null
+
+    return { output, confidence, neighbors, hit }
+  }
+
+  /** Store a new (fingerprint, output) pair from the slow (LLM) path. */
+  learn( queryFp: Float32Array, output: ExecutiveOutputFull, tick: Tick ): void {
+    this._evictIfFull( tick )
+    this._patterns.push( {
+      fingerprint: new Float32Array( queryFp ),
+      output,
+      competence: 0.5,
+      storedAtTick: tick,
+      retrievalCount: 0,
+      successCount: 0,
+    } )
+  }
+
+  /**
+   * Update the competence of the pattern nearest to `queryFp`, from a reafference
+   * reward in [0,1]. Called after an action outcome is confirmed.
+   */
+  updateCompetence( queryFp: Float32Array, reward: number, _tick: Tick ): void {
+    const best = this._findBestMatch( queryFp )
+    if( !best ) return
+    const r = Math.max( 0, Math.min( 1, reward ) )
+    best.retrievalCount++
+    if( r > 0.5 ) best.successCount++
+    const a = this._config.eta
+    best.competence = Math.max( 0, Math.min( 1, best.competence * ( 1 - a ) + r * a ) )
+  }
+
+  /** Decay all competences one executive cycle. Slowly forgets stale patterns. */
+  decay(): void {
+    const f = this._config.decayPerCycle
+    if( f >= 1 ) return
+    for( const p of this._patterns ) p.competence *= f
+  }
+
+  /** Deterministic 1-in-N verify schedule. Increments a counter each call. */
+  shouldVerify(): boolean {
+    if( this._config.verifyEveryNHits <= 0 ) return false
+    this._verifyCounter++
+    return this._verifyCounter % this._config.verifyEveryNHits === 0
+  }
+
+  // ── Snapshot / restore (entity persistence + tests) ──────
+
+  snapshot(): DeliberationCacheSnapshot {
+    return {
+      version: FINGERPRINT_VERSION,
+      patterns: this._patterns.map( p => ( {
+        fingerprint: Array.from( p.fingerprint ),
+        output: p.output,
+        competence: p.competence,
+        storedAtTick: p.storedAtTick,
+        retrievalCount: p.retrievalCount,
+        successCount: p.successCount,
+      } ) ),
+      hitCount: this._hitCount,
+      missCount: this._missCount,
+      verifyCounter: this._verifyCounter,
+    }
+  }
+
+  restore( snap: DeliberationCacheSnapshot ): void {
+    // Version guard: a fingerprint layout change invalidates stored vectors.
+    if( snap.version !== FINGERPRINT_VERSION ) return
+    this._patterns = snap.patterns.map( p => ( {
+      fingerprint: new Float32Array( p.fingerprint ),
+      output: p.output,
+      competence: p.competence,
+      storedAtTick: p.storedAtTick,
+      retrievalCount: p.retrievalCount,
+      successCount: p.successCount,
+    } ) )
+    this._hitCount = snap.hitCount ?? 0
+    this._missCount = snap.missCount ?? 0
+    this._verifyCounter = snap.verifyCounter ?? 0
+  }
+
+  // ── Internal ─────────────────────────────────────────────
+
+  private _retrieveNeighbors( queryFp: Float32Array ): ScoredNeighbor[] {
+    const scored: ScoredNeighbor[] = []
+    for( const p of this._patterns ){
+      const similarity = fingerprintSimilarity( queryFp, p.fingerprint )
+      if( similarity >= this._config.minSimilarity )
+        scored.push( { pattern: p, similarity } )
+    }
+
+    // Rank by (similarity × competence) desc; ties → older pattern first.
+    scored.sort( ( a, b ) => {
+      const sa = a.similarity * a.pattern.competence
+      const sb = b.similarity * b.pattern.competence
+      if( sa !== sb ) return sb - sa
+      return a.pattern.storedAtTick - b.pattern.storedAtTick
+    } )
+
+    return scored.slice( 0, this._config.k )
+  }
+
+  private _findBestMatch( queryFp: Float32Array ): CachePattern | null {
+    let best: CachePattern | null = null
+    let bestSim = -1
+    for( const p of this._patterns ){
+      const sim = fingerprintSimilarity( queryFp, p.fingerprint )
+      if( sim > bestSim ){ bestSim = sim; best = p }
+    }
+    return best
+  }
+
+  private _evictIfFull( _tick: Tick ): void {
+    if( this._patterns.length < this._config.maxPatterns ) return
+    // Evict the LEAST competent pattern; ties break on the oldest (lowest
+    // storedAtTick). Age is handled by decay() — stale patterns bleed competence
+    // toward 0 each cycle, so competence alone already ranks them lowest. Folding
+    // recency INTO the score inverts value: a high-competence *old* pattern would
+    // score below a low-competence *new* one and be wrongly evicted.
+    let evictIdx = 0
+    let best = this._patterns[ 0 ]!
+    for( let i = 1; i < this._patterns.length; i++ ){
+      const p = this._patterns[ i ]!
+      if( p.competence < best.competence ||
+        ( p.competence === best.competence && p.storedAtTick < best.storedAtTick ) ){
+        best = p
+        evictIdx = i
+      }
+    }
+    this._patterns.splice( evictIdx, 1 )
+  }
+}

package/src/cognition/cache/fingerprint.ts

@@ -0,0 +1,120 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/cache/fingerprint.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * CognitiveFingerprint — extracts a deterministic scalar vector from the
+ * frozen simulation state. No wall-clock, no RNG, no iteration-order
+ * dependence (values are sorted before they enter fixed slots). The vector
+ * captures the operating context that most strongly conditions executive
+ * reasoning — the same scalars the prompt's `## Current State` block renders.
+ *
+ * Dimension layout (fixed order — never reorder without bumping the version):
+ *   0–2   physiology         energy.level, sleep.pressure, stress.load   (metrics, 0–100 → 0–1)
+ *   3–5   PAD affect         valence (−1..1 → 0..1), arousal, dominance  (metrics, 0–1)
+ *   6–15  goal priorities    top 10 `goal` entities by metadata.priority (0..1)
+ *  16–25  belief confidences top 10 `belief` entities by metadata.confidence (0..1)
+ *  26–35  wm activations     top 10 `working_memory.item` by metadata.activation (0..1)
+ *
+ * Total: 36 dimensions. Verified against the live writers:
+ *   - interoception.ts writes energy.level / sleep.pressure (0–100)
+ *   - stress.regulator.ts writes stress.load
+ *   - affective.blender.ts writes affect.valence (−1..1) / arousal / dominance (0..1)
+ *   - goal.manager.ts persists goal entities with metadata.priority
+ *   - executive.engine/commands.ts + semantic integrator persist belief entities
+ *     with metadata.confidence
+ *   - working.memory.ts persists working_memory.item entities with metadata.activation
+ */
+
+import type { ReadonlySimulationState } from '#core/types'
+
+export const FINGERPRINT_DIM = 36
+export const FINGERPRINT_VERSION = 1
+
+export function extractFingerprint( state: ReadonlySimulationState ): Float32Array {
+  const vec = new Float32Array( FINGERPRINT_DIM )
+  let idx = 0
+
+  // ── Physiology (metrics are 0–100) ───────────────────────
+  vec[ idx++ ] = _norm( _metric( state, 'energy.level', 50 ), 0, 100 )
+  vec[ idx++ ] = _norm( _metric( state, 'sleep.pressure', 0 ), 0, 100 )
+  vec[ idx++ ] = _norm( _metric( state, 'stress.load', 0 ), 0, 100 )
+
+  // ── PAD affect ───────────────────────────────────────────
+  // valence is written on [-1, 1]; map to [0, 1] so a distressed state is not
+  // silently clamped to neutral. arousal / dominance are already [0, 1].
+  vec[ idx++ ] = _clamp01( ( _metric( state, 'affect.valence', 0 ) + 1 ) / 2 )
+  vec[ idx++ ] = _clamp01( _metric( state, 'affect.arousal', 0.3 ) )
+  vec[ idx++ ] = _clamp01( _metric( state, 'affect.dominance', 0.5 ) )
+
+  // ── Top-10 goal priorities ───────────────────────────────
+  idx = _topEntityScalars( state, 'goal', 'priority', 0, vec, idx, 10 )
+
+  // ── Top-10 belief confidences ────────────────────────────
+  idx = _topEntityScalars( state, 'belief', 'confidence', 0.5, vec, idx, 10 )
+
+  // ── Top-10 working-memory activations ────────────────────
+  idx = _topEntityScalars( state, 'working_memory.item', 'activation', 0, vec, idx, 10 )
+
+  // Defensive: zero-fill any remaining slots (never expected).
+  while( idx < FINGERPRINT_DIM ) vec[ idx++ ] = 0
+
+  return vec
+}
+
+/**
+ * Collect a metadata scalar from every entity of `type`, sort descending,
+ * and write the top `count` (clamped to [0,1]) into `vec` starting at `idx`.
+ * Sorting makes the slice order deterministic regardless of Map iteration.
+ * Returns the next free index.
+ */
+function _topEntityScalars(
+  state: ReadonlySimulationState,
+  type: string,
+  field: string,
+  fallback: number,
+  vec: Float32Array,
+  idx: number,
+  count: number,
+): number {
+  const vals: number[] = []
+  for( const e of state.entities.values() ){
+    if( e.type !== type ) continue
+    const raw = e.metadata?.[ field ]
+    vals.push( typeof raw === 'number' ? raw : fallback )
+  }
+  vals.sort( ( a, b ) => b - a )
+  for( let i = 0; i < count; i++ )
+    vec[ idx++ ] = _clamp01( vals[ i ] ?? 0 )
+  return idx
+}
+
+function _metric( state: ReadonlySimulationState, key: string, fallback: number ): number {
+  const v = state.metrics.get( key )
+  return typeof v === 'number' ? v : fallback
+}
+
+/** Normalise a value from [min,max] → [0,1]. */
+function _norm( v: number, min: number, max: number ): number {
+  if( max === min ) return 0.5
+  return Math.max( 0, Math.min( 1, ( v - min ) / ( max - min ) ) )
+}
+
+function _clamp01( v: number ): number {
+  if( Number.isNaN( v ) ) return 0
+  return Math.max( 0, Math.min( 1, v ) )
+}
+
+/** Cosine similarity between two fingerprint vectors. */
+export function fingerprintSimilarity( a: Float32Array, b: Float32Array ): number {
+  let dot = 0, na = 0, nb = 0
+  for( let i = 0; i < FINGERPRINT_DIM; i++ ){
+    const ai = a[ i ] ?? 0
+    const bi = b[ i ] ?? 0
+    dot += ai * bi
+    na += ai * ai
+    nb += bi * bi
+  }
+  const denom = Math.sqrt( na ) * Math.sqrt( nb )
+  return denom === 0 ? 0 : dot / denom
+}

package/src/cognition/cache/types.ts

@@ -0,0 +1,105 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/cache/types.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * DeliberationCache — types and contracts.
+ *
+ * The cache stores past executive outputs keyed by a deterministic
+ * cognitive fingerprint. It is pure, deterministic, and R2-safe:
+ * the same state + same history ⇒ same retrieval + same composition.
+ *
+ * Scope note: Phase 1 caches the ACTIONS block only. The composed output
+ * is a valid `ExecutiveOutputFull` carrying the three required fields
+ * (actions, reasoning, confidence) plus whatever optional blocks the
+ * enabled scopes cover. Everything else stays undefined and the existing
+ * downstream (`buildStateCommands`) treats it as "nothing to do", which is
+ * exactly the intended Phase-1 behaviour.
+ */
+
+import type { ExecutiveOutputFull } from '#faculties/executive.engine/types'
+
+/** Which blocks of the executive output the cache may synthesise. */
+export type CacheScope =
+  | 'actions'
+  | 'goals'
+  | 'beliefs'
+
+export interface DeliberationCacheConfig {
+  /** Maximum patterns to retain. Lowest (competence × recency) evicted when full. */
+  maxPatterns?: number
+  /** Neighbors retrieved for composition. */
+  k?: number
+  /** Minimum similarity for a stored pattern to count as a neighbor. */
+  minSimilarity?: number
+  /** Confidence threshold θ — cache hit requires ρ ≥ θ. Start conservative. */
+  theta?: number
+  /** Temperature for softmax weights over neighbors. */
+  tau?: number
+  /** Learning rate (EMA) for competence updates. */
+  eta?: number
+  /** Competence decay per executive cycle (applied via decay()). */
+  decayPerCycle?: number
+  /** Verify 1-in-N cache hits against the LLM (0 = never). */
+  verifyEveryNHits?: number
+  /** Which output blocks to synthesise. Phase 1 default: ['actions']. */
+  scopes?: CacheScope[]
+}
+
+/** A stored pattern in the cache. */
+export interface CachePattern {
+  /** Deterministic fingerprint vector (length FINGERPRINT_DIM). */
+  fingerprint: Float32Array
+  /** The executive output produced for this fingerprint (verbatim from the LLM). */
+  output: ExecutiveOutputFull
+  /** Competence score (0–1), learned from reafference. */
+  competence: number
+  /** Tick when stored. */
+  storedAtTick: number
+  /** Number of times this pattern won a retrieval. */
+  retrievalCount: number
+  /** Number of retrievals that were followed by a positive reafference. */
+  successCount: number
+}
+
+/** A neighbor plus its similarity to the query fingerprint. */
+export interface ScoredNeighbor {
+  pattern: CachePattern
+  /** Cosine similarity of this pattern's fingerprint to the query. */
+  similarity: number
+}
+
+/** Result of a cache retrieve (+ compose when hit). */
+export interface CacheResult {
+  /** The composed output — only meaningful when `hit` is true. */
+  output: ExecutiveOutputFull | null
+  /** Confidence ρ = max_i (competence_i × sim_i). Used for gating. */
+  confidence: number
+  /** The scored neighbors that were considered. */
+  neighbors: ScoredNeighbor[]
+  /** Whether this was a cache hit (confidence ≥ θ). */
+  hit: boolean
+}
+
+/**
+ * Serialisable snapshot for deterministic persistence / restore.
+ *
+ * Persistence follows the same pattern as the rolling summarizer: the engine
+ * writes this into a state entity (`executive-deliberation-cache`) via
+ * StateCommands and rehydrates it on the first tick. Float arrays are stored
+ * as plain number[] so they survive JSON round-tripping through state.
+ */
+export interface DeliberationCacheSnapshot {
+  version: number
+  patterns: Array<{
+    fingerprint: number[]
+    output: ExecutiveOutputFull
+    competence: number
+    storedAtTick: number
+    retrievalCount: number
+    successCount: number
+  }>
+  hitCount: number
+  missCount: number
+  verifyCounter: number
+}

package/src/cognition/config.mirror.entities.ts

@@ -13,6 +13,7 @@
 // reason about its own operational parameters.
 
 import { WillConfig } from '#stem/mind'
+import type { StateManager } from '#core/state.manager'
 
 export interface EngineConfigEntity {
   id:     string
@@ -102,7 +103,6 @@ export function buildEngineConfigEntities( config: WillConfig, executiveInterval
       params: {
         maxPerceptsPerTick: 50,
         defaultSalience:    0.3,
-        emitPerceptEvents:  1,
       },
     },
     {
@@ -316,6 +316,24 @@ export function buildEngineConfigEntities( config: WillConfig, executiveInterval
         // DOWN from demonstrated `analytical` disposition via the persona-prior mirror,
         // so a more analytical Will deliberates more readily; this is the baseline.
         deliberateThreshold: 0.5,
+        // How many focused facets this Will can hold at once before spawning starts
+        // evicting (FacetSupervisor). A structural ceiling, not the live budget:
+        // attention scales the allowance *within* it each tick, so a tired or loaded
+        // mind narrows on its own. The metacog loop develops it via the persona-prior
+        // (openness widens, conscientiousness narrows), which is what makes "how many
+        // things I can hold at once" a property of this person rather than a constant.
+        maxFacets: 10,
+        // How long a QUIET thread stays open before the mind considers it finished
+        // (FacetSupervisor idle reaper). The sibling of maxFacets — that one is how
+        // many threads at once, this one is how long each survives a silence — and
+        // it was the only number in the economy no personality could move.
+        //
+        // ~30 minutes at a typical tick rate. It was hardcoded at 50 ticks, which is
+        // THIRTY SECONDS: every pause longer than a person taking a moment to type
+        // destroyed the conversation, and the reply landed on a facet that had never
+        // heard of them. Generous is safe — maxFacets + eviction bound the population;
+        // this only decides when silence means "over".
+        facetIdleTtlTicks: 3000,
       },
     },
     {
@@ -366,6 +384,35 @@ export function buildEngineConfigEntities( config: WillConfig, executiveInterval
         switchCost:   0.15,
         riskWeight:   0.20,
         noveltyWeight: 0.10,
+        // How hard an act's own live footprint damps doing it again (EXAFFERENCE
+        // P5) — how long this mind sits with something it has already said before
+        // saying it again. Agreeableness develops it up, demonstrated persistence
+        // down, so "gives people room" vs "chases an answer" is a trait rather
+        // than a constant.
+        repeatDamping: 0.30,
+        // Ticks an act keeps satiating the urge to repeat it. Separate from the
+        // consequence TTL on purpose: that one is "how long until the world's echo
+        // could still arrive" (short, and about perception), this is "how long
+        // before saying it again feels right" (a disposition). Same two traits as
+        // repeatDamping move it — patience lengthens, persistence shortens.
+        repeatWindowTicks: 60,
+        // Ticks before a silence starts to mean something — how long this mind
+        // gives someone to get back to it before it counts the turn unanswered
+        // and learns from that (conversation.aim / ReafferenceEngine).
+        //
+        // Lives beside repeatWindowTicks rather than in a config of its own
+        // because they are two readings of ONE disposition, and splitting them
+        // would let a mind tune itself into contradiction — coming back to
+        // something in 20 ticks while still calling the silence too fresh to
+        // count. Long relative to its neighbours by design: repeatWindowTicks
+        // asks "how long before saying it again feels right", this asks "how long
+        // before I take not hearing back as information", and at 1s/tick that is
+        // four minutes of a real person's time, not one.
+        replyWindowTicks: 240,
+        // How much a learned read on someone biases acting toward them. SIGNED and
+        // unclamped: a warm mind leans toward whoever answers, a dogged one chases
+        // the silence. The container will not choose between those.
+        socialWeight:  0.30,
       },
     },
 
@@ -473,3 +520,63 @@ export function buildEngineConfigEntities( config: WillConfig, executiveInterval
     },
   ]
 }
+
+// ── The single writer ─────────────────────────────────────────
+
+/**
+ * Write an `engine.config` entity — MERGING, always. The only sanctioned way to
+ * write one; `tests/unit/config.mirror.writer.test.ts` fails on a raw
+ * `setEntity({ type: 'engine.config' })` anywhere else.
+ *
+ * Every whole-entity write to one of these has silently dropped params, three
+ * times in one day and each in a different place:
+ *
+ *   • PMALoader replaced `engine-config-executive` with the three behavioural
+ *     params a PMA carries, dropping `deliberateThreshold` — so `readBaseParams`
+ *     returned nothing for it and `consolidatePrior` skipped the analytical and
+ *     decisiveness edges outright, for every Will ever restored from an artifact.
+ *   • The same loader dropped `emitBlendEvents` from the blender and three params
+ *     from forgetting.
+ *   • Snapshot restore replaced the whole mirror, so a Will woke with the config
+ *     it FIRST hibernated under and could never receive a param added later —
+ *     `maxFacets` and `deliberateThreshold` were inert on a live Will for its
+ *     entire life.
+ *
+ * `precedence` says which side wins on a key both hold. Neither ever drops a key.
+ *
+ *   'incoming' — the caller is the authority (boot seed; a PMA supplying the
+ *                tenant's own dispositions). Keys it does not mention survive.
+ *   'existing' — state is the authority (post-restore backfill). Only genuinely
+ *                missing keys are added, so learned and PMA'd values are safe.
+ *
+ * Returns the keys it actually added or changed, for the caller to log.
+ */
+export function mergeEngineConfig(
+  store:      StateManager,
+  cfg:        EngineConfigEntity,
+  precedence: 'incoming' | 'existing' = 'incoming',
+): string[] {
+  const existing = store.getEntity( cfg.id )
+  const current  = ( existing?.metadata as { params?: Record<string, unknown> } | undefined )?.params ?? {}
+
+  const params = precedence === 'existing'
+    ? { ...cfg.params, ...current }   // state wins; fills only what is missing
+    : { ...current, ...cfg.params }   // caller wins; keeps everything else
+
+  const changed = Object.keys( params ).filter( k => params[ k ] !== current[ k ] )
+  if( existing && changed.length === 0 ) return []
+
+  // No timestamps: StateManager.setEntity is the single place they are stamped,
+  // and it sources them from the SIM clock so entity times replay identically
+  // (R2). It also preserves an existing `createdAt`. The write sites this
+  // replaced all passed `Date.now()`, which was both redundant and a real
+  // determinism hole — the guard test caught it the moment the code moved into
+  // `cognition/`, where wall-clock reads are banned.
+  store.setEntity({
+    id:       cfg.id,
+    type:     'engine.config',
+    metadata: { engine: cfg.engine, params },
+  })
+
+  return changed
+}

package/src/cognition/event.schemas.ts

@@ -74,14 +74,6 @@ globalSchemaRegistry.register({
   },
 })
 
-globalSchemaRegistry.register({
-  type: 'percept.batch.ingested', version: 1,
-  validate( p ){
-    if( !isObj(p) ) return 'payload must be object'
-    return hasNum( p, 'count')
-  },
-})
-
 globalSchemaRegistry.register({
   type: 'social.agents.present', version: 1,
   validate( p ){
@@ -566,3 +558,25 @@ globalSchemaRegistry.register({
     return hasNum( p, 'count')
   },
 })
+
+// ── Deliberation cache (fast-path telemetry) ─────────────────
+// Published from the ExecutiveEngine's committed path (onReasoningComplete),
+// never from inside the pure cache. Lets faculties like the PersonaConsolidator
+// react to how automatic the Will is becoming (e.g. a high hit rate could lower
+// the deliberate-effort threshold).
+
+globalSchemaRegistry.register({
+  type: 'cache.hit', version: 1,
+  validate( p ){
+    if( !isObj(p) ) return 'payload must be object'
+    return hasNum( p, 'confidence') ?? hasNum( p, 'neighborCount')
+  },
+})
+
+globalSchemaRegistry.register({
+  type: 'cache.miss', version: 1,
+  validate( p ){
+    if( !isObj(p) ) return 'payload must be object'
+    return hasNum( p, 'confidence')
+  },
+})

package/src/cognition/faculties/affective.blender.ts

@@ -47,6 +47,21 @@ const ACP_CONFIDENCE     = 0.4
  * Numeric encoding for dominant emotion metric.
  * Consumers decode using DOMINANT_EMOTION_LABELS[code].
  */
+/**
+ * The entity carrying the non-numeric side of affect — what the mind is feeling,
+ * by name.
+ *
+ * Exported as a CONSTANT because the id is a contract between two files and it
+ * silently broke: `context.ts` read `state.entities.get('affective-state')`, an
+ * id nothing has ever written, so `dominantEmotion` fell back to 'neutral' in
+ * every prompt ever rendered. Measured live: a COO sitting at frustration 1.000
+ * and boredom 1.000 was told "Dominant emotion: neutral".
+ *
+ * Two string literals in two files cannot disagree if there is only one.
+ */
+export const AFFECT_STATE_ID   = 'affect-blends'
+export const AFFECT_STATE_TYPE = 'affect.blends'
+
 const DOMINANT_EMOTION_CODES: Record<string, number> = {
   'neutral':       0,
   'fear':          1,
@@ -381,11 +396,13 @@ export class AffectiveBlender implements SimulationEngine, CognitiveEngine {
     const dominantCode = DOMINANT_EMOTION_CODES[ dominant ?? 'neutral' ] ?? 0
     commands.metrics!.push([ 'affect.dominant_emotion', dominantCode ])
 
-    // Persist active blends as a state entity so the executive bridge can read them
+    // The mind's own read on what it is feeling, as an entity the executive can
+    // render. `dominantEmotion` is written as the LABEL, not the code: the code
+    // goes to metrics for telemetry, and a prompt cannot say "I feel 20".
     commands.set!.push({
-      id: 'affect-blends',
-      type:     'affect.blends',
-      metadata: { blends },
+      id:   AFFECT_STATE_ID,
+      type: AFFECT_STATE_TYPE,
+      metadata: { dominantEmotion: dominant ?? 'neutral', blends },
     })
 
     // 8. Track emotion history for blending detection