@mindot/will 0.7.0 → 0.9.0

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
@@ -34,7 +35,7 @@ export function buildEngineConfigEntities( config: WillConfig, executiveInterval
       engine: 'system',
       params: {
         anatomy:        config.anatomy ?? 'mind',
-        model:          config.model ?? '',
+        model:          config.llm?.model ?? '',
         tickIntervalMs: config.tickIntervalMs ?? 1000
       }
     },
@@ -316,6 +317,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 +385,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 +521,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

@@ -566,3 +566,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/autobiographical.narrator.ts

@@ -23,6 +23,7 @@ import type { CognitiveEvent, CognitiveBus } from '#cognition/bus'
 import { GenerativeModel } from '#cognition/generative.model'
 import { readEffectiveParams } from '#cognition/persona.prior'
 import { ExecutiveEngine } from '#faculties/executive.engine'
+import { identityCommand } from '#cognition/identity.entity'
 
 export interface AutobiographicalNarratorConfig {
   minIntervalTicks?: number
@@ -171,16 +172,10 @@ export class AutobiographicalNarrator implements SimulationEngine, CognitiveEngi
           for( const { key: trait, value: delta } of executiveOutput.identityUpdates.traits )
             updatedTraits[ trait ] = Math.max( 0, Math.min( 1, ( updatedTraits[ trait ] ?? 0.5 ) + delta ) )
 
-          commands.set!.push({
-            id: 'identity-self',
-            type: 'will.identity',
-            createdAt: existingIdentity.createdAt,
-            metadata: {
-              ...existingIdentity.metadata,
-              traits: updatedTraits,
-              version: ( ( existingIdentity.metadata?.version as number ) ?? 1 ) + 1,
-            },
-          })
+          commands.set!.push( identityCommand( state, {
+            traits: updatedTraits,
+            version: ( ( existingIdentity.metadata?.version as number ) ?? 1 ) + 1,
+          } ) )
         }
       }
 

package/src/cognition/faculties/episodic.consolidator.ts

@@ -114,6 +114,13 @@ export class EpisodicConsolidator implements SimulationEngine, CognitiveEngine {
 
   // Vector memory integration
   private _vectorMemory: VectorMemoryAdapter | null = null
+  /**
+   * In-flight background indexing. Indexing is deliberately not awaited inside
+   * react() (a rate-limit retry chain would stall the whole tick loop), so this is
+   * the handle for the two callers that genuinely must wait for it: shutdown,
+   * before persisting the index, and tests asserting on it.
+   */
+  private _indexing: Promise<void> = Promise.resolve()
   private _embedder: EmbeddingProvider | null = null
   private _autoIndex: boolean
 
@@ -278,7 +285,35 @@ export class EpisodicConsolidator implements SimulationEngine, CognitiveEngine {
         content: ep.content
       } ) )
 
-      await this._vectorMemory.indexBatch( episodesWithContent )
+      // Indexing is BEST-EFFORT, exactly like semanticQuery. It calls an embedding
+      // provider, so a rate limit or an outage is an ordinary condition, not a
+      // cognitive fault: the episode is already consolidated and in the store, and
+      // only its vector is missing. Letting that throw took the whole engine down
+      // mid-tick — observed live as `Engine "episodic-consolidator" threw at tick
+      // 107: Embedding failed: 429`, which also aborted the rest of this react()
+      // (store sync, forgetting-curve decay) for that tick.
+      //
+      // The episode itself is NOT lost: it is in `_store` and is written to state by
+      // the periodic full-store sync below, so it survives snapshot/restore. Only its
+      // VECTOR is missing, which costs semantic recall of that episode for the rest of
+      // the session — `rebuildFromStore()` re-indexes the whole store on a later
+      // restore that finds no persisted index. Nothing re-indexes it in-session; that
+      // is a known gap, not a claim that this self-heals.
+      // NOT awaited. Nothing in this tick reads the vector index, and the embedding
+      // call is a network round-trip behind a rate-limit gate whose retry chain runs
+      // ~60s (4+8+16+32s) before giving up. Awaiting it made a single 429 stall the
+      // WHOLE TICK LOOP for a minute — measured: ticks 3→4 and 4→5 took 64.9s and
+      // 63.5s, one per deferred batch. That is not merely slow: `AWAIT_TIMEOUT` and
+      // every other agency deadline are denominated in TICKS, so a 60s tick silently
+      // turned a 15-tick timeout into 15 minutes, left one communicate intent stuck
+      // 'awaiting', and — because the selector is serial — blocked every subsequent
+      // action. 45 executive decisions produced 1 intent and 0 delivered messages.
+      this._indexing = this._vectorMemory.indexBatch( episodesWithContent ).catch( ( err: unknown ) => {
+        logger.warn(
+          `[EpisodicConsolidator] indexing deferred for ${ newEpisodes.length } episode(s) — ` +
+          `${ err instanceof Error ? err.message : String( err ) }`
+        )
+      } )
     }
 
     // 5. Periodic full-store sync — captures activationStrength decay (forgetting curve),
@@ -385,6 +420,9 @@ export class EpisodicConsolidator implements SimulationEngine, CognitiveEngine {
    * Other metadata narrowing (sourceType / tags) remains the caller's job on the
    * returned episodes (which carry all metadata).
    */
+  /** Await any background indexing still in flight. Shutdown and tests only. */
+  async flushIndexing(): Promise<void> { await this._indexing }
+
   async semanticQuery(
     query: unknown,
     filters?: {
@@ -417,10 +455,18 @@ export class EpisodicConsolidator implements SimulationEngine, CognitiveEngine {
     let timer: ReturnType<typeof setTimeout> | undefined
     const timedOut = Symbol('recall-timeout')
 
+    // The search keeps running after the race is lost — its own rate-limit retry
+    // chain can outlive this timeout by a minute. Its rejection is caught HERE
+    // rather than left to the race: a promise that loses a Promise.race still
+    // settles, and an unhandled 429 rejection surfaces as a process-level warning
+    // (or a crash, depending on host) long after the recall it belonged to gave up.
     const results = await Promise.race( [
       this._vectorMemory.search( query, {
         maxResults:    fetch,
         minSimilarity: filters?.minSimilarity,
+      } ).catch( ( err: unknown ) => {
+        logger.warn(`[EpisodicConsolidator] recall search failed — ${ err instanceof Error ? err.message : String( err ) }`)
+        return []
       } ),
       new Promise<typeof timedOut>( resolve => { timer = setTimeout( () => resolve( timedOut ), timeoutMs ) } ),
     ] ).finally( () => clearTimeout( timer ) )
@@ -658,8 +704,18 @@ export class EpisodicConsolidator implements SimulationEngine, CognitiveEngine {
     if( this._vectorMemory ){
       await this._vectorMemory.load()
       if( this._vectorMemory.size === 0 && this._store.length > 0 ){
-        await this._vectorMemory.rebuildFromStore( this._store )
-        logger.info(`[episodic] vector index rebuilt with ${this._store.length} episodes`)
+        // Re-embedding the whole store is a bulk network operation, and this runs on
+        // the FIRST TICK after restore. Awaited, it held tick 1 for 66.7s against a
+        // 500ms budget and threw on a rate limit — a mind spending its first waking
+        // minute frozen, with every tick-denominated deadline stretched around it.
+        // Detached: recall degrades to "not yet indexed" until it lands, which is the
+        // same best-effort contract semanticQuery already has. `flushIndexing()` is
+        // what shutdown drains, so a rebuild in flight is still written out.
+        this._indexing = this._vectorMemory.rebuildFromStore( this._store )
+          .then( () => { logger.info(`[episodic] vector index rebuilt with ${ this._store.length } episodes`) } )
+          .catch( ( err: unknown ) => {
+            logger.warn(`[episodic] vector index rebuild deferred — ${ err instanceof Error ? err.message : String( err ) }`)
+          } )
       } else if( this._vectorMemory.size > 0 ){
         logger.info(`[episodic] vector index loaded from disk (${this._vectorMemory.size} entries)`)
       }