@mindot/will 0.1.0

package/src/stem/tracts/ack.reconciler.ts

@@ -0,0 +1,55 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/ack.reconciler.ts
+// ─────────────────────────────────────────────────────────────
+//
+// AckReconciler — idempotent dedup for the dual ack paths (Section 3).
+//
+// An outbound envelope can be acked twice: once via the socket.io emit callback
+// (fast, best-effort) and once via a discrete inbound event (durable across
+// reconnects — see SocketIoTransport). Both carry the same correlationId. This
+// keyed deduper guarantees the ack is applied exactly once: the FIRST ack for a
+// correlationId wins, every later one is a no-op.
+//
+// It is a pure deduper — classification (delivery vs result) and application
+// (confirmDelivery / confirmExecution) stay in TransportController, which holds
+// the collaborators. Bounded by a FIFO eviction window so it never grows without
+// limit on a long-lived Will.
+// ─────────────────────────────────────────────────────────────
+
+const DEFAULT_MAX_TRACKED = 10_000
+
+export class AckReconciler {
+  private readonly _seen  = new Set<string>()
+  private readonly _order: string[] = []
+  private readonly _max:   number
+
+  constructor( maxTracked: number = DEFAULT_MAX_TRACKED ){
+    this._max = maxTracked
+  }
+
+  /**
+   * Record an ack for `correlationId`. Returns true the FIRST time (caller should
+   * apply the ack), false on every subsequent call (caller drops it).
+   */
+  shouldApply( correlationId: string ): boolean {
+    if( this._seen.has( correlationId ) ) return false
+
+    this._seen.add( correlationId )
+    this._order.push( correlationId )
+    if( this._order.length > this._max ){
+      const evicted = this._order.shift()
+      if( evicted !== undefined ) this._seen.delete( evicted )
+    }
+    return true
+  }
+
+  /** Whether a correlationId has already been applied (without recording it). */
+  has( correlationId: string ): boolean { return this._seen.has( correlationId ) }
+
+  get size(): number { return this._seen.size }
+
+  clear(): void {
+    this._seen.clear()
+    this._order.length = 0
+  }
+}

package/src/stem/tracts/biography.writer.ts

@@ -0,0 +1,190 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/biography.writer.ts  —  per-Will session-biography writers
+// ─────────────────────────────────────────────────────────────
+//
+// BiographyWriter owns the session-biography disk writers extracted from
+// WillStem (R5-f): the behavioral session summary and the emotional
+// biography (real-time spike/sustained-arousal events + end-of-session
+// summary). All output is appended as JSONL under
+// `data/wills/{willId}/profiles/`.
+//
+// WillStem calls these from its lifecycle (pause/archive) and tick loop
+// (emotion-spike detection). The writers read (and, for the emotional
+// summary, flush) the instance's `_sessionBehavior` aggregate; they touch
+// only WillInstance fields, so they take the resolved instance directly
+// and derive the Will id from `instance.config.id`.
+//
+// Behaviour is preserved verbatim from the original WillStem methods;
+// this is a pure extract-collaborator refactor.
+// ─────────────────────────────────────────────────────────────
+
+import { logger } from '#core/logger'
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileLoggingEnabled } from '#stem/tracts/transport/stream.transport'
+import type { WillInstance } from '#stem/index'
+
+export class BiographyWriter {
+  /** Profile dirs already ensured this process — avoids an mkdir syscall per write. */
+  private readonly _ensuredDirs = new Set<string>()
+
+  /**
+   * Append one JSONL record to a Will's profiles/ dir. Dev-only (gated by
+   * `fileLoggingEnabled()`, matching SessionLogger) — in production this concern
+   * rides the `session_log`/transport path, not ephemeral local disk. The dir is
+   * ensured once per process, not per write.
+   */
+  private _append( willId: string, file: string, record: unknown ): void {
+    if( !fileLoggingEnabled() ) return
+
+    const dataDir = process.env[ 'WILL_DATA_DIR' ] ?? './data'
+    const dir     = join( dataDir, 'wills', willId, 'profiles' )
+    try {
+      if( !this._ensuredDirs.has( dir ) ){
+        mkdirSync( dir, { recursive: true } )
+        this._ensuredDirs.add( dir )
+      }
+      appendFileSync( join( dir, file ), JSON.stringify( record ) + '\n', 'utf8' )
+    } catch( err ){
+      logger.error( `[biography] ${file} write failed:`, err )
+    }
+  }
+  /**
+   * Compute and append a behavioral session summary to `behavioral.jsonl`.
+   * Captures action distribution, top/novel/impulsive action counts, avg
+   * confidence, valence/arousal ranges, and goal completion for the session.
+   * Topics discussed (TODO 7.2) intentionally omitted — requires NLP analysis
+   * on conversation content not available in state metrics.
+   */
+  writeSessionSummary( instance: WillInstance ): void {
+    const sb = instance._sessionBehavior
+    if( !sb ) return
+
+    const willId = instance.config.id
+
+    // Action type distribution from the agency repertoire's enactment counts.
+    const actionDist: Record<string, number> = {}
+    for( const skill of instance.cognition.schemaRepertoire.skills().values() )
+      if( skill.enactments > 0 ) actionDist[ skill.schema ] = skill.enactments
+
+    const topAction = Object.entries( actionDist )
+      .sort( ( a, b ) => b[1] - a[1] )[ 0 ]?.[ 0 ] ?? 'none'
+
+    // Action types tried exactly once signal exploratory/novel behavior
+    const novelActionCount = Object.values( actionDist ).filter( c => c === 1 ).length
+
+    const avgConfidence = sb.confidenceCount > 0
+      ? sb.confidenceSum / sb.confidenceCount
+      : null
+
+    const completionRate = sb.goalsTotal > 0
+      ? sb.goalsCompleted / sb.goalsTotal
+      : null
+
+    const summary = {
+      type:                'session_summary',
+      wallTime:            Date.now(),
+      sessionId:           instance.sessionLogger?.sessionId ?? 'unknown',
+      willId,
+      startTick:           sb.startTick,
+      endTick:             instance.tickCount,
+      tickCount:           instance.tickCount - sb.startTick,
+      actionDist,
+      topAction,
+      avgConfidence,
+      novelActionCount,
+      impulsiveActionCount: sb.impulsiveActionCount,
+      valenceRange:        { min: sb.valenceMin,  max: sb.valenceMax,  spread: sb.valenceMax  - sb.valenceMin  },
+      arousalRange:        { min: sb.arousalMin,  max: sb.arousalMax,  spread: sb.arousalMax  - sb.arousalMin  },
+      goalsTotal:          sb.goalsTotal,
+      goalsCompleted:      sb.goalsCompleted,
+      completionRate,
+    }
+
+    this._append( willId, 'behavioral.jsonl', summary )
+  }
+
+  /**
+   * Append one emotional event entry to `emotional_biography.jsonl`.
+   * Called real-time on spike detection and sustained-arousal episode end.
+   *
+   * @param evtType  'spike' | 'sustained_high_arousal'
+   * @param fields   Event-specific fields (tick, dimension, from/to/delta, etc.)
+   */
+  writeEmotionalEvent(
+    instance: WillInstance,
+    evtType:  'spike' | 'sustained_high_arousal',
+    fields:   Record<string, unknown>
+  ): void {
+    const willId = instance.config.id
+
+    const entry = {
+      type:      evtType,
+      wallTime:  Date.now(),
+      sessionId: instance.sessionLogger?.sessionId ?? 'unknown',
+      willId,
+      ...fields,
+    }
+
+    this._append( willId, 'emotional_biography.jsonl', entry )
+  }
+
+  /**
+   * Compute and append a session emotional biography summary to
+   * `emotional_biography.jsonl`. Called at session end (pause or archive).
+   * Flushes any open sustained-arousal streak, then writes a `session_summary`
+   * entry covering dominant mood, valence/arousal arcs, spike count, and the
+   * number of completed sustained-high-arousal episodes.
+   *
+   * PMA tooling can read across all `session_summary` entries to build a cross-
+   * session emotional biography.
+   */
+  writeEmotionalBiographySummary( instance: WillInstance ): void {
+    const sb = instance._sessionBehavior
+    if( !sb || sb.avgValenceCount === 0 ) return
+
+    const willId = instance.config.id
+
+    // Flush any open sustained-arousal streak before writing the summary.
+    if( sb.highArousalStreak >= 10 ){
+      sb.sustainedEpisodes++
+      this.writeEmotionalEvent( instance, 'sustained_high_arousal', {
+        startTick:     instance.tickCount - sb.highArousalStreak,
+        durationTicks: sb.highArousalStreak,
+        tick:          instance.tickCount,
+      })
+      sb.highArousalStreak = 0
+    }
+
+    const avgValence    = sb.avgValenceSum / sb.avgValenceCount
+    const dominantMood  = avgValence > 0.15 ? 'positive' : avgValence < -0.10 ? 'negative' : 'neutral'
+
+    const summary = {
+      type:                         'session_summary',
+      wallTime:                     Date.now(),
+      sessionId:                    instance.sessionLogger?.sessionId ?? 'unknown',
+      willId,
+      startTick:                    sb.startTick,
+      endTick:                      instance.tickCount,
+      tickCount:                    instance.tickCount - sb.startTick,
+      dominantMood,
+      avgValence:                   Math.round( avgValence * 1000 ) / 1000,
+      valenceArc: {
+        start: Math.round( sb.valenceStart * 1000 ) / 1000,
+        end:   Math.round( sb.valenceEnd   * 1000 ) / 1000,
+        min:   Math.round( sb.valenceMin   * 1000 ) / 1000,
+        max:   Math.round( sb.valenceMax   * 1000 ) / 1000,
+      },
+      arousalArc: {
+        start: Math.round( sb.arousalStart * 1000 ) / 1000,
+        end:   Math.round( sb.arousalEnd   * 1000 ) / 1000,
+        min:   Math.round( sb.arousalMin   * 1000 ) / 1000,
+        max:   Math.round( sb.arousalMax   * 1000 ) / 1000,
+      },
+      spikeCount:                         sb.spikeCount,
+      sustainedHighArousalEpisodes:        sb.sustainedEpisodes,
+    }
+
+    this._append( willId, 'emotional_biography.jsonl', summary )
+  }
+}

package/src/stem/tracts/effector.controller.ts

@@ -0,0 +1,143 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/effector.controller.ts  —  per-Will external-effector subsystem
+// ─────────────────────────────────────────────────────────────
+//
+// effectorController owns the external-effector machinery extracted from
+// WillStem (R5-d): the runtime allow-list (setAllowed), the host
+// execution-feedback / reafference loop (confirmExecution), buffering of
+// externally-dispatched invocations off the `agency.invocation` bus event
+// (bufferInvocation), and draining that buffer for the delivery layer (drain).
+//
+// Agency-native (no legacy effector/decision.record stack): the MotorSchemaExecutor
+// holds a host-owned action as an 'awaiting' `agency.intent` and publishes
+// `agency.invocation` (carrying the intentId as the correlation handle). The host
+// executes it and acks; `confirmExecution` turns that ack into an `agency.outcome`
+// via `reconcileInvocation`, which the ReafferenceEngine consumes — learning the
+// real result, freeing the awaiting intent, and (when the intent was a plan's
+// frontier step) emitting the `action.outcome` the PlanningEngine advances on.
+//
+// The ops touch only WillInstance fields (no Will id needed), so these
+// methods take the resolved instance directly. WillStem still validates
+// existence via _get(id) before delegating.
+// ─────────────────────────────────────────────────────────────
+
+import { logger } from '#core/logger'
+import { reconcileInvocation } from '#agency/reconcile.learning'
+import type { effectorInvocation } from '#types'
+import type { WillInstance } from '#stem/index'
+
+export class effectorController {
+  /**
+   * Update the set of allowed communication effectors at runtime via AccessGrants
+   * (the permission / sense gate the senses + reply path read).
+   */
+  setAllowed( instance: WillInstance, effectors: string[] | null ): void {
+    instance.cognition.accessGrants.setAllowed( effectors )
+  }
+
+  /**
+   * Buffer a host-owned effector invocation for delivery. Called from the WillStem
+   * `agency.invocation` bus subscription with the event payload
+   * (`{ schema, intentId, targetEntityId, parameters, tick }`). The awaiting
+   * `agency.intent` id is the **correlation handle** (`decisionRecordId`): the host
+   * echoes it on its result-ack, and `confirmExecution` uses it to find the intent.
+   */
+  bufferInvocation( instance: WillInstance, payload: Record<string, unknown> ): void {
+    const intentId = ( payload.intentId as string ) ?? ''
+    instance.pendingEffectorInvocations.push({
+      id:               intentId,
+      decisionRecordId: intentId,   // correlation handle — the awaiting agency.intent id
+      effectorName:      ( payload.schema as string ) ?? '',
+      parameters:       ( payload.parameters as Record<string, unknown> ) ?? {},
+      targetEntityId:   payload.targetEntityId as string | undefined,
+      reasoning:        ( payload.reasoning as string ) ?? '',
+      tick:             ( payload.tick as number ) ?? 0,
+      timestamp:        Date.now()
+    })
+  }
+
+  /**
+   * Drain all pending external effector invocations.
+   * Called by the SSE delivery layer each tick after drainOutbox.
+   */
+  drain( instance: WillInstance ): effectorInvocation[] {
+    return instance.pendingEffectorInvocations.splice( 0 )
+  }
+
+  // ── External Effector Feedback (agency-native reafference) ─────────────────
+  /**
+   * Called by the host/WorldInterface after executing a host-owned effector.
+   * `invocationId` is the correlation handle the host echoed — the awaiting
+   * `agency.intent`'s id (= the `decisionRecordId` field of the effectorInvocation).
+   *
+   * It reconciles the ack into an `agency.outcome` (via `reconcileInvocation`),
+   * carrying the intent's efference copy (predicted reward/valence) so surprise is
+   * honest, and its plan provenance (planId/stepId) when it was a plan's frontier
+   * step. The ReafferenceEngine consumes that next tick: it learns the real result,
+   * frees the awaiting intent, and — for a plan-tagged outcome — emits the
+   * `action.outcome` the PlanningEngine advances on. No decision.record, no legacy
+   * `effector.confirmed`: the agency pipeline owns the loop end to end.
+   */
+  confirmExecution(
+    instance:     WillInstance,
+    invocationId: string,
+    result: {
+      success:     boolean
+      description: string
+      metrics?:    Record<string, number>
+    },
+  ): void {
+    const tick = instance.tickCount
+
+    const intent = instance.simulation.stateManager.snapshot().entities.get( invocationId )
+    if( !intent || intent.type !== 'agency.intent' ){
+      // No awaiting intent for this id. Expected when the executor's 15-tick await
+      // timeout already abandoned it (writing a failed outcome + advancing any plan)
+      // before the host's late ack arrived, or the id is unknown. Drop the straggler.
+      logger.warn( `[effector] confirmExecution: no awaiting agency.intent "${invocationId}" (timed out / already reconciled?) — ignored` )
+      return
+    }
+
+    const m       = ( intent.metadata ?? {} ) as Record<string, unknown>
+    const schema  = ( m['schema'] as string ) ?? 'unknown'
+    const predicted = {
+      reward:  num( m['predictedReward'],  num( m['expectedReward'],  0.5 ) ),
+      valence: num( m['predictedValence'], num( m['expectedValence'], 0 ) ),
+    }
+    const provenance = { planId: m['planId'] as string | undefined, stepId: m['stepId'] as string | undefined }
+
+    // Reconcile → agency.outcome. ReafferenceEngine consumes it next tick (learn +
+    // free the intent + emit the plan's action.outcome when plan-tagged).
+    instance.simulation.stateManager.setEntity(
+      reconcileInvocation( invocationId, schema, result, tick, predicted, provenance )
+    )
+
+    // Optional host-supplied metric deltas (e.g. the world moved a body metric).
+    // Validate each value is a finite number before it touches simulation state —
+    // a NaN/Infinity/garbage value from a buggy host would persist and corrupt
+    // cognition (it isn't recomputed away like blended affect is).
+    if( result.metrics )
+      for( const [ k, v ] of Object.entries( result.metrics ) ){
+        if( typeof v === 'number' && Number.isFinite( v ) )
+          instance.simulation.stateManager.setMetric( k, v )
+        else
+          logger.warn( `[effector] confirmExecution: dropped non-finite metric "${k}"=${String( v )} from host ack (${schema})` )
+      }
+
+    instance.sessionLogger?.write({
+      type:                'action.outcome',
+      tick,
+      actionType:          schema,
+      success:             result.success,
+      outcome:             result.description.slice( 0, 300 ),
+      outcomeQuality:      result.success ? 0.8 : 0.2,
+      confirmedExternally: true,
+    } as never)
+
+    logger.info( `[effector] ✓ reconciled ${result.success ? 'success' : 'failure'}: intent "${invocationId}" (${schema})` )
+  }
+}
+
+function num( v: unknown, fallback: number ): number {
+  return typeof v === 'number' && Number.isFinite( v ) ? v : fallback
+}

package/src/stem/tracts/health.reporter.ts

@@ -0,0 +1,113 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/health.reporter.ts  —  per-Will cognitive-health reporter
+// ─────────────────────────────────────────────────────────────
+//
+// HealthReporter owns the composite cognitive-health view extracted from
+// WillStem (R5-f2): a pure, read-only computation over a running Will's
+// belief quality, affect state, and goal state, collapsed into a single
+// `overallScore` and a 'healthy' | 'drifting' | 'degraded' status band.
+// Intended for developer dashboards and platform monitoring.
+//
+// WillStem.getCognitiveHealth delegates here. The op touches only
+// WillInstance fields (no Will id needed), so this method takes the
+// resolved instance directly; WillStem still validates existence via
+// _get(id) before delegating.
+//
+// Behaviour is preserved verbatim from the original WillStem method;
+// this is a pure extract-collaborator refactor.
+// ─────────────────────────────────────────────────────────────
+
+import type { CognitiveHealth, WillInstance } from '#stem/index'
+
+/** Round to 3 decimals — keeps health payloads readable. */
+const r3 = ( n: number ): number => Math.round( n * 1000 ) / 1000
+
+export class HealthReporter {
+  /**
+   * Returns a composite health summary for a running Will.
+   * Intended for developer dashboards and platform monitoring.
+   *
+   * Status bands:
+   *   healthy  — normal operating range
+   *   drifting — one or more indicators approaching problematic thresholds
+   *   degraded — one or more indicators clearly outside healthy range
+   */
+  report( instance: WillInstance ): CognitiveHealth {
+    const
+    snap     = instance.simulation.stateManager.snapshot(),
+    beliefs  = instance.cognition.semanticIntegrator.getBeliefs(),
+    tick     = instance.tickCount
+
+    // ── Belief quality ──────────────────────────────────────────
+    const totalBeliefs = beliefs.length
+    let
+    confidenceSum = 0,
+    highRiskCount = 0
+
+    for( const b of beliefs ){
+      confidenceSum += b.confidence
+      if( b.confidence > 0.85 && b.supportingEpisodes < 3 ) highRiskCount++
+    }
+
+    const
+    avgConfidence = totalBeliefs > 0 ? confidenceSum / totalBeliefs : 0,
+    // Confidence health peaks at ~0.62 and falls off linearly toward either
+    // extreme (over-confidence and chronic doubt are both unhealthy).
+    beliefScore = totalBeliefs === 0
+      ? 0.5  // no beliefs yet — neutral
+      : Math.max( 0,
+          1.0
+          - Math.abs( avgConfidence - 0.62 ) * 1.5  // deviation from ideal
+          - ( highRiskCount / Math.max( totalBeliefs, 1 ) ) * 0.8
+        )
+
+    // ── Affect state ────────────────────────────────────────────
+    // Negative emotions AND sustained low valence both signal distress — the
+    // latter is exactly what the executive early-fires on, so health tracks it too.
+    const
+    valence      = snap.metrics.get('affect.valence')     ?? 0,
+    frustration  = snap.metrics.get('emotion.frustration') ?? 0,
+    irritability = snap.metrics.get('emotion.irritability') ?? 0,
+    stress       = snap.metrics.get('stress.load')         ?? 0,
+    isElevated   = irritability > 0.55 || frustration > 0.65 || stress > 0.7,
+    affectScore  = Math.max( 0,
+      1.0
+      - Math.max( 0, frustration  - 0.3  ) * 0.8
+      - Math.max( 0, irritability - 0.3  ) * 0.8
+      - Math.max( 0, stress       - 0.4  ) * 0.6
+      - Math.max( 0, -valence     - 0.15 ) * 0.7   // sustained low valence drags health down
+    )
+
+    // ── Goal state ──────────────────────────────────────────────
+    // Use the O(1) type index rather than scanning every entity — health is polled.
+    let
+    activeGoals = 0,
+    totalGoals  = 0
+
+    for( const entity of instance.simulation.stateManager.getEntitiesByType('goal') ){
+      totalGoals++
+      const s = entity.metadata?.status
+      if( s === 'active' || s === 'in_progress' ) activeGoals++
+    }
+
+    const goalScore = totalGoals === 0
+      ? 0.7   // no goals yet — mildly healthy
+      : Math.min( 1, 0.4 + ( activeGoals / totalGoals ) * 0.6 )
+
+    // ── Composite ───────────────────────────────────────────────
+    const
+    overallScore = ( beliefScore * 0.4 ) + ( affectScore * 0.4 ) + ( goalScore * 0.2 ),
+    status: CognitiveHealth['status'] =
+      overallScore >= 0.65 ? 'healthy'  :
+      overallScore >= 0.40 ? 'drifting' : 'degraded'
+
+    return {
+      tick,
+      status,
+      overallScore: r3( overallScore ),
+      beliefs: { total: totalBeliefs, avgConfidence: r3( avgConfidence ), highRisk: highRiskCount },
+      affect:  { valence: r3( valence ), frustration: r3( frustration ), irritability: r3( irritability ), stress: r3( stress ), isElevated },
+      goals:   { total: totalGoals, active: activeGoals }
+    }
+  }
+}

package/src/stem/tracts/inbound.queue.ts

@@ -0,0 +1,54 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/inbound.queue.ts
+// ─────────────────────────────────────────────────────────────
+//
+// InboundQueue — the determinism linchpin for external I/O.
+//
+// Every InboundEnvelope from the ExternalTransport (messages, percepts, acks)
+// is enqueued here on arrival and applied LATER, at a fixed point in the tick
+// loop, with a logicalTime (tick) stamp. This is what keeps a live, async,
+// non-deterministic socket compatible with the replay-deterministic core:
+//   - arrival is decoupled from application
+//   - application happens on-tick, in FIFO order, stamped to that tick
+//   - the replay recorder logs each tick's drained batch; replay re-injects it
+//
+// The queue holds NO sockets and applies NOTHING itself — it is a buffer.
+// ─────────────────────────────────────────────────────────────
+
+import type { InboundEnvelope } from './transport/types'
+
+/** An inbound envelope paired with the tick it was applied on (set at drain). */
+export interface StampedInbound {
+  envelope:    InboundEnvelope
+  /** Tick at which this was drained + applied. Assigned by drain(tick). */
+  appliedTick: number
+}
+
+export class InboundQueue {
+  private _pending: InboundEnvelope[] = []
+
+  /** Buffer an inbound envelope. Called from the transport handler — never applies. */
+  enqueue( env: InboundEnvelope ): void {
+    this._pending.push( env )
+  }
+
+  /** Number of envelopes waiting to be applied. */
+  get size(): number { return this._pending.length }
+
+  /**
+   * Remove and return all pending envelopes, stamped with the given tick.
+   * Called once per tick by the stem before simulation.step(). FIFO order is
+   * preserved so application is deterministic given the recorded batch.
+   */
+  drain( tick: number ): StampedInbound[] {
+    if( this._pending.length === 0 ) return []
+    const batch = this._pending
+    this._pending = []
+    return batch.map( envelope => ({ envelope, appliedTick: tick }) )
+  }
+
+  /** Discard everything without applying (teardown). */
+  clear(): void {
+    this._pending = []
+  }
+}