@mindot/will 0.8.0 → 0.9.0

package/src/cognition/cache/composition.ts

@@ -0,0 +1,232 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/cache/composition.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Compositional operators for cache interpolation.
+ *
+ * Design principle (from the research sketch): interpolate what is safe to
+ * interpolate, copy verbatim what is not. Executive actions carry free-text
+ * fields (`reasoning`, `expectedOutcome`) that would turn to gibberish under
+ * blending, so the ACTIONS block uses a weighted *vote* over action type and
+ * then copies the winning neighbor's action objects verbatim. Numeric scalars
+ * (goal priority, belief confidence) are the only fields we mean-blend.
+ *
+ * Every operator is deterministic: inputs arrive pre-sorted from the cache and
+ * ties are resolved by neighbor order (already deterministic), never by hashing.
+ */
+
+import type { ExecutiveOutputFull } from '#faculties/executive.engine/types'
+import type { ScoredNeighbor, CacheScope } from './types'
+
+/**
+ * Compose a valid ExecutiveOutputFull from scored neighbors. `neighbors` must be
+ * non-empty and ordered best-first (as the cache returns them). The three
+ * required fields (actions, reasoning, confidence) are always populated.
+ */
+export function composeOutput(
+  neighbors: ScoredNeighbor[],
+  tau: number,
+  scopes: CacheScope[],
+): ExecutiveOutputFull {
+  const weights = _softmaxWeights( neighbors, tau )
+
+  // The best neighbor anchors required fields when a scope leaves them empty.
+  const anchor = neighbors[ 0 ]!.pattern.output
+
+  const out: ExecutiveOutputFull = {
+    actions:    [],
+    reasoning:  anchor.reasoning ?? '',
+    confidence: anchor.confidence ?? 0.5,
+  }
+
+  if( scopes.includes('actions') ){
+    const composed = _composeActions( neighbors, weights )
+    out.actions    = composed.actions
+    out.reasoning  = composed.reasoning
+    out.confidence = composed.confidence
+  } else {
+    // Actions are required downstream — fall back to the anchor's verbatim actions.
+    out.actions = _clone( anchor.actions ?? [] )
+  }
+
+  if( scopes.includes('goals') )
+    out.newGoals = _composeGoals( neighbors, weights )
+
+  if( scopes.includes('beliefs') )
+    out.newBeliefs = _composeBeliefs( neighbors, weights )
+
+  return out
+}
+
+// ── Weight computation ─────────────────────────────────────
+
+function _softmaxWeights( neighbors: ScoredNeighbor[], tau: number ): number[] {
+  const t = tau > 0 ? tau : 1e-6
+  const sims = neighbors.map( n => n.similarity )
+  const maxSim = Math.max( ...sims )
+  const exps = sims.map( s => Math.exp( ( s - maxSim ) / t ) )  // shift for stability
+  const sum = exps.reduce( ( a, b ) => a + b, 0 )
+  return exps.map( e => ( sum === 0 ? 1 / exps.length : e / sum ) )
+}
+
+// ── ACTIONS: weighted type vote + verbatim copy ────────────
+
+function _composeActions(
+  neighbors: ScoredNeighbor[],
+  weights: number[],
+): { actions: ExecutiveOutputFull['actions']; reasoning: string; confidence: number } {
+  // Vote on each neighbor's primary (first) action type.
+  const typeWeight = new Map<string, number>()
+  for( let i = 0; i < neighbors.length; i++ ){
+    const acts = neighbors[ i ]!.pattern.output.actions ?? []
+    const primary = acts[ 0 ]?.type
+    if( primary === undefined ) continue
+    typeWeight.set( primary, ( typeWeight.get( primary ) ?? 0 ) + ( weights[ i ] ?? 0 ) )
+  }
+
+  // Winning type — deterministic: highest weight, ties broken by neighbor order
+  // (the first neighbor to reach the max keeps it, and neighbors are best-first).
+  let winningType: string | null = null
+  let bestWeight = -1
+  for( let i = 0; i < neighbors.length; i++ ){
+    const primary = neighbors[ i ]!.pattern.output.actions?.[ 0 ]?.type
+    if( primary === undefined ) continue
+    const w = typeWeight.get( primary ) ?? 0
+    if( w > bestWeight ){ bestWeight = w; winningType = primary }
+  }
+
+  // Copy the full action list from the highest-weight neighbor whose primary
+  // action type matches the winner — verbatim, so text fields stay coherent.
+  let source = neighbors[ 0 ]!
+  for( let i = 0; i < neighbors.length; i++ ){
+    if( neighbors[ i ]!.pattern.output.actions?.[ 0 ]?.type === winningType ){
+      source = neighbors[ i ]!
+      break
+    }
+  }
+
+  const src = source.pattern.output
+  return {
+    actions:    _clone( src.actions ?? [] ),
+    reasoning:  src.reasoning ?? '',
+    confidence: src.confidence ?? 0.5,
+  }
+}
+
+// ── GOALS: merge by description, mean priority (Phase 2) ────
+
+function _composeGoals(
+  neighbors: ScoredNeighbor[],
+  weights: number[],
+): ExecutiveOutputFull['newGoals'] {
+  type Agg = {
+    weight: number
+    priority: number
+    tags: string[]
+    completionType: string
+    completionCondition?: string
+    bestW: number
+  }
+  const byDesc = new Map<string, Agg>()
+
+  for( let i = 0; i < neighbors.length; i++ ){
+    const w = weights[ i ] ?? 0
+    for( const g of neighbors[ i ]!.pattern.output.newGoals ?? [] ){
+      const cur = byDesc.get( g.description )
+      if( cur ){
+        cur.weight += w
+        cur.priority += g.priority * w
+        if( w > cur.bestW ){
+          cur.bestW = w
+          cur.tags = g.tags
+          cur.completionType = g.completionType
+          cur.completionCondition = g.completionCondition
+        }
+      } else {
+        byDesc.set( g.description, {
+          weight: w,
+          priority: g.priority * w,
+          tags: g.tags,
+          completionType: g.completionType,
+          completionCondition: g.completionCondition,
+          bestW: w,
+        } )
+      }
+    }
+  }
+
+  const result: NonNullable<ExecutiveOutputFull['newGoals']> = []
+  for( const [ description, a ] of byDesc ){
+    result.push( {
+      description,
+      priority: a.weight === 0 ? 0 : a.priority / a.weight,
+      tags: [ ...a.tags ],
+      completionType: a.completionType,
+      ...( a.completionCondition !== undefined ? { completionCondition: a.completionCondition } : {} ),
+    } )
+  }
+  result.sort( ( x, y ) => y.priority - x.priority )
+  return result.slice( 0, 3 )
+}
+
+// ── BELIEFS: merge by statement, mean confidence (Phase 3) ─
+
+function _composeBeliefs(
+  neighbors: ScoredNeighbor[],
+  weights: number[],
+): ExecutiveOutputFull['newBeliefs'] {
+  type Agg = {
+    weight: number
+    confidence: number
+    category: string
+    evidence: 'single_observation' | 'recurring_pattern' | 'strong_pattern'
+    tags: string[]
+    bestW: number
+  }
+  const byStmt = new Map<string, Agg>()
+
+  for( let i = 0; i < neighbors.length; i++ ){
+    const w = weights[ i ] ?? 0
+    for( const b of neighbors[ i ]!.pattern.output.newBeliefs ?? [] ){
+      const cur = byStmt.get( b.statement )
+      if( cur ){
+        cur.weight += w
+        cur.confidence += b.confidence * w
+        if( w > cur.bestW ){
+          cur.bestW = w
+          cur.category = b.category
+          cur.evidence = b.evidence
+          cur.tags = b.tags
+        }
+      } else {
+        byStmt.set( b.statement, {
+          weight: w,
+          confidence: b.confidence * w,
+          category: b.category,
+          evidence: b.evidence,
+          tags: b.tags,
+          bestW: w,
+        } )
+      }
+    }
+  }
+
+  const result: NonNullable<ExecutiveOutputFull['newBeliefs']> = []
+  for( const [ statement, a ] of byStmt ){
+    result.push( {
+      statement,
+      category: a.category,
+      confidence: a.weight === 0 ? 0 : a.confidence / a.weight,
+      evidence: a.evidence,
+      tags: [ ...a.tags ],
+    } )
+  }
+  return result
+}
+
+// ── Deterministic deep clone for verbatim-copied blocks ────
+
+function _clone<T>( v: T ): T {
+  return JSON.parse( JSON.stringify( v ) ) as T
+}

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
+}