@mindot/will 0.1.0

package/src/cognition/agency/engines/affordance.synthesizer.ts

@@ -0,0 +1,384 @@
+// ─────────────────────────────────────────────────────────────
+// src/agency/affordance.synthesizer.ts  —  head of the agency pipeline
+// ─────────────────────────────────────────────────────────────
+//
+// The AffordanceSynthesizer is the Gibsonian move: instead of a static catalog
+// the executive selects from, perception *emits* the field of what is possible
+// right now, for this body, in this state. It runs every tick with no LLM.
+//
+// Each tick it draws on:
+//   • the innate floor    — reflexive, objectless possibilities (always present)
+//   • salient percepts    — "inspect this", bound to what perception surfaced
+//   • known sentient minds — "reach out to them", bound to the relationship
+//   • (Phase 3) the repertoire of learned composite skills
+//
+// Two properties make it mind-shaped, not framework-shaped:
+//   1. Parameters are bound *at perception time* from the evoking thing, so an
+//      affordance can never arrive at execution with empty arguments.
+//   2. Attention gates the WIDTH of the field — a depleted or unfocused mind
+//      literally has fewer possibilities available to it. The body shapes the
+//      option set, not just the choice.
+//
+// Output: transient `affordance` entities (the field is rebuilt every tick),
+// plus metrics and an `affordance.field.synthesized` bus event for the selector
+// and telemetry. See AGENCY_PIPELINE_TODO.md.
+// ─────────────────────────────────────────────────────────────
+
+import { logger } from '#core/logger'
+import type {
+  Duration, Tick, SimulationContext,
+  ReadonlySimulationState, StateCommands, EntityInput,
+} from '#core/types'
+import type { CognitiveBus } from '#cognition/bus'
+import type { CognitiveEngine, EngineResult } from '#cognition/types'
+import type { CognitiveEventSchema } from '#cognition/schema.registry'
+import type { Affordance, AffordanceSource, MotorSchema, LearnedSkill, SchemaPrecondition } from '#agency/types'
+import type { SchemaRepertoire } from '#agency/schemas/repertoire'
+import { INNATE_SCHEMAS } from '#agency/schemas/innate'
+import { collectGoalTargets } from '#agency/selection.scoring'
+
+/** Default field width for non-innate affordances when no attention metric exists. */
+const DEFAULT_ATTENTION_CAP = 5
+/** Hard ceiling so a flood of percepts can never explode the field. */
+const MAX_ATTENTION_CAP = 12
+/** Pre-activation floor for an ideomotor candidate — the executive deliberately willed
+ *  it, so it should reliably reach the field, but it still competes in the selector. */
+const IDEOMOTOR_BASE_SALIENCE = 0.5
+
+type SkillAccessor = () => ReadonlyMap<string, LearnedSkill>
+
+interface Candidate {
+  /** Coarse evoke-salience used only for attention budgeting (selection scores later). */
+  salience:   number
+  affordance: Affordance
+}
+
+export class AffordanceSynthesizer implements CognitiveEngine {
+  readonly name = 'affordance-synthesizer'
+
+  private _schemas:     MotorSchema[]
+  private _skills:      SkillAccessor | null = null
+  private _repertoire:  SchemaRepertoire | null = null
+  private _bus:         CognitiveBus | null = null
+  private _defaultCap:  number
+  private _lastFieldSize = 0
+
+  constructor( schemas: MotorSchema[] = INNATE_SCHEMAS, defaultCap = DEFAULT_ATTENTION_CAP ){
+    this._schemas    = schemas
+    this._defaultCap = defaultCap
+  }
+
+  // ── wiring ────────────────────────────────────────────────────
+  attachBus( bus: CognitiveBus ): void { this._bus = bus }
+  /** Inject the repertoire's learned-skill accessor (Phase 3). */
+  attachSkills( accessor: SkillAccessor ): void { this._skills = accessor }
+  /**
+   * Attach the live repertoire — its templates (innate floor + learned composites)
+   * become the schema set, and its skills feed the affordance priors. This is how
+   * a newly-learned composite shows up in the field without a restart.
+   */
+  attachRepertoire( repertoire: SchemaRepertoire ): void { this._repertoire = repertoire }
+  /** Register an additional schema template (e.g. a learned composite). */
+  registerSchema( schema: MotorSchema ): void { this._schemas.push( schema ) }
+
+  // ── CognitiveEngine interface ─────────────────────────────────
+  publishes(): CognitiveEventSchema[] {
+    return [ { type: 'affordance.field.synthesized', version: 1, validate: () => null } ]
+  }
+  subscribes(): string[] { return [] }
+  onCognitiveEvent(): void { /* pull model — reads frozen state each tick */ }
+  snapshot(): Record<string, unknown> { return { lastFieldSize: this._lastFieldSize } }
+
+  // ── react ─────────────────────────────────────────────────────
+  async react(
+    _delta:   Duration,
+    tick:     Tick,
+    state:    ReadonlySimulationState,
+    _context: SimulationContext,
+  ): Promise<EngineResult> {
+    // Rehydrate learned composites the executor needs to resolve. After a
+    // snapshot/restore the repertoire is rebuilt innate-only; the composite
+    // *definitions* come back as `agency.schema` entities (written by the
+    // ReafferenceEngine). Doing this here — the first agency engine each tick —
+    // means the executor, which ticks later in the SAME tick, sees a whole
+    // repertoire and can expand a restored mid-flight macro. Idempotent.
+    this._repertoire?.restoreComposites( state.entities )
+
+    const schemas   = this._repertoire?.schemas() ?? this._schemas
+    const skills    = this._skills?.() ?? this._repertoire?.skills() ?? null
+    const valence   = metric( state, 'affect.valence', 0 )
+    const energyLow = metric( state, 'energy.level', 0 ) < 30
+
+    const set:    EntityInput[] = []
+    const del:    string[]      = []
+
+    // Clear the previous tick's field — affordances are transient.
+    for( const [ id, e ] of state.entities )
+      if( e.type === 'affordance' ) del.push( id )
+
+    // ── 1. innate floor — always emitted, never attention-capped ──
+    const floor = schemas.filter( s => s.binds === 'none' )
+    for( const schema of floor )
+      set.push( this._toEntity(
+        this._build( schema, tick, state, valence, energyLow, skills, {} ),
+      ) )
+
+    // ── 2. perception-bound candidates, attention-budgeted ───────
+    // Goal-relevance counts at the CAP, not only at selection: an affordance whose
+    // target an active goal is directed at is lifted here so goal-driven outreach
+    // isn't out-competed by ambient rumination before the selector (which also
+    // scores goalRelevance) ever sees it. Same `goalTargets` notion as the selector.
+    const candidates:  Candidate[]           = []
+    const goalTargets: Map<string, number>   = collectGoalTargets( state )
+
+    const perceptSchema = schemas.find( s => s.binds === 'percept' )
+    if( perceptSchema )
+      for( const [ id, e ] of state.entities ){
+        if( e.type !== 'percept' ) continue
+        const m        = e.metadata
+        const salience = num( m?.['salience'], 0 )
+        const summary  = str( m?.['summary'] ) ?? str( m?.['category'] ) ?? 'something'
+        const target   = str( m?.['entityId'] ) ?? str( m?.['targetEntityId'] )
+        candidates.push({
+          salience: salience + ( target ? goalTargets.get( target ) ?? 0 : 0 ),
+          affordance: this._build( perceptSchema, tick, state, valence, energyLow, skills, {
+            evokedBy:       id,
+            targetEntityId: target,
+            parameters:     { focus: summary },
+          } ),
+        })
+      }
+
+    const entitySchema = schemas.find( s => s.binds === 'entity' )
+    if( entitySchema )
+      for( const [ id, e ] of state.entities ){
+        if( e.type !== 'known-entity' ) continue
+        const m = e.metadata
+        if( str( m?.['kind'] ) !== 'sentient' ) continue
+        const keid = str( m?.['keid'] ) ?? id
+        const fam  = num( m?.['familiarity'], 0 )
+        const val  = num( m?.['valence'], 0 )
+        const res  = num( m?.['resolutionConfidence'], 0 )
+        candidates.push({
+          salience: fam * 0.6 + Math.max( 0, val ) * 0.3 + res * 0.1 + ( goalTargets.get( keid ) ?? 0 ),
+          affordance: this._build( entitySchema, tick, state, valence, energyLow, skills, {
+            evokedBy:       id,
+            targetEntityId: keid,
+            parameters:     { targetEntityName: str( m?.['name'] ) ?? keid },
+          } ),
+        })
+      }
+
+    // ── ideomotor candidates: the executive's imagined actions, pre-activated ──
+    // The executive writes `ideomotor.intent` entities for the actions it imagines
+    // (its "what if I…"). They enter the field as HIGH-salience candidates — it
+    // deliberately willed them — but still COMPETE in the selector; they never bypass
+    // it. This is the AffordanceSource.ideomotor leg: executive intention → an
+    // affordance that competes like any other.
+    for( const [ id, e ] of state.entities ){
+      if( e.type !== 'ideomotor.intent' ) continue
+      const m        = e.metadata
+      const schemaId = str( m?.['schema'] )
+      const schema   = schemaId ? schemas.find( s => s.id === schemaId ) : undefined
+      if( !schema ) continue
+      candidates.push({
+        salience: IDEOMOTOR_BASE_SALIENCE + num( m?.['priority'], 0.8 ),
+        affordance: this._build( schema, tick, state, valence, energyLow, skills, {
+          evokedBy:       id,
+          targetEntityId: str( m?.['targetEntityId'] ),
+          parameters:     ( m?.['parameters'] as Record<string, unknown> ) ?? {},
+          source:         'ideomotor',
+        } ),
+      })
+    }
+
+    // ── plan priors: an executing plan's frontier step, pre-activated ──────────
+    // A plan does not dispatch its steps; it BIASES the competition toward the
+    // action its current frontier needs. The PlanningEngine writes one `plan.prior`
+    // per ready frontier step; each enters the field as a HIGH-salience candidate
+    // (the frontier is willed) carrying a `planBias` the scorer weighs and the
+    // planId/stepId provenance that flows through to action.outcome so the plan
+    // advances when the field actually enacts it. Like ideomotor, it never bypasses
+    // the selector — if a more pressing affordance wins, the plan simply re-projects
+    // next tick. The suggested schema must resolve in the repertoire; if it does not,
+    // the prior cannot surface as an action and the plan waits / replans.
+    for( const [ id, e ] of state.entities ){
+      if( e.type !== 'plan.prior' ) continue
+      const m        = e.metadata
+      const schemaId = str( m?.['schema'] )
+      const schema   = schemaId ? schemas.find( s => s.id === schemaId ) : undefined
+      if( !schema ) continue
+      const planBias = clamp01( num( m?.['planBias'], 0.6 ) )
+      candidates.push({
+        salience: IDEOMOTOR_BASE_SALIENCE + planBias,
+        affordance: this._build( schema, tick, state, valence, energyLow, skills, {
+          evokedBy:       id,
+          targetEntityId: str( m?.['targetEntityId'] ),
+          parameters:     ( m?.['parameters'] as Record<string, unknown> ) ?? {},
+          source:         'plan',
+          planBias,
+          planId:         str( m?.['planId'] ),
+          stepId:         str( m?.['stepId'] ),
+        } ),
+      })
+    }
+
+    // Attention gates the WIDTH of the field: keep only the top-salient few.
+    const cap = this._attentionCap( state )
+    candidates.sort( ( a, b ) => b.salience - a.salience )
+    for( const c of candidates.slice( 0, cap ) )
+      set.push( this._toEntity( c.affordance ) )
+
+    // ── 3. metrics + telemetry ───────────────────────────────────
+    const fieldSize      = set.length
+    const availableCount = set.reduce( ( n, e ) => n + ( e.metadata?.['available'] ? 1 : 0 ), 0 )
+    this._lastFieldSize  = fieldSize
+
+    const commands: StateCommands = {
+      set,
+      delete:  del,
+      metrics: [
+        [ 'affordance.field_size',      fieldSize ],
+        [ 'affordance.available_count', availableCount ],
+      ],
+    }
+
+    if( this._bus ){
+      try {
+        this._bus.publish({
+          type:         'affordance.field.synthesized',
+          version:      1,
+          sourceEngine: this.name,
+          salience:     0.3,
+          payload:      { size: fieldSize, availableCount, tick },
+        })
+      }
+      catch( err ){
+        logger.warn( `[affordance] bus publish failed: ${ err instanceof Error ? err.message : String( err ) }` )
+      }
+    }
+
+    return { commands }
+  }
+
+  // ── internals ─────────────────────────────────────────────────
+
+  /** Compose an Affordance from a schema + the evoking context, folding in learned priors. */
+  private _build(
+    schema:   MotorSchema,
+    tick:     Tick,
+    state:    ReadonlySimulationState,
+    valence:  number,
+    energyLow: boolean,
+    skills:   ReadonlyMap<string, LearnedSkill> | null,
+    ctx: {
+      evokedBy?:       string
+      targetEntityId?: string
+      parameters?:     Record<string, unknown>
+      source?:         AffordanceSource
+      planBias?:       number
+      planId?:         string
+      stepId?:         string
+    },
+  ): Affordance {
+    const skill = skills?.get( schema.id )
+
+    // Learned value if known, else the schema's intrinsic prior mapped to 0..1.
+    const expectedReward = skill?.valueEstimate
+      ?? clamp01( ( ( schema.baseValence ?? 0 ) + 1 ) / 2 )
+    const expectedValence = schema.baseValence ?? valence
+    const habitStrength   = skill?.habitStrength ?? 0
+    // Low energy makes everything feel costlier.
+    const cost            = clamp01( schema.cost * ( energyLow ? 1.5 : 1 ) )
+
+    const key    = ctx.targetEntityId ?? ctx.evokedBy ?? schema.id
+    const source = ctx.source ?? schema.source
+    // A non-default-source candidate (ideomotor) gets a distinct id so it can coexist
+    // with a same-schema/target candidate evoked from another source (e.g. entity-bound).
+    const idTag  = ctx.source && ctx.source !== schema.source ? `-${ ctx.source }` : ''
+
+    return {
+      id:              `affordance-${ tick }-${ schema.id }-${ key }${ idTag }`,
+      schema:          schema.id,
+      source,
+      parameters:      { ...( skill?.paramPriors ?? {} ), ...( ctx.parameters ?? {} ) },
+      targetEntityId:  ctx.targetEntityId,
+      evokedBy:        ctx.evokedBy,
+      expectedValence,
+      expectedReward,
+      cost,
+      habitStrength,
+      available:       this._available( schema.preconditions, ( k ) => metric( state, k, 0 ) ),
+      tags:            schema.tags ?? [],
+      planBias:        ctx.planBias,
+      planId:          ctx.planId,
+      stepId:          ctx.stepId,
+      tick,
+    }
+  }
+
+  private _toEntity( a: Affordance ): EntityInput {
+    return {
+      id:   a.id,
+      type: 'affordance',
+      metadata: {
+        schema:          a.schema,
+        source:          a.source,
+        parameters:      a.parameters,
+        targetEntityId:  a.targetEntityId,
+        evokedBy:        a.evokedBy,
+        expectedValence: a.expectedValence,
+        expectedReward:  a.expectedReward,
+        cost:            a.cost,
+        habitStrength:   a.habitStrength,
+        available:       a.available,
+        tags:            a.tags,
+        planBias:        a.planBias,
+        planId:          a.planId,
+        stepId:          a.stepId,
+        tick:            a.tick,
+      },
+    }
+  }
+
+  private _available(
+    preconditions: SchemaPrecondition[] | undefined,
+    read: ( metric: string ) => number,
+  ): boolean {
+    if( !preconditions ) return true
+    return preconditions.every( pc => {
+      const cur = read( pc.metric )
+      switch( pc.op ){
+        case 'gt':  return cur >  pc.value
+        case 'lt':  return cur <  pc.value
+        case 'gte': return cur >= pc.value
+        case 'lte': return cur <= pc.value
+        case 'eq':  return cur === pc.value
+        default:    return false
+      }
+    })
+  }
+
+  private _attentionCap( state: ReadonlySimulationState ): number {
+    const cap = state.metrics.get( 'attention.capacity' ) ?? this._defaultCap
+    return Math.max( 1, Math.min( MAX_ATTENTION_CAP, Math.round( cap ) ) )
+  }
+}
+
+// ─── module helpers ──────────────────────────────────────────────────────────
+
+function metric( state: ReadonlySimulationState, key: string, fallback: number ): number {
+  return state.metrics.get( key ) ?? fallback
+}
+
+function num( v: unknown, fallback: number ): number {
+  return typeof v === 'number' && Number.isFinite( v ) ? v : fallback
+}
+
+function str( v: unknown ): string | undefined {
+  return typeof v === 'string' ? v : undefined
+}
+
+function clamp01( n: number ): number {
+  return n < 0 ? 0 : n > 1 ? 1 : n
+}

package/src/cognition/agency/engines/deliberation.engine.ts

@@ -0,0 +1,241 @@
+// ─────────────────────────────────────────────────────────────
+// src/agency/deliberation.engine.ts  —  the System-2 seam
+// ─────────────────────────────────────────────────────────────
+//
+// The DeliberationEngine is the only place the LLM touches the agency pipeline,
+// and it does so through the SAME unified-inference path as everything else: it
+// spawns a facet — "a focused instance of the executive consciousness" — which
+// builds its prompt from the unified PromptFactory (persona, identity, live
+// self-context). There is NO bespoke prompt here. This is the project-wide rule:
+// every LLM call shares one self, so the Will never fractures / hallucinates a
+// different identity when it deliberates vs. converses vs. narrates.
+//
+// It is recruited only when the selector marks a choice 'deliberating' (ambiguous
+// or high-stakes). It then biases the competition — choosing among the candidate
+// affordances the substrate already surfaced (ideomotor: imagining outcomes
+// pre-activates one) — and writes the result back as the now-'selected' intent.
+// It never invents actions outside the field. Message *content* authoring stays
+// with the unified conversation facet path (AuditionEngine), not duplicated here.
+//
+// With no executive attached (basic tier) or the facet budget full, it confirms
+// the substrate's provisional winner — graceful System-1 degradation, never a
+// stall, and never an un-grounded LLM call.
+// ─────────────────────────────────────────────────────────────
+
+import { logger } from '#core/logger'
+import type {
+  Duration, Tick, SimulationContext,
+  ReadonlySimulationState, StateCommands, EntityInput,
+} from '#core/types'
+import type { CognitiveBus } from '#cognition/bus'
+import type { CognitiveEngine, EngineResult } from '#cognition/types'
+import type { CognitiveEventSchema } from '#cognition/schema.registry'
+
+// ── Minimal structural view of the executive's facet machinery ───────────────
+// Kept structural (not an import of the executive engine) so the agency module
+// stays decoupled; ExecutiveEngine is assignable to DeliberationFacetProvider.
+
+interface DeliberationFacetHandle {
+  setFocus( focus: { title: string; content: string; instructions?: string; function?: string } ): void
+  report( report: { type: string; payload: unknown } ): Promise<void> | void
+  subscribe( listener: ( decision: { decision: unknown } ) => void ): () => void
+  destroy(): void
+}
+export interface DeliberationFacetProvider {
+  spawnFacet(): { attention: 'available' | 'full'; handle?: DeliberationFacetHandle }
+}
+
+interface Candidate {
+  schema:          string
+  targetEntityId?: string
+  parameters?:     Record<string, unknown>
+  activation?:     number
+  /** Channel B: this candidate is an active plan's current frontier step. */
+  fromPlan?:       boolean
+}
+
+const DELIBERATION_INSTRUCTIONS =
+  'Automatic action-selection was uncertain or the stakes were high. From the candidate actions ' +
+  'listed above, choose the ONE that best fits who you are and your situation. Do not invent ' +
+  'actions that are not listed. Put your chosen action as your single action; its "type" must be ' +
+  'exactly one of the candidate names.'
+
+export class DeliberationEngine implements CognitiveEngine {
+  readonly name = 'deliberation'
+
+  private _provider: DeliberationFacetProvider | null = null
+  private _handle:   DeliberationFacetHandle | null = null
+  private _bus:      CognitiveBus | null = null
+  private _willName  = 'the mind'
+  private _deliberations = 0
+
+  attachBus( bus: CognitiveBus ): void { this._bus = bus }
+  /**
+   * Attach the executive (facet provider). Absent ⇒ the engine confirms the
+   * substrate's winner (System 1) — used at basic tier where no LLM runs.
+   */
+  attachExecutive( provider: DeliberationFacetProvider ): void { this._provider = provider }
+  setWillName( name: string ): void { this._willName = name }
+
+  publishes(): CognitiveEventSchema[] {
+    return [ { type: 'agency.deliberated', version: 1, validate: () => null } ]
+  }
+  subscribes(): string[] { return [] }
+  onCognitiveEvent(): void { /* pull model — reads deliberating intents from frozen state */ }
+  snapshot(): Record<string, unknown> { return { deliberations: this._deliberations } }
+
+  async react(
+    _delta:   Duration,
+    tick:     Tick,
+    state:    ReadonlySimulationState,
+    _context: SimulationContext,
+  ): Promise<EngineResult> {
+    // One deliberation per tick (the serial bottleneck).
+    let target: { id: string; meta: Record<string, unknown> } | null = null
+    for( const [ id, e ] of state.entities ){
+      if( e.type !== 'agency.intent' ) continue
+      if( str( e.metadata?.['status'] ) !== 'deliberating' ) continue
+      const meta = ( e.metadata ?? {} ) as Record<string, unknown>
+      if( !target || id < target.id ) target = { id, meta }   // stable pick
+    }
+    if( !target ) return { commands: {} }
+
+    const { id, meta }   = target
+    const provisional    = str( meta['schema'] ) ?? 'wait'
+    const candidates: Candidate[] = Array.isArray( meta['candidates'] ) ? ( meta['candidates'] as Candidate[] ) : []
+
+    // No executive → confirm the substrate's winner (graceful System-1).
+    if( !this._provider )
+      return { commands: { set: [ this._commit( id, meta, provisional, candidates, 'no-executive' ) ] } }
+
+    // Deliberate through a UNIFIED facet (same persona/context as the master).
+    const chosen = await this._deliberate( state, candidates, provisional, meta )
+
+    this._deliberations++
+    if( this._bus ){
+      try {
+        this._bus.publish({
+          type: 'agency.deliberated', version: 1, sourceEngine: this.name,
+          salience: 0.6, payload: { intentId: id, chosen, tick },
+        })
+      }
+      catch { /* unregistered schema is telemetry-only */ }
+    }
+
+    return {
+      commands: {
+        set:     [ this._commit( id, meta, chosen, candidates, 'facet' ) ],
+        metrics: [ [ 'agency.deliberation.count', 1 ] ],
+      },
+    }
+  }
+
+  // ── internals ─────────────────────────────────────────────────
+
+  /** Run one unified-inference deliberation. Returns the chosen schema (or the provisional winner on any failure). */
+  private async _deliberate(
+    state:       ReadonlySimulationState,
+    candidates:  Candidate[],
+    provisional: string,
+    meta:        Record<string, unknown>,
+  ): Promise<string> {
+    try {
+      if( !this._handle ){
+        const spawned = this._provider!.spawnFacet()
+        if( spawned.attention === 'full' || !spawned.handle ){
+          logger.info( '[deliberation] facet budget full — confirming substrate winner' )
+          return provisional
+        }
+        this._handle = spawned.handle
+      }
+
+      let capturedDecision: unknown = undefined
+      const unsub = this._handle.subscribe( d => { capturedDecision = d.decision } )
+
+      this._handle.setFocus({
+        title:        'Deliberation',
+        function:     'deliberation',
+        content:      this._buildFocusContent( state, candidates, meta ),
+        instructions: DELIBERATION_INSTRUCTIONS,
+      })
+      await this._handle.report({ type: 'deliberation', payload: { candidateSchemas: candidates.map( c => c.schema ) } })
+      unsub()
+
+      const picked = extractChosen( capturedDecision, candidates )
+      return picked ?? provisional
+    }
+    catch( err ){
+      // Director/state not ready (e.g. executive hasn't run yet) or LLM failure →
+      // fall back to the substrate winner. Drop a possibly-dead handle.
+      this._handle = null
+      logger.warn( `[deliberation] facet unavailable, confirming winner: ${ err instanceof Error ? err.message : String( err ) }` )
+      return provisional
+    }
+  }
+
+  /** Write the deliberating intent back as 'selected' with the chosen action. */
+  private _commit(
+    id:         string,
+    meta:       Record<string, unknown>,
+    chosen:     string,
+    candidates: Candidate[],
+    via:        string,
+  ): EntityInput {
+    const cand = candidates.find( c => c.schema === chosen )
+    return {
+      id, type: 'agency.intent',
+      metadata: {
+        ...meta,
+        schema:         chosen,
+        targetEntityId: cand?.targetEntityId ?? meta['targetEntityId'],
+        parameters:     { ...( ( meta['parameters'] as Record<string, unknown> ) ?? {} ), ...( cand?.parameters ?? {} ) },
+        status:         'selected',
+        deliberated:    true,
+        deliberatedVia: via,
+      },
+    }
+  }
+
+  /** The deliberation focus body — the candidate actions the substrate surfaced. */
+  private _buildFocusContent(
+    state:      ReadonlySimulationState,
+    candidates: Candidate[],
+    meta:       Record<string, unknown>,
+  ): string {
+    const lines: string[] = []
+    // Channel B: if this choice arose by interrupting a pending action, name it so the
+    // facet owns the interruption in-character rather than reasoning in a vacuum.
+    const preemptedFrom = str( meta['preemptedFrom'] )
+    if( preemptedFrom )
+      lines.push( `You just broke off a pending action ("${ preemptedFrom }") because something more pressing pulled at you. Decide what to do now:` )
+    else
+      lines.push( 'Your automatic action-selection was uncertain. Candidate actions:' )
+    candidates.forEach( ( c, i ) => {
+      const to   = c.targetEntityId ? ` toward ${ c.targetEntityId }` : ''
+      // Channel B: name the plan link so the facet chooses as the self pursuing it,
+      // not blindly among labels ("this one is the next step of the plan I'm on").
+      const plan = c.fromPlan ? " — your current plan's next step" : ''
+      lines.push( `${ i + 1 }. ${ c.schema }${ to }${ plan }` )
+    })
+    return lines.join( '\n' )
+  }
+}
+
+// ─── decoding ────────────────────────────────────────────────────────────────
+
+/** Pull the chosen schema from a facet decision, validated against the candidates. */
+function extractChosen( decision: unknown, candidates: Candidate[] ): string | undefined {
+  if( !decision || typeof decision !== 'object' ) return undefined
+  const actions = ( decision as Record<string, unknown> )['actions']
+  if( !Array.isArray( actions ) ) return undefined
+  const valid = new Set( candidates.map( c => c.schema ) )
+  for( const a of actions ){
+    const type = ( a as Record<string, unknown> )?.['type']
+    if( typeof type === 'string' && valid.has( type ) ) return type
+  }
+  return undefined
+}
+
+function str( v: unknown ): string | undefined {
+  return typeof v === 'string' ? v : undefined
+}

package/src/cognition/agency/engines/instruction.intake.ts

@@ -0,0 +1,54 @@
+// ─────────────────────────────────────────────────────────────
+// src/agency/instruction.intake.ts  —  instruction → goal
+// ─────────────────────────────────────────────────────────────
+//
+// External instructions (developer/host directives injected into state) become
+// the Will's own goals here. This role used to live inside the legacy
+// ActionExecutor; on the agency cutover it moves to a small dedicated intake so
+// the legacy executor can be retired. Behaviour is preserved verbatim: each tick
+// it drains pending instructions and converts them to goals via the same
+// InstructionHandler + GoalManager.
+// ─────────────────────────────────────────────────────────────
+
+import type {
+  Duration, Tick, SimulationContext, ReadonlySimulationState,
+} from '#core/types'
+import type { CognitiveEngine, EngineResult } from '#cognition/types'
+import type { CognitiveEventSchema } from '#cognition/schema.registry'
+import type { InstructionHandler } from '#cognition/instruction.handler'
+import type { GoalManager } from '#faculties/goal.manager'
+
+export class InstructionIntake implements CognitiveEngine {
+  readonly name = 'instruction-intake'
+
+  private _instructionHandler: InstructionHandler | null = null
+  private _goalManager:        GoalManager | null = null
+
+  attachInstructionHandler( h: InstructionHandler ): void { this._instructionHandler = h }
+  attachGoalManager( gm: GoalManager ): void { this._goalManager = gm }
+
+  publishes(): CognitiveEventSchema[] { return [] }
+  subscribes(): string[] { return [] }
+  onCognitiveEvent(): void { /* pull model — reads pending instructions from state */ }
+  snapshot(): Record<string, unknown> {
+    return { pending: this._instructionHandler?.getPending().length ?? 0 }
+  }
+
+  async react(
+    _delta:   Duration,
+    _tick:    Tick,
+    state:    ReadonlySimulationState,
+    _context: SimulationContext,
+  ): Promise<EngineResult> {
+    const handler = this._instructionHandler
+    const goals   = this._goalManager
+    if( !handler || !goals ) return { commands: {} }
+
+    for( const instruction of handler.evaluatePending( state, [] ) ){
+      const g = handler.convertToGoal( instruction )
+      goals.addGoal( g.description, g.priority, g.tags, undefined, undefined, g.completionType, g.completionCondition )
+    }
+
+    return { commands: {} }
+  }
+}