@mindot/will 0.1.0

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

@@ -0,0 +1,167 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/outbox.controller.ts  —  per-Will messaging / outbox subsystem
+// ─────────────────────────────────────────────────────────────
+//
+// OutboxController owns the outbound-message machinery extracted from
+// WillStem (R5-c): draining / peeking / re-queuing the per-Will outbox,
+// the message-delivery receipt (reafference percept), and TTL expiry of
+// stale messages. WillStem delegates drainOutbox/peekOutbox/
+// requeueToOutbox/confirmMessageDelivery here and calls expireStale()
+// from its tick loop, so the god-object no longer owns this concern.
+//
+// The outbox 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.
+//
+// OUTBOX_TTL_TICKS lives here (source of truth) and is re-exported from
+// #stem/index for backward-compatible public-API consumers.
+//
+// Behaviour is preserved verbatim from the original WillStem methods;
+// this is a pure extract-collaborator refactor.
+// ─────────────────────────────────────────────────────────────
+
+import type { OutboxMessage } from '#types'
+import type { WillInstance } from '#stem/index'
+
+/**
+ * Number of ticks an undelivered outbox message survives before it is
+ * expired. Override via WILL_OUTBOX_TTL_TICKS. Default: 100 ticks.
+ */
+export const OUTBOX_TTL_TICKS = parseInt( process.env.WILL_OUTBOX_TTL_TICKS ?? '100')
+
+export class OutboxController {
+  /**
+   * Drain all queued outbound messages from the Will's outbox.
+   * Called by the SSE/webhook delivery layer to retrieve messages.
+   * Stamps each message with the current tick if createdAtTick is 0.
+   */
+  drain( instance: WillInstance ): OutboxMessage[] {
+    const messages = instance.outbox.splice( 0 )
+
+    for( const msg of messages )
+      if( msg.createdAtTick === 0 ) msg.createdAtTick = instance.tickCount
+
+    return messages
+  }
+
+  /** Peek at outbox without draining it. */
+  peek( instance: WillInstance ): readonly OutboxMessage[] {
+    return instance.outbox
+  }
+
+  /**
+   * Re-queue messages that were drained but not successfully delivered.
+   * Prepends them so they are the first to be drained on the next tick.
+   */
+  requeue( instance: WillInstance, messages: OutboxMessage[] ): void {
+    if( messages.length === 0 ) return
+    instance.outbox.unshift( ...messages )
+  }
+
+  /**
+   * Called by the delivery layer (SSE consumer or webhook) after a message
+   * has been confirmed received by the target entity.
+   *
+   * Writes a message.delivery percept so the mind perceives its own words
+   * landing — the "ear hears the word you spoke" reafference signal.
+   */
+  confirmDelivery( instance: WillInstance, messageId: string, delivered: boolean ): void {
+    const tick = instance.tickCount
+
+    // 1. Update the conversation.sent entity that tracks this outbox message.
+    //    ProactiveCommunicator stores outboxMessageIds in the entity metadata (11.3)
+    //    so we can correlate messageId → sent entity without extra bookkeeping.
+    //    Use the O(1) type index rather than scanning every entity.
+    for( const entity of instance.simulation.stateManager.getEntitiesByType('conversation.sent') ){
+      const ids = entity.metadata?.outboxMessageIds as string[] | undefined
+      if( !ids?.includes( messageId ) ) continue
+
+      instance.simulation.stateManager.setEntity({
+        id:        entity.id,
+        type:      'conversation.sent',
+        createdAt: entity.createdAt,
+        updatedAt: Date.now(),
+        metadata: {
+          ...entity.metadata,
+          delivered,
+          deliveredAt: tick,
+        },
+      })
+
+      break
+    }
+
+    // 2. Write a percept so Exteroception perceives delivery ("ear hears the word")
+    instance.simulation.stateManager.setEntity({
+      id:        `msg-delivered-${messageId}`,
+      type:      'percept',
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      metadata: {
+        category:   'message-delivery',
+        summary:    delivered
+          ? `Your message was delivered successfully.`
+          : `Your message failed to reach the recipient.`,
+        salience:   delivered ? 0.35 : 0.6,
+        changeType: delivered ? 'delivered' : 'failed',
+        messageId,
+      },
+    })
+
+    instance.sessionLogger?.write({
+      type:      'conversation.delivery',
+      tick,
+      messageId,
+      delivered,
+    } as any)
+  }
+
+  /**
+   * Expire stale outbox messages. Called from the Will tick loop each tick.
+   *
+   * Messages created with createdAtTick=0 (OutboxWriter default) have not yet been
+   * stamped with a real tick — stamp them now so the TTL clock starts here rather
+   * than instantly expiring them (age = tickCount - 0 would be >> TTL).
+   * Mutate in-place (splice, not filter) so the shared outbox array (held by
+   * OutboxWriter) continues to reference the same object after TTL cleanup.
+   * Array.filter() would create a new array and silently detach the shared ref.
+   */
+  expireStale( instance: WillInstance ): void {
+    const expiredMessages: OutboxMessage[] = []
+
+    for( let i = instance.outbox.length - 1; i >= 0; i-- ){
+      const msg = instance.outbox[ i ]!
+      if( msg.createdAtTick === 0 ) msg.createdAtTick = instance.tickCount
+
+      const age = instance.tickCount - msg.createdAtTick
+      if( age > OUTBOX_TTL_TICKS ){
+        expiredMessages.push( msg )
+        instance.outbox.splice( i, 1 )
+      }
+    }
+
+    for( const msg of expiredMessages ){
+      instance.sessionLogger?.write({
+        type:           'outbox.expire',
+        tick:           instance.tickCount,
+        messageId:      msg.id,
+        targetEntityId: msg.targetEntityId,
+        effectorName:    msg.effectorName,
+        ageAtExpiry:    instance.tickCount - msg.createdAtTick,
+      })
+
+      try {
+        instance.simulation.eventBus.publish(
+          {
+            type:    'communication.outbound.undelivered',
+            source:  'will-manager',
+            payload: { messageId: msg.id, targetEntityId: msg.targetEntityId, effectorName: msg.effectorName },
+          },
+          instance.simulation.context,
+          instance.tickCount as any,
+        )
+      }
+      catch { /* event bus may not be flushing — non-critical */ }
+    }
+  }
+}

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

@@ -0,0 +1,133 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/outbox.writer.ts  —  the outbox PRODUCER primitive
+// ─────────────────────────────────────────────────────────────
+//
+// OutboxWriter is the producer half of the outbox, paired with OutboxController
+// (the consumer half: drain / expire / confirm). It owns the ONE canonical
+// outbox-row shape (id format, default fields) and the `conversation.out`
+// session-audit log for facet replies. Everything that wants to put words on the
+// wire goes through here, so the row shape lives in exactly one place.
+//
+// It is a leaf primitive — constructed with the shared `outbox` array (no
+// WillInstance) and injected into both producers:
+//   - ProactiveCommunicator  → enqueue()      (effector-dispatch path)
+//   - AuditionEngine         → enqueueReply()  (facet-reply fast-path)
+//
+// There is NO gating here. Emission is authorized upstream by AccessGrants
+// (the `talk`/`text`/… grants), checked by the calling engine.
+// ─────────────────────────────────────────────────────────────
+
+import { logger } from '#core/logger'
+import type { OutboxMessage } from '#types'
+import type { SessionLogger } from './session.logger'
+
+/** The caller-supplied fields of an outbox row; the writer stamps id + defaults. */
+export interface OutboxRow {
+  targetEntityId:    string
+  content:           string
+  effectorName:       OutboxMessage[ 'effectorName' ]
+  targetEntityName?: string
+  gestureType?:      string
+  replyToMessageId?: string
+  threadId?:         string
+}
+
+export class OutboxWriter {
+  private _outbox:        OutboxMessage[]
+  private _willId:        string
+  private _sessionLogger: SessionLogger | null = null
+  /**
+   * Per-Will monotonic id counter. Deterministic for replay: the writer is
+   * created once per Will and `enqueue` is called in the same order on a
+   * re-execution, so the ids reproduce exactly (vs the old Date.now()+random,
+   * which made the embedded ids in `conversation.sent` diverge every run).
+   */
+  private _seq = 0
+
+  constructor( opts: { outbox?: OutboxMessage[]; willId?: string } = {} ){
+    this._outbox = opts.outbox ?? []
+    this._willId = opts.willId ?? 'will'
+  }
+
+  attachSessionLogger( logger: SessionLogger | null ): void {
+    this._sessionLogger = logger
+  }
+
+  private _genId( suffix = '' ): string {
+    return `outbox-${ this._willId }-${ ++this._seq }${ suffix }`
+  }
+
+  /**
+   * Push one canonical outbox row and return its generated id. The single point
+   * where the row shape is materialized — all producers funnel through here.
+   */
+  enqueue( row: OutboxRow, idSuffix = '' ): string {
+    const id = this._genId( idSuffix )
+    this._outbox.push({
+      id,
+      targetEntityId:   row.targetEntityId,
+      ...( row.targetEntityName !== undefined ? { targetEntityName: row.targetEntityName } : {} ),
+      content:          row.content,
+      effectorName:      row.effectorName,
+      ...( row.gestureType      ? { gestureType:      row.gestureType }      : {} ),
+      ...( row.replyToMessageId ? { replyToMessageId: row.replyToMessageId } : {} ),
+      ...( row.threadId         ? { threadId:         row.threadId }         : {} ),
+      deliveryStatus:   'pending',
+      createdAtTick:    0,
+      createdAt:        Date.now(),
+    })
+    return id
+  }
+
+  /**
+   * Reply convenience for AuditionEngine (formerly ProactiveCommunicator.deliverReply).
+   *
+   * Pushes the facet's reply bubbles as `text` outbox rows and writes the
+   * `conversation.out` audit entry. Returns the generated message ids (always
+   * generated, for delivery correlation), or an empty array when there are no
+   * bubbles.
+   *
+   * `pushToOutbox` (default true) controls only whether a copy is queued: set
+   * false when an ExternalTransport already delivered the reply via the fast-path
+   * (avoids double delivery) — the ids are still generated and returned.
+   */
+  enqueueReply( opts: {
+    entityId:      string
+    entityName:    string
+    bubbles:       string[]
+    threadId?:     string
+    tick?:         number
+    pushToOutbox?: boolean
+  } ): string[] {
+    const { entityId, entityName, bubbles, threadId, tick = 0, pushToOutbox = true } = opts
+
+    if( bubbles.length === 0 ) return []
+
+    const ids: string[] = []
+    bubbles.forEach( ( bubble, i ) => {
+      if( !pushToOutbox ){ ids.push( this._genId( `-${ i }` ) ); return }
+      logger.info(`[outbox-writer] reply → ${ entityId } bubble[${ i }] "${ bubble.slice( 0, 80 ) }"`)
+      ids.push( this.enqueue({
+        targetEntityId:   entityId,
+        targetEntityName: entityName,
+        content:          bubble,
+        effectorName:      'text',
+        threadId,
+      }, `-${ i }` ) )
+    } )
+
+    this._sessionLogger?.write({
+      type:             'conversation.out',
+      tick,
+      targetEntityId:   entityId,
+      targetEntityName: entityName,
+      messageCount:     bubbles.length,
+      messages:         bubbles.map( b => b.slice( 0, 300 ) ),
+      preview:          bubbles[0]?.slice( 0, 100 ) ?? '',
+      threadId,
+      source:           'audition-facet',
+    })
+
+    return ids
+  }
+}

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

@@ -0,0 +1,109 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/pma.controller.ts  —  per-Will PMA (portable mind archive)
+// ─────────────────────────────────────────────────────────────
+//
+// PMAController owns the PMA subsystem extracted from WillStem (R5-b):
+// the distiller (state → portable snapshot), the loader (snapshot →
+// seeded Will), and the reconstruction-fidelity eval harness. WillStem
+// delegates its loadPMA/distillPMA/runPMAEval methods here, resolving the
+// WillInstance (and validating existence) before each call.
+//
+// Behaviour is preserved verbatim from the original WillStem methods;
+// this is a pure extract-collaborator refactor.
+// ─────────────────────────────────────────────────────────────
+
+import { PMADistiller, PMALoader, type PMASnapshot } from '../../pma'
+import { PMAEvalHarness, type ReconstructionFidelityReport } from '../../pma/eval'
+import { validateWillIdentity } from '../guards/identity.guard'
+import { logger } from '#core/logger'
+import type { WillInstance } from '#stem/index'
+
+export class PMAController {
+  private readonly _distiller   = new PMADistiller()
+  private readonly _loader      = new PMALoader()
+  private readonly _evalHarness = new PMAEvalHarness()
+
+  /**
+   * Load a PMASnapshot into a paused or freshly-created Will. The Will must
+   * not be active (status 'paused' or 'initializing'); seeding an active Will
+   * with existing beliefs may cause unintended merges.
+   */
+  load( id: string, instance: WillInstance, pma: PMASnapshot ): void {
+    if( instance.status === 'active' )
+      throw new Error(`Cannot load PMA into an active Will (${id}). Pause first.`)
+
+    // Re-validate the artifact's persona at the load boundary (Phase 2): a stored
+    // or tampered PMA must not inject a collapsed / colliding / injected self on
+    // reload, the same way creation guards the operator-supplied identity.
+    const guard = validateWillIdentity({ identity: {
+      prompt: pma.identity.prompt,
+      values: pma.identity.values,
+      traits: pma.identity.traits,
+      style:  pma.identity.style,
+    } })
+    if( !guard.ok )
+      throw new Error(`Invalid PMA identity for "${id}": ${ guard.errors.join('; ') }`)
+    for( const w of guard.warnings )
+      logger.warn(`[identity-guard] PMA ${id}: ${w}`)
+
+    const safePma: PMASnapshot = { ...pma, identity: { ...pma.identity, ...guard.sanitized.identity } }
+
+    this._loader.load(
+      safePma,
+      instance.simulation,
+      instance.cognition,
+    )
+  }
+
+  /**
+   * Distill the current state of a Will into a portable PMASnapshot. Reads
+   * simulation state and JSONL profile logs. Does NOT pause or modify the
+   * Will — safe to call while active.
+   */
+  distill( id: string, instance: WillInstance ): PMASnapshot {
+    const
+    state     = instance.simulation.stateManager.snapshot(),
+    sessionId = instance.sessionLogger?.sessionId ?? 'unknown',
+    dataDir   = process.env[ 'WILL_DATA_DIR' ] ?? './data'
+
+    return this._distiller.distill(
+      id,
+      instance.config.name ?? id,
+      state,
+      sessionId,
+      dataDir,
+      instance.cognition.schemaRepertoire,
+    )
+  }
+
+  /**
+   * Distill the Will and score how faithfully the PMA reconstructs it.
+   * `vsOriginal` (with `behavioral`) captures the original's probe baseline
+   * before evaluating, for reconstruction-vs-original behavioral fidelity.
+   *
+   * ⚠️ Not read-only when `behavioral` is set: the probe phase runs probes against
+   * the LIVE Will, perturbing its state. Don't call it on a production Will you
+   * need pristine — distil + eval a paused clone instead.
+   */
+  async runEval(
+    id:       string,
+    instance: WillInstance,
+    opts:     { behavioral?: boolean; vsOriginal?: boolean } = {}
+  ): Promise<ReconstructionFidelityReport> {
+    // Distil the CLEAN state first — capturing the baseline below probes (and
+    // therefore mutates) the live original, so order matters.
+    const pma = this.distill( id, instance )
+
+    let baselineDist: Record<string, Record<string, number>> | undefined
+    if( opts.behavioral && opts.vsOriginal )
+      baselineDist = await this._evalHarness.captureProbeBaseline(
+        instance.simulation,
+        instance.cognition,
+      )
+
+    return this._evalHarness.evaluate( pma, instance.config, {
+      runBehavioralProbes: opts.behavioral ?? false,
+      baselineDist,
+    })
+  }
+}

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

@@ -0,0 +1,177 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/replay.controller.ts  —  per-Will record/replay subsystem
+// ─────────────────────────────────────────────────────────────
+//
+// ReplayController owns the record/replay machinery extracted from
+// WillStem (R5-a): the ReplayManager, the set of active recorders, the
+// completed-replay metadata cache, and the on-disk replay paths — all
+// keyed by Will id. WillStem delegates its start/stop/getMeta/list/compare
+// replay methods here, so the god-object no longer owns this concern.
+//
+// Behaviour is preserved verbatim from the original WillStem methods;
+// this is a pure extract-collaborator refactor.
+// ─────────────────────────────────────────────────────────────
+
+import { mkdirSync, existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  ReplayManager,
+  type DefaultReplayRecorder,
+  type ReplayMetadata,
+  type ReplayComparison,
+} from '#core/replay'
+import { setCompletionRecorder, clearCompletionRecorder } from '#core/completion.recorder'
+import { setInboundRecorder, clearInboundRecorder } from '#core/inbound.recorder'
+import type { WillInstance } from '#stem/index'
+
+export class ReplayController {
+  private readonly _replayManager    = new ReplayManager()
+  private readonly _activeRecorders  = new Map<string, { runId: string; unsub: () => void; recorder: DefaultReplayRecorder }>()
+  private readonly _completedReplays = new Map<string, ReplayMetadata>()
+  private readonly _replayPaths      = new Map<string, string>()
+
+  /**
+   * Begin recording the given Will's ticks (and LLM completions) into a new
+   * replay run. Returns the run id. The caller is responsible for resolving
+   * `instance` (and thereby validating the Will exists) before calling.
+   */
+  start( id: string, instance: WillInstance ): string {
+    if( this._activeRecorders.has( id ) )
+      throw new Error(`Replay already active for Will: ${id}`)
+
+    const runId    = `replay-${Date.now()}-${Math.random().toString(36).slice( 2, 8 )}`
+
+    // Pre-create the replay dir so flush() can persist segments incrementally
+    // (stop() saves the consolidated file into the same dir).
+    const dataDir = process.env[ 'WILL_DATA_DIR' ] ?? './data'
+    const dir     = join( dataDir, 'wills', id, 'replays' )
+    mkdirSync( dir, { recursive: true } )
+
+    const recorder = this._replayManager.createRecorder( id, runId, undefined, {
+      flushBasePath: join( dir, runId ),
+    })
+
+    const unsub = ( instance.simulation.orchestrator as any ).onAfterTick(
+      ( tick: number ) => recorder.recordTick( tick, [] )
+    )
+
+    // Route this Will's LLM completions + external inbound into the recorder
+    // while recording is active (both are non-deterministic inputs for replay).
+    setCompletionRecorder( id, recorder )
+    setInboundRecorder( id, recorder )
+
+    this._activeRecorders.set( id, { runId, unsub, recorder } )
+    return runId
+  }
+
+  async stop( id: string ): Promise<ReplayMetadata> {
+    const active = this._activeRecorders.get( id )
+    if( !active ) throw new Error(`No active replay for Will: ${id}`)
+
+    active.unsub()
+    clearCompletionRecorder( id )
+    clearInboundRecorder( id )
+    this._activeRecorders.delete( id )
+
+    const dataDir = process.env[ 'WILL_DATA_DIR' ] ?? './data'
+    const dir     = join( dataDir, 'wills', id, 'replays' )
+    mkdirSync( dir, { recursive: true } )
+
+    const path = join( dir, `${active.runId}.json` )
+    await active.recorder.save( path )
+
+    const meta = active.recorder.getMetadata()
+    const key  = `${id}:${active.runId}`
+    this._completedReplays.set( key, meta )
+    this._replayPaths.set( key, path )
+
+    return meta
+  }
+
+  getMeta( id: string, runId: string ): ReplayMetadata | null {
+    const active = this._activeRecorders.get( id )
+    if( active?.runId === runId ) return active.recorder.getMetadata()
+
+    const key    = `${id}:${runId}`
+    const cached = this._completedReplays.get( key )
+    if( cached ) return cached
+
+    const dataDir = process.env[ 'WILL_DATA_DIR' ] ?? './data'
+    const path    = join( dataDir, 'wills', id, 'replays', `${runId}.json` )
+    if( !existsSync( path ) ) return null
+
+    try {
+      const meta = ( JSON.parse( readFileSync( path, 'utf8' ) ) as { metadata: ReplayMetadata } ).metadata
+      this._completedReplays.set( key, meta )
+      this._replayPaths.set( key, path )
+      return meta
+    } catch {
+      return null
+    }
+  }
+
+  list( id: string ): ReplayMetadata[] {
+    const results: ReplayMetadata[] = []
+    const prefix  = `${id}:`
+
+    const active = this._activeRecorders.get( id )
+    if( active ) results.push( active.recorder.getMetadata() )
+
+    for( const [ key, meta ] of this._completedReplays )
+      if( key.startsWith( prefix ) ) results.push( meta )
+
+    const dataDir = process.env[ 'WILL_DATA_DIR' ] ?? './data'
+    const dir     = join( dataDir, 'wills', id, 'replays' )
+
+    if( existsSync( dir ) ){
+      const inMem = new Set(
+        [ ...this._completedReplays.keys() ]
+          .filter( k => k.startsWith( prefix ) )
+          .map( k => k.slice( prefix.length ) )
+      )
+      if( active ) inMem.add( active.runId )
+
+      for( const file of readdirSync( dir ) ){
+        if( !file.endsWith('.json') ) continue
+        const runId = file.slice( 0, -5 )
+        if( inMem.has( runId ) ) continue
+        try {
+          const path   = join( dir, file )
+          const meta   = ( JSON.parse( readFileSync( path, 'utf8' ) ) as { metadata: ReplayMetadata } ).metadata
+          const key    = `${id}:${runId}`
+          this._completedReplays.set( key, meta )
+          this._replayPaths.set( key, path )
+          results.push( meta )
+        } catch { /* skip malformed */ }
+      }
+    }
+
+    return results.sort( ( a, b ) => b.startTime - a.startTime )
+  }
+
+  async compare( id: string, runId1: string, runId2: string ): Promise<ReplayComparison> {
+    const path1 = this._resolvePath( id, runId1 )
+    const path2 = this._resolvePath( id, runId2 )
+    if( !path1 ) throw Object.assign( new Error(`Replay not found: ${runId1}`), { code: 404 } )
+    if( !path2 ) throw Object.assign( new Error(`Replay not found: ${runId2}`), { code: 404 } )
+    return this._replayManager.compare( path1, path2 )
+  }
+
+  /**
+   * Resolve a replay file path: prefer the in-memory cache, else fall back to the
+   * conventional on-disk location. Without the fallback, compare() would 404 for
+   * replays that exist on disk but weren't loaded via list()/getMeta() this
+   * process (e.g. after a server restart).
+   */
+  private _resolvePath( id: string, runId: string ): string | undefined {
+    const cached = this._replayPaths.get( `${id}:${runId}` )
+    if( cached ) return cached
+
+    const dataDir = process.env[ 'WILL_DATA_DIR' ] ?? './data'
+    const path    = join( dataDir, 'wills', id, 'replays', `${runId}.json` )
+    if( !existsSync( path ) ) return undefined
+
+    this._replayPaths.set( `${id}:${runId}`, path )
+    return path
+  }
+}