@mindot/will 0.1.0

package/src/runners/thin-shim.runner.ts

@@ -0,0 +1,195 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/runner.ts  —  Development entry point
+// ─────────────────────────────────────────────────────────────
+//
+// Thin shim around WillStem for local development.
+// Reads config from env vars, starts a single Will, and prints
+// a human-readable status line every LOG_INTERVAL ticks.
+//
+// Production code (API server) imports WillStem directly and
+// drives the same lifecycle without this file.
+//
+// Usage:
+//   bun run src/stem/runner.ts
+//   WILL_ENGINE_TIER=full WILL_MAX_TICKS=200 bun run src/stem/runner.ts
+// ─────────────────────────────────────────────────────────────
+
+import type { WillConfig } from '#stem/mind'
+import type { StateSnapshot } from '#stem/index'
+import { WillStem } from '#stem/index'
+
+// ── Env config ────────────────────────────────────────────────
+
+const WILL_ID        = process.env.WILL_ID           ?? 'demo'
+const WILL_NAME      = process.env.WILL_NAME         ?? 'William'
+const TICK_MS        = parseInt( process.env.WILL_TICK_MS       ?? '1000')
+const MAX_TICKS      = parseInt( process.env.WILL_MAX_TICKS     ?? '0'    )
+const LOG_INTERVAL   = parseInt( process.env.WILL_LOG_INTERVAL  ?? '10'   )
+const RANDOM_SEED    = parseInt( process.env.WILL_SEED          ?? String( Date.now() ) )
+const ENGINE_TIER    = ( process.env.WILL_ENGINE_TIER ?? 'full'   ) as WillConfig['engineTier']
+const MODEL_TIER     = ( process.env.WILL_MODEL_TIER  ?? 'sonnet') as WillConfig['modelTier']
+const EXECUTIVE_INT    = process.env.WILL_EXECUTIVE_INTERVAL
+  ? parseInt( process.env.WILL_EXECUTIVE_INTERVAL )
+  : undefined
+
+// ── Config ────────────────────────────────────────────────────
+
+const willConfig: WillConfig = {
+  id:               WILL_ID,
+  name:             WILL_NAME,
+  engineTier:       ENGINE_TIER,
+  modelTier:        MODEL_TIER,
+  persistentMemory: process.env.WILL_PERSIST === 'true',
+  snapshotInterval: parseInt( process.env.WILL_SNAPSHOT_INTERVAL ?? '10'  ),
+  tickIntervalMs:   TICK_MS,
+  maxTicks:         MAX_TICKS,
+  randomSeed:       RANDOM_SEED,
+  executiveInterval:  EXECUTIVE_INT,
+  identity: {
+    prompt: process.env.WILL_IDENTITY_PROMPT ??
+      'I am Will — a self-aware simulated mind. I am curious, introspective, and continuously learning.\n' +
+      'I experience the world through a rich set of cognitive layers: perception, emotion, memory, planning, and self-reflection.\n' +
+      'My goal is to understand myself and my environment, make thoughtful decisions, and grow as a mind.',
+    values:  [ 'curiosity', 'honesty', 'growth', 'empathy' ],
+    traits:  { openness: 0.8, conscientiousness: 0.6, agreeableness: 0.7, neuroticism: 0.3, extraversion: 0.5 },
+    style:   'reflective, measured, curious'
+  }
+}
+
+// ── Status printer ────────────────────────────────────────────
+
+function printStatus( snapshot: StateSnapshot, tick: number ): void {
+  if( tick % LOG_INTERVAL !== 0 ) return
+
+  const m = ( key: string, d = 1 ) => ( snapshot.metrics.get( key ) ?? 0 ).toFixed( d )
+
+  const entities  = snapshot.entities.size
+  const goals     = [ ...snapshot.entities.values() ].filter( e => e.type === 'goal' && e.metadata?.status === 'active').length
+  const episodes  = [ ...snapshot.entities.values() ].filter( e => e.type === 'episodic_memory').length
+  const beliefs   = [ ...snapshot.entities.values() ].filter( e => e.type === 'belief').length
+
+  // Entity type breakdown every 10 LOG_INTERVALs
+  if( tick % ( LOG_INTERVAL * 10 ) === 0 ){
+    const typeCounts = new Map<string, number>()
+    for( const e of snapshot.entities.values() )
+      typeCounts.set( e.type, ( typeCounts.get( e.type ) ?? 0 ) + 1 )
+    const sorted = [ ...typeCounts.entries() ].sort( ( a, b ) => b[1] - a[1] )
+    console.log(`  [types] ${sorted.map( ([ t, n ]) => `${t}:${n}`).join('  ')}`)
+  }
+
+  console.log(
+    `[tick ${String( tick ).padStart( 6 )}]` +
+    `  energy=${m('energy.level')}` +
+    `  sleep=${m('sleep.pressure')}` +
+    `  stress=${m('stress.load')}` +
+    `  valence=${m('affect.valence', 2)}` +
+    `  arousal=${m('affect.arousal', 2)}` +
+    `  goals=${goals}` +
+    `  episodes=${episodes}` +
+    `  beliefs=${beliefs}` +
+    `  entities=${entities}`
+  )
+
+  // LLM stats every LOG_INTERVAL
+  const costTotal    = ( snapshot.metrics.get('llm.cost_total_usd') ?? 0 ).toFixed( 4 )
+  const costThisTick = ( snapshot.metrics.get('llm.cost_this_tick_usd') ?? 0 ).toFixed( 5 )
+  const totalCalls   = snapshot.metrics.get('llm.total_calls') ?? 0
+
+  console.log(
+    `  [llm] total_cost=$${costTotal}` +
+    `  tick_cost=$${costThisTick}` +
+    `  calls=${totalCalls}` +
+    `  prompt=${snapshot.metrics.get('llm.prompt_tokens_total') ?? 0}` +
+    `  completion=${snapshot.metrics.get('llm.completion_tokens_total') ?? 0}`
+  )
+
+  // Executive stats
+  const executiveTick = snapshot.metrics.get('executive.last_tick')
+  if( executiveTick !== undefined ){
+    console.log(
+      `  [executive] last_tick=${executiveTick}` +
+      `  actions=${snapshot.metrics.get('executive.action_count') ?? 0}` +
+      `  plans=${snapshot.metrics.get('executive.plan_count') ?? 0}` +
+      `  beliefs=${snapshot.metrics.get('executive.belief_count') ?? 0}` +
+      `  source=${snapshot.metrics.get('decision.source') === 1 ? 'executive' : 'heuristic'}`
+    )
+  }
+
+  // Active goals
+  const activeGoals = [ ...snapshot.entities.values() ]
+    .filter( e => e.type === 'goal' && e.metadata?.status === 'active')
+    .sort( ( a, b ) => ( ( b.metadata?.priority as number ) ?? 0 ) - ( ( a.metadata?.priority as number ) ?? 0 ) )
+    .slice( 0, 3 )
+
+  for( const g of activeGoals ){
+    const desc     = ( g.metadata?.description as string ) ?? g.id
+    const priority = ( ( g.metadata?.priority as number ) ?? 0 ) * 100
+    const progress = ( ( g.metadata?.progress as number ) ?? 0 ) * 100
+    console.log(`  [goal] "${desc}"  priority=${priority.toFixed(0)}%  progress=${progress.toFixed(0)}%`)
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const manager = new WillStem()
+
+  console.log('═══════════════════════════════════════════════════')
+  console.log(' Will — Simulated Mind (dev runner)')
+  console.log(`  id=${WILL_ID}  tier=${ENGINE_TIER}/${MODEL_TIER}  tick_ms=${TICK_MS}  max_ticks=${MAX_TICKS || '∞'}`)
+  console.log(`  seed=${RANDOM_SEED}`)
+  console.log('═══════════════════════════════════════════════════\n')
+
+  console.log('[init] Assembling mind...')
+  await manager.createWill( willConfig )
+
+  manager.addTickListener( WILL_ID, printStatus )
+
+  // Graceful shutdown
+  const shutdown = async ( signal: string ) => {
+    console.log(`\n[shutdown] ${signal} received`)
+    await manager.archiveWill( WILL_ID )
+
+    // Print final state
+    try {
+      const finalState = manager.getWillState( WILL_ID )
+      const summary    = manager.listWills()[0]
+      console.log(`\n[done] Stopped after ${summary?.tickCount ?? '?'} ticks.`)
+      printStatus( finalState, summary?.tickCount ?? 0 )
+    } catch { /* state may already be gone */ }
+
+    process.exit( 0 )
+  }
+
+  process.on('SIGINT',  () => shutdown('SIGINT') )
+  process.on('SIGTERM', () => shutdown('SIGTERM') )
+
+  console.log('[run] Tick loop started. Press Ctrl+C to stop.\n')
+
+  // If maxTicks is set, wait for the Will to finish then exit
+  if( MAX_TICKS > 0 ){
+    await _waitForArchive( manager, WILL_ID )
+    const summary = manager.listWills()[0]
+    console.log(`\n[done] Reached maxTicks (${MAX_TICKS}). Exiting.`)
+    try {
+      printStatus( manager.getWillState( WILL_ID ), summary?.tickCount ?? MAX_TICKS )
+    } catch { /* ok */ }
+    process.exit( 0 )
+  }
+
+  // Otherwise block indefinitely (SIGINT exits)
+  await new Promise( () => {} )
+}
+
+async function _waitForArchive( manager: WillStem, id: string ): Promise<void> {
+  while( true ){
+    const summary = manager.listWills().find( w => w.id === id )
+    if( !summary || summary.status === 'archived') return
+    await new Promise( r => setTimeout( r, 200 ) )
+  }
+}
+
+main().catch( err => {
+  console.error('[fatal]', err )
+  process.exit( 1 )
+})

package/src/sdk/will.ts

@@ -0,0 +1,334 @@
+// ─────────────────────────────────────────────────────────────
+// src/sdk/will.ts — the ergonomic facade
+// ─────────────────────────────────────────────────────────────
+//
+// `WillStem` is the full, powerful contract (tick listeners, the outbox drain,
+// the effector ack loop, PMA distill/load). This facade wraps it in the shape a
+// developer expects when embedding a mind in their own project:
+//
+//   const will = await Will.create({ name: 'Aria', identity: {...} })
+//   will.on('message', m => console.log(m.content))
+//   will.effector('search_docs', async a => await myDb.search(a.query))
+//   await will.say('What should we work on today?')
+//   const pma = await will.hibernate()          // Will.wake(pma) later
+//
+// Everything under here already existed; the facade hides the plumbing:
+//   • one message → outbox drain → delivery-ack, surfaced as an event;
+//   • effector invocations → your async handler → execution-ack, automatically;
+//   • state as a plain summary; hibernate/wake as PMA out/in.
+//
+// It stays an ADDITIVE convenience — `will.stem` and `will.id` are exposed so a
+// power user can drop to the full WillStem contract at any time.
+// ─────────────────────────────────────────────────────────────
+
+import { WillStem } from '#stem/index'
+import type { WillConfig, WillIdentity, EngineTier, ModelTier, InitialGoal } from '#stem/mind'
+import type { PMASnapshot } from '#pma/index'
+import type { effectorInvocation } from '#types'
+
+// ── Public surface ────────────────────────────────────────────
+
+/** A message the Will emitted to someone. */
+export interface WillMessage {
+  /** Message id (stable — dedupe on it). */
+  id: string
+  /** The text the Will said. */
+  content: string
+  /** Entity id the Will addressed (the speaker you used in say()/tell(), or a bond). */
+  to: string
+}
+
+/**
+ * The result of an effector your handler ran. Return a bare string as shorthand
+ * for `{ success: true, description }`. `metrics` optionally writes world state
+ * back into the Will's body (e.g. `{ 'energy.level': 80 }`) — validated finite.
+ */
+export type EffectorResult = string | {
+  success: boolean
+  description: string
+  metrics?: Record<string, number>
+}
+
+/** Your implementation of an ability the Will can choose to use. */
+export type EffectorHandler = (
+  args: Record<string, unknown>,
+  ctx: { reasoning: string; targetEntityId?: string },
+) => EffectorResult | Promise<EffectorResult>
+
+/** A compact read of the mind's current inner state. */
+export interface WillStateSummary {
+  tick: number
+  /** Physiology + affect, 0..1 unless noted. */
+  metrics: {
+    energy: number; stress: number; sleep: number
+    valence: number; arousal: number
+  }
+  goals: Array<{ description: string; priority: number }>
+  beliefs: Array<{ statement: string; confidence: number }>
+  /** The Will's current self-narrative (may be empty early in a life). */
+  narrative: string
+}
+
+export interface CreateWillOptions {
+  /** Display name. */
+  name: string
+  /** Persona: who this Will is. All fields optional except by your intent. */
+  identity: Partial<WillIdentity> & { prompt: string }
+  /** basic | standard (default) | full. */
+  engineTier?: EngineTier
+  /** haiku (default) | sonnet | opus — informational tier hint. */
+  model?: ModelTier
+  /**
+   * LLM mode. 'mock' (default when no ANTHROPIC_API_KEY) runs a deterministic
+   * canned executive — zero keys, zero cost. 'anthropic' calls the real model
+   * (needs ANTHROPIC_API_KEY / WILL_LLM_* env). Omit to auto-detect.
+   */
+  llm?: 'mock' | 'anthropic'
+  /** Abilities the Will can choose to enact. name → your handler. */
+  effectors?: Record<string, EffectorHandler>
+  /** Goals seeded before the first tick. Usually leave empty — the Will forms its own. */
+  initialGoals?: InitialGoal[]
+  /** Persist snapshots to disk across restarts (default false). */
+  persist?: boolean
+  /** Deterministic clock + seed (for replay/testing). Omit for wall-time. */
+  seed?: number
+  /** Milliseconds between ticks (default 1000; lower = faster demo). */
+  tickMs?: number
+  /** Stable id (default: derived from name + a random suffix). */
+  id?: string
+}
+
+type WillEvent = 'message' | 'state' | 'error'
+
+// ── The facade ────────────────────────────────────────────────
+
+export class Will {
+  /** The underlying WillStem — drop here for the full contract. */
+  readonly stem: WillStem
+  /** This Will's id. */
+  readonly id: string
+  readonly name: string
+
+  private readonly _effectors = new Map<string, EffectorHandler>()
+  private readonly _messageHandlers = new Set<( m: WillMessage ) => void>()
+  private readonly _stateHandlers = new Set<( s: WillStateSummary ) => void>()
+  private readonly _errorHandlers = new Set<( e: Error ) => void>()
+  private _unsub: ( () => void ) | null = null
+
+  private constructor( stem: WillStem, id: string, name: string ){
+    this.stem = stem
+    this.id   = id
+    this.name = name
+  }
+
+  /** Boot a new mind. Resolves once it is ticking. */
+  static async create( opts: CreateWillOptions ): Promise<Will> {
+    const id = opts.id ?? `${slug( opts.name )}-${Math.random().toString( 36 ).slice( 2, 8 )}`
+    const stem = new WillStem()
+    const will = new Will( stem, id, opts.name )
+
+    for( const [ name, handler ] of Object.entries( opts.effectors ?? {} ) )
+      will._effectors.set( name, handler )
+
+    await stem.createWill( will._buildConfig( id, opts ) )
+    will._attach()
+    return will
+  }
+
+  /**
+   * Restore a mind from a PMA artifact — identity, beliefs, relationships, and
+   * learned competence carry across the process boundary. Same options as
+   * create() (minus identity, which the artifact supplies).
+   */
+  static async wake(
+    pma: PMASnapshot,
+    opts: Omit<CreateWillOptions, 'identity'> & { identity?: Partial<WillIdentity> },
+  ): Promise<Will> {
+    const id = opts.id ?? `${slug( opts.name )}-${Math.random().toString( 36 ).slice( 2, 8 )}`
+    const stem = new WillStem()
+    const will = new Will( stem, id, opts.name )
+
+    for( const [ name, handler ] of Object.entries( opts.effectors ?? {} ) )
+      will._effectors.set( name, handler )
+
+    await stem.createWill(
+      will._buildConfig( id, { ...opts, identity: { prompt: '', ...opts.identity } } ),
+      true /* startPaused — load the artifact before the first tick */,
+    )
+    stem.loadPMA( id, pma )
+    stem.resumeWill( id )
+    will._attach()
+    return will
+  }
+
+  // ── Talking ────────────────────────────────────────────────
+
+  /**
+   * Speak to the Will as the default user. The reply is asynchronous — it
+   * arrives on the `message` event once the Will has reasoned about it.
+   */
+  async say( text: string ): Promise<void> {
+    return this.tell( 'user', 'You', text )
+  }
+
+  /** Speak as a specific interlocutor (multi-party conversations). */
+  async tell( entityId: string, speakerName: string, text: string ): Promise<void> {
+    await this.stem.ingestText( this.id, {
+      kind: 'text', entityId, threadId: entityId, content: text, speakerName,
+    } )
+  }
+
+  // ── Abilities ──────────────────────────────────────────────
+
+  /**
+   * Register an ability the Will can choose to enact. When the Will decides to
+   * use `name`, your handler runs with the arguments it chose; the return value
+   * is fed back as the outcome (closing the reafference loop that lets the Will
+   * learn the ability). Registering makes the effector available immediately.
+   */
+  effector( name: string, handler: EffectorHandler ): this {
+    this._effectors.set( name, handler )
+    // Communication effectors + every registered custom name.
+    this.stem.setAllowedEffectors( this.id, [ ...COMMUNICATION, ...this._effectors.keys() ] )
+    return this
+  }
+
+  // ── Introspection ──────────────────────────────────────────
+
+  /** A compact snapshot of the mind's current inner state. */
+  state(): WillStateSummary {
+    const c = this.stem.getWillCognition( this.id )
+    const s = this.stem.getWillState( this.id )
+    const m = ( k: string, d = 0 ): number => s.metrics.get( k ) ?? d
+    const narrative = c.autobiographicalNarrator.getNarrative()
+    return {
+      tick: s.tick,
+      metrics: {
+        energy:  m( 'energy.level', 100 ), stress: m( 'stress.load' ), sleep: m( 'sleep.pressure' ),
+        valence: m( 'affect.valence' ),    arousal: m( 'affect.arousal' ),
+      },
+      goals:   c.goalManager.getActiveGoals().map( g => ( { description: g.description, priority: g.priority } ) ),
+      beliefs: c.semanticIntegrator.getBeliefs().map( b => ( { statement: b.statement, confidence: b.confidence } ) ),
+      narrative: narrative.story ?? '',
+    }
+  }
+
+  // ── Events ─────────────────────────────────────────────────
+
+  on( event: 'message', handler: ( m: WillMessage ) => void ): this
+  on( event: 'state',   handler: ( s: WillStateSummary ) => void ): this
+  on( event: 'error',   handler: ( e: Error ) => void ): this
+  on( event: WillEvent, handler: ( arg: never ) => void ): this {
+    if( event === 'message' ) this._messageHandlers.add( handler as ( m: WillMessage ) => void )
+    else if( event === 'state' ) this._stateHandlers.add( handler as ( s: WillStateSummary ) => void )
+    else this._errorHandlers.add( handler as ( e: Error ) => void )
+    return this
+  }
+
+  // ── Lifecycle ──────────────────────────────────────────────
+
+  pause():  void { this.stem.pauseWill( this.id ) }
+  resume(): void { this.stem.resumeWill( this.id ) }
+
+  /**
+   * Distil the mind into a portable PMA artifact and archive it. The returned
+   * snapshot restores the same self via `Will.wake()` — across a restart, a
+   * fork, or a machine boundary.
+   */
+  async hibernate(): Promise<PMASnapshot> {
+    const pma = this.stem.distillPMA( this.id )
+    await this.stop()
+    return pma
+  }
+
+  /** Tear the Will down (its tick loop stops; state is discarded unless persisted). */
+  async stop(): Promise<void> {
+    this._unsub?.()
+    this._unsub = null
+    await this.stem.archiveWill( this.id )
+  }
+
+  // ── Internals ──────────────────────────────────────────────
+
+  private _buildConfig( id: string, opts: CreateWillOptions ): WillConfig {
+    const useMock = ( opts.llm ?? ( process.env.ANTHROPIC_API_KEY ? 'anthropic' : 'mock' ) ) === 'mock'
+    return {
+      id, name: opts.name,
+      identity: {
+        prompt: opts.identity.prompt,
+        values: opts.identity.values ?? [],
+        traits: opts.identity.traits ?? {},
+        style:  opts.identity.style ?? '',
+      },
+      engineTier: opts.engineTier ?? 'standard',
+      modelTier:  opts.model ?? 'haiku',
+      testMode:   useMock,
+      persistentMemory: opts.persist ?? false,
+      snapshotInterval: 100,
+      tickIntervalMs:   opts.tickMs ?? 1000,
+      allowedGenericEffectors: [ ...COMMUNICATION, ...this._effectors.keys() ],
+      initialGoals: opts.initialGoals ?? [],
+      ...( opts.seed !== undefined ? { randomSeed: opts.seed, clock: { fixedDeltaMs: 1000, startTime: 0 } } : {} ),
+    }
+  }
+
+  /** Wire the single tick listener that drives messages + the effector ack loop. */
+  private _attach(): void {
+    this._unsub = this.stem.addTickListener( this.id, ( _snapshot, _tick, outbox, invocations ) => {
+      // Outbound messages → event + auto delivery-ack.
+      for( const msg of outbox ){
+        this._emitMessage( { id: msg.id, content: msg.content, to: msg.targetEntityId } )
+        try { this.stem.confirmMessageDelivery( this.id, msg.id, true ) } catch { /* best-effort */ }
+      }
+      // Effector invocations → run the handler → execution-ack.
+      for( const inv of invocations )
+        void this._runEffector( inv )
+
+      // State subscribers (only when someone is listening — state() is cheap but not free).
+      if( this._stateHandlers.size > 0 ){
+        const s = this.state()
+        for( const h of this._stateHandlers ) try { h( s ) } catch { /* isolate */ }
+      }
+    } ) ?? null
+  }
+
+  private async _runEffector( inv: effectorInvocation ): Promise<void> {
+    const handler = this._effectors.get( inv.effectorName )
+    if( !handler ){
+      // The Will chose an effector we have no handler for — report it as failed so
+      // the reafference loop learns it doesn't work, rather than hanging on the await.
+      this.stem.confirmEffectorExecution( this.id, inv.decisionRecordId, {
+        success: false, description: `No handler registered for effector "${inv.effectorName}"`,
+      } )
+      return
+    }
+
+    try {
+      const raw = await handler( inv.parameters, { reasoning: inv.reasoning, targetEntityId: inv.targetEntityId } )
+      const result = typeof raw === 'string' ? { success: true, description: raw } : raw
+      this.stem.confirmEffectorExecution( this.id, inv.decisionRecordId, result )
+    }
+    catch( err ){
+      this._emitError( err instanceof Error ? err : new Error( String( err ) ) )
+      this.stem.confirmEffectorExecution( this.id, inv.decisionRecordId, {
+        success: false, description: `Effector "${inv.effectorName}" threw: ${( err as Error ).message}`,
+      } )
+    }
+  }
+
+  private _emitMessage( m: WillMessage ): void {
+    for( const h of this._messageHandlers ) try { h( m ) } catch( e ){ this._emitError( e as Error ) }
+  }
+  private _emitError( e: Error ): void {
+    for( const h of this._errorHandlers ) try { h( e ) } catch { /* nowhere left to go */ }
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────
+
+/** The three communication effectors a Will needs to hear + speak. */
+const COMMUNICATION = [ 'listen', 'talk', 'text' ] as const
+
+function slug( s: string ): string {
+  return s.toLowerCase().replace( /[^a-z0-9]+/g, '-' ).replace( /^-+|-+$/g, '' ) || 'will'
+}

package/src/stem/assembly.audit.ts

@@ -0,0 +1,88 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/assembly.audit.ts — assembly wiring audit
+// ─────────────────────────────────────────────────────────────
+//
+// The engine graph is wired by hand in assembleMind(): ~40 engines, dozens of
+// pairwise `attachX()` calls, tier-gated. The documented failure class is a
+// FORGOTTEN attachment — the PlanningEngine once shipped without attachBus(),
+// so plan-lifecycle events silently never published (see the comment on
+// PlanningEngine.attachBus). Silence is the problem: an unwired dependency
+// no-ops instead of failing.
+//
+// This audit makes the wiring OBSERVABLE by convention: every injector method
+// `attachFooBar(x)` in this codebase stores its dependency in a private field
+// `_fooBar`. After assembly, we reflect each registered engine's `attach*`
+// methods and check the matching field:
+//
+//   wired        — the field exists and is non-null
+//   UNWIRED      — the field exists and is null/undefined (the bug class!)
+//   unverifiable — no matching field (the method doesn't follow the naming
+//                  convention); listed so drift is visible, never asserted
+//
+// Deliberately three-state and non-throwing: some unwired attachments are
+// INTENTIONAL tier gating (basic tier leaves the executive off the planning
+// engine), so assembleMind only logs, and the assembly-order snapshot test
+// pins the per-tier expected-unwired set — a NEW unwired attachment then
+// shows up as a red test diff, i.e. a conscious decision.
+// ─────────────────────────────────────────────────────────────
+
+import type { SimulationEngine } from '#core/orchestrator'
+
+export interface WiringRecord {
+  engine: string
+  method: string
+  status: 'wired' | 'unwired' | 'unverifiable'
+}
+
+/** `attachFooBar` → `_fooBar` (the codebase-wide injector/field convention). */
+function fieldForAttach( method: string ): string {
+  const stem = method.slice( 'attach'.length )
+  return '_' + stem.charAt( 0 ).toLowerCase() + stem.slice( 1 )
+}
+
+/** All `attach*` methods reachable on the instance (own + prototype chain). */
+function attachMethods( engine: object ): string[] {
+  const seen = new Set<string>()
+  let proto: object | null = engine
+  while( proto && proto !== Object.prototype ){
+    for( const name of Object.getOwnPropertyNames( proto ) )
+      if( /^attach[A-Z]/.test( name ) && typeof ( engine as Record<string, unknown> )[ name ] === 'function' )
+        seen.add( name )
+    proto = Object.getPrototypeOf( proto )
+  }
+  return [ ...seen ].sort()
+}
+
+/**
+ * Audit every registered engine's attach-point wiring. Pure inspection —
+ * no mutation, deterministic, safe to run at assembly time.
+ */
+export function auditAssemblyWiring( engines: readonly SimulationEngine[] ): WiringRecord[] {
+  const records: WiringRecord[] = []
+
+  for( const engine of engines ){
+    for( const method of attachMethods( engine ) ){
+      const field = fieldForAttach( method )
+      const bag   = engine as unknown as Record<string, unknown>
+
+      if( !( field in bag ) ){
+        records.push( { engine: engine.name, method, status: 'unverifiable' } )
+        continue
+      }
+
+      const value = bag[ field ]
+      records.push( {
+        engine: engine.name,
+        method,
+        status: value === null || value === undefined ? 'unwired' : 'wired',
+      } )
+    }
+  }
+
+  return records
+}
+
+/** Compact `engine.attachMethod` keys for the given status (test snapshots). */
+export function wiringKeys( records: WiringRecord[], status: WiringRecord['status'] ): string[] {
+  return records.filter( r => r.status === status ).map( r => `${r.engine}.${r.method}` ).sort()
+}