@mindot/will 0.1.0

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

@@ -0,0 +1,475 @@
+//
+// These entities make every tunable engine parameter visible to the executive
+// reasoning cycle, metacognition engines, and future self-tuning features.
+//
+// Architecture contract:
+//   • Engines currently read their config from constructor parameters (fast path).
+//   • These entities are the *readable* mirror of those resolved values.
+//   • Future work: engines read from state each tick so a MetacognitionEngine
+//     can write updated values and have them take effect without a restart.
+//     That read path is already implemented in each engine via _readConfigFromState().
+//
+// The executive can reference `engine.config` entities in its context prompt to
+// reason about its own operational parameters.
+
+import { WillConfig } from '#stem/mind'
+
+export interface EngineConfigEntity {
+  id:     string
+  engine: string
+  params: Record<string, unknown>
+}
+
+export function buildEngineConfigEntities( config: WillConfig, executiveInterval: number ): EngineConfigEntity[] {
+  const selfBelonging  = parseFloat( process.env.WILL_SELF_BELONGING  ?? '0.35' )
+  const boredomRate    = parseFloat( process.env.WILL_BOREDOM_RATE    ?? '0.005' )
+  const curiosityFloor = parseFloat( process.env.WILL_CURIOSITY_FLOOR ?? '0.08' )
+  const summaryInterval   = parseInt( process.env.WILL_SUMMARY_INTERVAL   ?? '10' )
+  const summaryBufferSize = parseInt( process.env.WILL_SUMMARY_BUFFER_SIZE ?? '12' )
+
+  return [
+    // ── System metadata ──────────────────────────────────────────
+    {
+      id: 'engine-config-system',
+      engine: 'system',
+      params: {
+        engineTier:     config.engineTier,
+        modelTier:      config.modelTier,
+        tickIntervalMs: config.tickIntervalMs ?? 1000
+      }
+    },
+
+    // ── Regulatory ───────────────────────────────────────────────
+    {
+      id: 'engine-config-energy',
+      engine: 'energy',
+      params: {
+        maxEnergy:               100,
+        baseDecayRate:           0.02,
+        restReplenishRate:       0.15,
+        lowEnergyThreshold:      30,
+        criticalEnergyThreshold: 10,
+        collapseThreshold:       1,
+        recoveryThreshold:       15,
+      },
+    },
+    {
+      id: 'engine-config-sleep',
+      engine: 'sleep',
+      params: {
+        wakeAccumulationRate: 0.008,
+        restDissipationRate:  0.04,
+        maxPressure:          100,
+        fatigueThreshold:     40,
+        exhaustionThreshold:  70,
+      },
+    },
+    {
+      id: 'engine-config-circadian',
+      engine: 'circadian',
+      params: {
+        periodHours:      24.2,
+        phaseOffsetHours: 0,
+        entrainable:      1,   // boolean stored as 1/0 for numeric consistency
+      },
+    },
+    {
+      id: 'engine-config-attention',
+      engine: 'attention',
+      params: {
+        maxCapacity: 100,
+        costPerFocus: 5,
+        maxFoci:      4,
+        shiftInertia: 0.7,
+      },
+    },
+    {
+      id: 'engine-config-stress',
+      engine: 'stress',
+      params: {
+        baseDecayRate:     1.5,   // overridden in mind.ts from default 0.01
+        optimalThreshold:  30,
+        distressThreshold: 50,
+        overloadThreshold: 75,
+        maxLoad:           100,
+      },
+    },
+
+    // ── Perceptual ───────────────────────────────────────────────
+    {
+      id: 'engine-config-exteroception',
+      engine: 'exteroception',
+      params: {
+        maxPerceptsPerTick: 50,
+        defaultSalience:    0.3,
+        emitPerceptEvents:  1,
+      },
+    },
+    {
+      id: 'engine-config-interoception',
+      engine: 'interoception',
+      params: {
+        emitDetailEvent: 0,
+      },
+    },
+    {
+      id: 'engine-config-social-perception',
+      engine: 'social-perception',
+      params: {
+        maxPerceptsPerTick: 20,
+      },
+    },
+    {
+      id: 'engine-config-novelty',
+      engine: 'novelty',
+      params: {
+        learningRate:          0.1,
+        windowSize:            10,
+        significanceThreshold: 0.4,
+      },
+    },
+
+    // ── Affective ────────────────────────────────────────────────
+    {
+      id: 'engine-config-threat',
+      engine: 'threat',
+      params: {
+        hostileWeight:     0.35,
+        scarcityWeight:    0.25,
+        uncertaintyWeight: 0.20,
+        socialWeight:      0.20,
+        fearEventThreshold: 0.6,
+      },
+    },
+    {
+      id: 'engine-config-reward',
+      engine: 'reward',
+      params: {
+        goalWeight:      0.40,
+        socialWeight:    0.25,
+        resourceWeight:  0.15,
+        discoveryWeight: 0.20,
+        socialDecayRate: 0.02,
+        socialWarmthBoost: 0.4,
+      },
+    },
+    {
+      id: 'engine-config-loss',
+      engine: 'loss',
+      params: {
+        significantLossThreshold: 0.5,
+        decayRate:                0.05,
+      },
+    },
+    {
+      id: 'engine-config-frustration',
+      engine: 'frustration',
+      params: {
+        stuckThreshold:   5,
+        irritabilityRate: 0.02,
+        decayRate:        0.08,
+        habituationRate:  0.03,
+        // How strongly provocation (unfairness + blocked progress) becomes anger.
+        // Channel A: the metacog loop develops it DOWN from demonstrated `agreeableness`
+        // (yielding in conflict — accommodate rather than retaliate). This is the baseline.
+        angerReactivity:  0.7,
+      },
+    },
+    {
+      id: 'engine-config-attachment',
+      engine: 'attachment',
+      params: {
+        selfBelonging,
+        attachmentGrowthRate:   0.05,
+        attachmentDecayRate:    0.002,
+        lonelinessThreshold:    0.4,
+        minInteractionsForBond: 3,
+      },
+    },
+    {
+      id: 'engine-config-aesthetic',
+      engine: 'aesthetic',
+      params: {
+        boredomRate,
+        curiosityFloor,
+        aweThreshold:      0.8,
+        curiosityRangeMin: 0.2,
+        curiosityRangeMax: 0.7,
+      },
+    },
+    {
+      id: 'engine-config-moral',
+      engine: 'moral',
+      params: {
+        eventThreshold: 0.3,
+        decayRate:      0.02,
+        // Moral foundations stored flat — keys map 1:1 to the six MFT
+        // foundations the engine tracks (care, fairness, loyalty, authority,
+        // sanctity, liberty). Values are the constructor's normalized weights
+        // (sum 1.0); the engine re-normalizes after applying them.
+        foundationCare:      0.25,
+        foundationFairness:  0.25,
+        foundationLoyalty:   0.15,
+        foundationAuthority: 0.10,
+        foundationSanctity:  0.10,
+        foundationLiberty:   0.15,
+      },
+    },
+    {
+      id: 'engine-config-affective-blender',
+      engine: 'affective-blender',
+      params: {
+        inertia:          0.5,
+        emitBlendEvents:  0,
+      },
+    },
+
+    // ── Memory ───────────────────────────────────────────────────
+    {
+      id: 'engine-config-working-memory',
+      engine: 'working-memory',
+      params: {
+        maxChunks:           7,
+        baseDecayRate:       0.08,
+        attentionProtection: 0.6,
+        retrievalThreshold:  0.05,
+      },
+    },
+    {
+      id: 'engine-config-episodic',
+      engine: 'episodic',
+      params: {
+        consolidationThreshold: 0.25,
+        emotionBoost:           2.0,
+        maxPerTick:             5,
+      },
+    },
+    {
+      id: 'engine-config-semantic',
+      engine: 'semantic',
+      params: {
+        minIntervalTicks:         30,
+        minNewEpisodes:           10,
+        maxBeliefs:               500,
+        beliefStalenessThreshold: 300,
+        beliefDecayRate:          0.001,
+      },
+    },
+    {
+      id: 'engine-config-forgetting',
+      engine: 'forgetting',
+      params: {
+        baseForgettingRate: 0.02,
+        emotionProtection:  0.7,
+        pruningThreshold:   0.01,
+        maxPrunePerTick:    10,
+      },
+    },
+    {
+      id: 'engine-config-spaced-repetition',
+      engine: 'spaced-repetition',
+      params: {
+        reviewIntervalTicks:    50,
+        maxReviewsPerCycle:     5,
+        minConfidenceForReview: 0.15,
+        successBoost:           0.05,
+        failurePenalty:         0.08,
+        baseIntervalTicks:      10,
+        maxIntervalTicks:       500,
+        executiveReviewEnabled: 0,   // boolean stored as 1/0 for numeric consistency
+      },
+    },
+    {
+      id: 'engine-config-dream',
+      engine: 'dream',
+      params: {
+        maxReactivationsPerTick: 5,
+        emotionalDampeningRate:  0.05,
+        recombinationProbability: 0.1,
+      },
+    },
+
+    // ── Executive ────────────────────────────────────────────────
+    {
+      id: 'engine-config-goal-manager',
+      engine: 'goal-manager',
+      params: {
+        maxActiveGoals:           5,
+        priorityDecayRate:        0.005,
+        deactivationThreshold:    0.1,
+        epistemicBeliefThreshold: 8,
+        // Personality dispositions (PMA-seedable per Will; developed by metacog via
+        // the persona-prior). Grit/persistence + frustration tolerance.
+        gritPriority:             0.8,
+        gritPatienceScale:        2,
+        frustrationTolerance:     0.5,
+      },
+    },
+    {
+      id: 'engine-config-executive',
+      engine: 'executive',
+      params: {
+        executiveInterval: executiveInterval,
+        cooldownTicks:   5,
+        // Dual-process effort gate (Channel A). Effort demand at/above which the master
+        // engages System 2 (deliberate propose→evaluate). The metacog loop develops it
+        // 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,
+      },
+    },
+    {
+      id: 'engine-config-planning',
+      engine: 'planning',
+      // Trait-driven supervision dispositions (Channel A). The metacog loop
+      // (PersonaConsolidator) develops these from demonstrated conscientiousness
+      // via the persona-prior mirror; these are the PMA-seeded baselines.
+      params: {
+        maxStepRetries:         3,
+        surpriseOutcomeQuality: 0.25,
+        // How hard the plan asserts its frontier in the action competition
+        // (planning-as-prior). 1 = neutral; conscientiousness develops it UP so a
+        // conscientious Will pushes its plan against competing impulses.
+        planBiasGain:           1,
+      },
+    },
+    {
+      id: 'engine-config-inhibition',
+      engine: 'inhibition',
+      params: {
+        baseInhibitionStrength: 0.6,
+        arousalThreshold:       0.6,
+        maxDeferralsPerTick:    3,
+      },
+    },
+    {
+      id: 'engine-config-task-switcher',
+      engine: 'task-switcher',
+      params: {
+        baseSwitchCost:  0.3,
+        switchThreshold: 0.2,
+        minFocusTicks:   3,
+      },
+    },
+    {
+      // Agency action-selection apparatus (Channel A). `switchCost` is the selector's
+      // preemption hysteresis on the *activation* scale — the second owner of the same
+      // "switch resistance" disposition the task-switcher develops in attention space.
+      // Conscientiousness raises it (less distractible → sees actions through); the
+      // selector modulates it by the shared `task_switch.current_focus_ticks` signal.
+      // `riskWeight` / `noveltyWeight` are competition weights the selector reads back
+      // (base ⊕ prior): emotional-stability lowers risk (bolder), openness raises novelty
+      // (curiosity pulls toward the unpracticed). Mirror DEFAULT_WEIGHTS in scoring.ts.
+      id: 'engine-config-action-selector',
+      engine: 'action-selector',
+      params: {
+        switchCost:   0.15,
+        riskWeight:   0.20,
+        noveltyWeight: 0.10,
+      },
+    },
+
+    // ── Meta-cognitive ───────────────────────────────────────────
+    {
+      id: 'engine-config-self-model',
+      engine: 'self-model',
+      params: {
+        minIntervalTicks:    200,
+        minNewExperiences:   20,
+      },
+    },
+    {
+      id: 'engine-config-confidence',
+      engine: 'confidence',
+      params: {
+        minSamplesPerDomain: 5,
+        calibrationRate:     0.1,
+        maxAdjustment:       0.3,
+      },
+    },
+    {
+      id: 'engine-config-bias-detector',
+      engine: 'bias-detector',
+      params: {
+        minDecisions:      10,
+        scanIntervalTicks: 100,
+        emitBiasEvents:    1,
+      },
+    },
+    {
+      id: 'engine-config-narrator',
+      engine: 'narrator',
+      params: {
+        minIntervalTicks:   50,
+        maxNarrativeLength: 5000,
+      },
+    },
+    {
+      id: 'engine-config-introspection',
+      engine: 'introspection',
+      params: {
+        cooldownTicks:         50,
+        significanceThreshold: 0.4,
+      },
+    },
+
+    // ── Social ───────────────────────────────────────────────────
+    {
+      id: 'engine-config-theory-of-mind',
+      engine: 'theory-of-mind',
+      params: {
+        maxModeledAgents:      10,
+        beliefDecayRate:       0.002,
+        confidenceThreshold:   0.3,
+      },
+    },
+    {
+      id: 'engine-config-empathy',
+      engine: 'empathy',
+      params: {
+        resonanceStrength:   0.6,
+        compassionThreshold: 0.3,
+      },
+    },
+    {
+      id: 'engine-config-reputation',
+      engine: 'reputation',
+      params: {
+        maxTrackedAgents: 20,
+        decayRate:        0.001,
+        minInteractions:  3,
+        // How much a cooperative interaction raises an agent's cooperativeness (trust step).
+        // Channel A: the metacog loop develops it UP from demonstrated `agreeableness`
+        // (extends trust / benefit-of-the-doubt more readily). This is the baseline.
+        trustGrowthStep:  0.05,
+      },
+    },
+
+    {
+      id: 'engine-config-known-entity',
+      engine: 'known-entity-tracker',
+      params: {
+        // How fast a sense of an entity forms per encounter. Channel A: the metacog loop
+        // develops it UP from demonstrated `openness` (an open mind grows familiar faster).
+        familiarityGrowthRate: 0.15,
+        // Gain on the curiosity-to-resolve pull. Channel A: `openness` UP → feels the
+        // pull-to-know the half-known more readily.
+        curiosityGain:         1.0,
+        // How fast a reliability (track-record) judgment is revised per outcome. Channel A:
+        // `analytical` UP → updates its assessment more responsively from evidence.
+        reliabilityRate:       0.2,
+      },
+    },
+
+    // ── LLM / Summarizer (standard + full only) ──────────────────
+    {
+      id: 'engine-config-summarizer',
+      engine: 'summarizer',
+      params: {
+        summaryInterval,
+        summaryBufferSize,
+        maxCharsPerEntry: 600,
+      },
+    },
+  ]
+}

package/src/cognition/conversation.memory.ts

@@ -0,0 +1,81 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/conversation.memory.ts
+// ─────────────────────────────────────────────────────────────
+//
+// The single authority for the `conversation.exchange` working-memory item.
+//
+// A completed conversational turn is persisted as a `working_memory.item` state
+// entity so it flows through WorkingMemory → EpisodicConsolidator → vector. There
+// are two producers and they MUST agree on the shape:
+//
+//   - AuditionEngine        — reactive replies (someone spoke → the Will answered)
+//   - ProactiveCommunicator — proactive outreach (the Will decided to reach out)
+//
+// Both call `buildConversationExchange`; each applies the result via its own sink
+// (AuditionEngine → memory sink / setEntity; ProactiveCommunicator → StateCommands).
+// Per-caller knobs (activation, attendedCount, threadId, the id/createdAt stamps)
+// stay parameters; the row shape, tags, and summary live here once.
+//
+// Downstream consumers read the STRUCTURED fields (`userMessage` / `willReply` in
+// executive context + semantic clustering), with `summary` as the fallback — so
+// both producers now emit the structured fields, not just a summary string.
+// ─────────────────────────────────────────────────────────────
+
+export interface ConversationExchangeInput {
+  /** Stable entity id of the other party. */
+  entityId:       string
+  /** Display name; falls back to entityId. */
+  entityName?:    string
+  /** The inbound message. Empty string for proactive, master-initiated outreach. */
+  userMessage:    string
+  /** What the Will said. May be empty (formulated-but-unspoken still gets remembered). */
+  willReply:      string
+  /** Conversation thread, when the producer has one (replies do; outreach may not). */
+  threadId?:      string
+  /** Sim tick, when the producer is on-tick. Omitted off-tick. */
+  tick?:          number
+  /** WM activation. Default 0.85; AuditionEngine passes a confidence-derived value. */
+  activation?:    number
+  /** WM attended count. Default 3. */
+  attendedCount?: number
+  /** Unique id seed — the caller's clock (wallClock() under replay; never Date.now() in a scanned tree). */
+  idSeed:         number
+  /** Top-level createdAt. Pass on the StateCommands path; omit when setEntity stamps it. */
+  createdAt?:     number
+}
+
+export interface ConversationExchangeEntity {
+  id:         string
+  type:       'working_memory.item'
+  createdAt?: number
+  metadata:   Record<string, unknown>
+}
+
+export function buildConversationExchange( input: ConversationExchangeInput ): ConversationExchangeEntity {
+  const {
+    entityId, userMessage, willReply, threadId, tick,
+    activation = 0.85, attendedCount = 3, idSeed, createdAt,
+  } = input
+  const name = input.entityName ?? entityId
+
+  return {
+    id:   `wm-exchange-${ entityId }-${ idSeed }`,
+    type: 'working_memory.item',
+    ...( createdAt !== undefined ? { createdAt } : {} ),
+    metadata: {
+      wmType:        'conversation.exchange',
+      activation,
+      attendedCount,
+      tags:          [ 'conversation', 'exchange', `entity:${ entityId }` ],
+      summary:       userMessage
+        ? `${ name }: "${ userMessage.slice( 0, 100 ) }" → "${ willReply.slice( 0, 100 ) }"`
+        : `You → ${ name }: "${ willReply.slice( 0, 140 ) }"`,
+      entityId,
+      entityName:    name,
+      userMessage,
+      willReply,
+      ...( threadId ? { threadId } : {} ),
+      ...( tick !== undefined ? { tick } : {} ),
+    },
+  }
+}

package/src/cognition/event.log.ts

@@ -0,0 +1,116 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/event.log.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Append-only persistent event log.
+ *
+ * Every CognitiveEvent is written here before delivery so the full
+ * causal history of the system is reconstructible at any logical time.
+ * The log is the authoritative record; engine state is a derived projection.
+ *
+ * Storage: JSONL (one JSON object per line), pluggable backend via StorageAdapter.
+ * Auto-flushes at AUTO_FLUSH_SIZE entries or when flush() is called explicitly.
+ *
+ * In-memory ring buffer is capped at MAX_IN_MEMORY entries to prevent OOM.
+ */
+
+import type { StorageAdapter } from '#core/abstracts'
+import type { CognitiveEvent } from '#cognition/bus'
+
+const AUTO_FLUSH_SIZE = 100
+const MAX_IN_MEMORY   = 10_000
+
+export interface EventLog {
+  append( event: CognitiveEvent ): void
+  flush(): Promise<void>
+  recent( n?: number ): CognitiveEvent[]
+  since( logicalTime: number ): CognitiveEvent[]
+}
+
+export class DefaultEventLog implements EventLog {
+  private _path: string
+  private _storage: StorageAdapter
+  private _buffer: CognitiveEvent[] = []      // pending writes, not yet flushed
+  private _memory:  CognitiveEvent[] = []      // in-memory ring (capped)
+  private _flushing = false
+  private _pendingFlush: Promise<void> | null = null
+
+  constructor( path: string, storage: StorageAdapter ){
+    this._path    = path
+    this._storage = storage
+  }
+
+  append( event: CognitiveEvent ): void {
+    this._buffer.push( event )
+
+    // Ring buffer — drop oldest when full
+    if( this._memory.length >= MAX_IN_MEMORY )
+      this._memory.shift()
+    this._memory.push( event )
+
+    if( this._buffer.length >= AUTO_FLUSH_SIZE )
+      void this._triggerFlush()
+  }
+
+  async flush(): Promise<void> {
+    if( this._pendingFlush )
+      return this._pendingFlush
+    return this._triggerFlush()
+  }
+
+  recent( n = 100 ): CognitiveEvent[] {
+    return this._memory.slice( -n )
+  }
+
+  since( logicalTime: number ): CognitiveEvent[] {
+    return this._memory.filter( e => e.logicalTime >= logicalTime )
+  }
+
+  // ── Internal ─────────────────────────────────────────────
+
+  private async _triggerFlush(): Promise<void> {
+    if( this._flushing || this._buffer.length === 0 ) return
+
+    this._flushing = true
+    const batch = this._buffer.splice( 0 )
+
+    this._pendingFlush = this._writeBatch( batch ).finally( () => {
+      this._flushing    = false
+      this._pendingFlush = null
+    })
+
+    return this._pendingFlush
+  }
+
+  private async _writeBatch( batch: CognitiveEvent[] ): Promise<void> {
+    const lines  = batch.map( e => JSON.stringify( e ) ).join( '\n' ) + '\n'
+    let existing = ''
+
+    try {
+      if( await this._storage.exists( this._path ) )
+        existing = await this._storage.read( this._path )
+    } catch { /* file may not exist yet */ }
+
+    await this._storage.ensureDir?.( this._path.replace( /\/[^/]+$/, '' ) )
+    await this._storage.write( this._path, existing + lines )
+  }
+}
+
+/** No-op log for testing or when persistence is not needed. */
+export class NullEventLog implements EventLog {
+  private _memory: CognitiveEvent[] = []
+
+  append( event: CognitiveEvent ): void {
+    if( this._memory.length >= MAX_IN_MEMORY ) this._memory.shift()
+    this._memory.push( event )
+  }
+
+  flush(): Promise<void> { return Promise.resolve() }
+
+  recent( n = 100 ): CognitiveEvent[] { return this._memory.slice( -n ) }
+
+  since( logicalTime: number ): CognitiveEvent[] {
+    return this._memory.filter( e => e.logicalTime >= logicalTime )
+  }
+}