@mindot/will 0.1.1 → 0.2.0

package/src/sdk/will.ts

@@ -9,8 +9,14 @@
 //   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
+//   await will.perceive({ from: 'ada', text: 'What should we work on?' })
+//   const reply = await will.nextUtterance({ to: 'ada' })   // WillMessage | null
+//   const pma = await will.save()               // non-destructive; keeps ticking
+//
+// A Will is a *subject*, not a function: you `perceive` stimuli to it and observe
+// its *projections* (message / effector / emotion / state) — you never `await`
+// a computed return. `nextUtterance` is a thin, honest adapter for callers that
+// want a reply-shaped await; `null` means the Will chose silence, not an error.
 //
 // Everything under here already existed; the facade hides the plumbing:
 //   • one message → outbox drain → delivery-ack, surfaced as an event;
@@ -25,9 +31,27 @@ 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'
+import type { EffectorDeclaration, SchemaPrecondition } from '#agency/types'
 
 // ── Public surface ────────────────────────────────────────────
 
+/**
+ * A stimulus entering the Will's sensory field. A Will is a subject, not a
+ * function: you don't *call* it with input and await a return — you `perceive`
+ * something to it, and it *may* project a response later (see `nextUtterance`),
+ * coloured by its current state. Silence is a valid, meaningful outcome.
+ */
+export interface Stimulus {
+  /** What was said / observed. */
+  text: string
+  /** Who it's from (entity id). Default 'user'. */
+  from?: string
+  /** Display name of the speaker. Default 'You' for `user`, else the `from` id. */
+  speaker?: string
+  /** Conversation/thread id (default = `from`). */
+  thread?: string
+}
+
 /** A message the Will emitted to someone. */
 export interface WillMessage {
   /** Message id (stable — dedupe on it). */
@@ -38,6 +62,28 @@ export interface WillMessage {
   to: string
 }
 
+/**
+ * A motor act the Will *chose* to enact — a projection of its agency, surfaced
+ * whether or not you registered a handler for it. (When you did, the handler
+ * still runs and its outcome feeds reafference.)
+ */
+export interface WillEffectorAct {
+  /** The effector the Will selected. */
+  name: string
+  /** The arguments it bound. */
+  args: Record<string, unknown>
+  /** Its stated reason for the act. */
+  reasoning: string
+  /** Bound target entity, when the act binds one. */
+  to?: string
+}
+
+/** The Will's affect, projected when it shifts. Valence/arousal ∈ −1..1. */
+export interface WillAffect {
+  valence: number
+  arousal: number
+}
+
 /**
  * The result of an effector your handler ran. Return a bare string as shorthand
  * for `{ success: true, description }`. `metrics` optionally writes world state
@@ -52,9 +98,45 @@ export type EffectorResult = string | {
 /** Your implementation of an ability the Will can choose to use. */
 export type EffectorHandler = (
   args: Record<string, unknown>,
-  ctx: { reasoning: string; targetEntityId?: string },
+  ctx: { reasoning: string; targetEntityId?: string; description?: string },
 ) => EffectorResult | Promise<EffectorResult>
 
+/**
+ * A richer effector declaration — the ability seeded as a *learnable affordance*.
+ * `description` is its meaning (carried to perception + your handler); `cost`,
+ * `valence`, and `preconditions` are the intrinsic priors the mind starts from,
+ * refined by reafference through use. Args still bind from the situation — this
+ * is not a tool-call parameter form. Declare rich effectors in `create()`'s
+ * `effectors` map (that is where they enter the affordance repertoire).
+ */
+export interface EffectorSpec {
+  /** What the ability is for. */
+  description?: string
+  /** Intrinsic effort / energy demand 0..1 (default 0.15). */
+  cost?: number
+  /** Intrinsic reward prior −1..1 the mind expects before learning (default 0). */
+  valence?: number
+  /** Body-state gates; the ability is unavailable unless all pass. */
+  preconditions?: SchemaPrecondition[]
+  /**
+   * Whether the ability targets a specific perceived target (default 'none').
+   * 'entity' directs it at a known person, 'object' at a known thing; the bound
+   * target arrives as `ctx.targetEntityId`.
+   */
+  binds?: 'none' | 'entity' | 'object'
+  /**
+   * Routing tags (merged with 'external'/'host'). A drive-recognised tag (e.g.
+   * 'social', 'nourishment') lets a homeostatic drive lift this ability when it
+   * presses.
+   */
+  tags?: string[]
+  /** Your implementation. */
+  handler: EffectorHandler
+}
+
+/** An effectors-map value: a bare handler, or a spec carrying meaning + priors. */
+export type EffectorEntry = EffectorHandler | EffectorSpec
+
 /** A compact read of the mind's current inner state. */
 export interface WillStateSummary {
   tick: number
@@ -84,8 +166,13 @@ export interface CreateWillOptions {
    * (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>
+  /**
+   * Abilities the Will can choose to enact. `name → handler`, or
+   * `name → { handler, description?, cost?, valence?, preconditions? }` to seed
+   * the ability with meaning + intrinsic priors (see EffectorSpec). Declared
+   * here (create time) so they enter the affordance repertoire.
+   */
+  effectors?: Record<string, EffectorEntry>
   /** Goals seeded before the first tick. Usually leave empty — the Will forms its own. */
   initialGoals?: InitialGoal[]
   /** Persist snapshots to disk across restarts (default false). */
@@ -98,7 +185,18 @@ export interface CreateWillOptions {
   id?: string
 }
 
-type WillEvent = 'message' | 'state' | 'error'
+type WillEvent = 'message' | 'state' | 'effector' | 'emotion' | 'error'
+
+/** A caller awaiting the Will's next spontaneous utterance (see nextUtterance). */
+interface UtteranceWaiter {
+  /** Only resolve on an utterance addressed to this entity, when set. */
+  to?: string
+  resolve: ( m: WillMessage | null ) => void
+  timer:   ReturnType<typeof setTimeout>
+}
+
+/** Affect must move at least this far (−1..1) before another `emotion` projection. */
+const AFFECT_EPSILON = 0.02
 
 // ── The facade ────────────────────────────────────────────────
 
@@ -110,9 +208,15 @@ export class Will {
   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>()
+  /** Rich declarations for create-time effectors → seed the affordance repertoire. */
+  private readonly _effectorDecls = new Map<string, EffectorDeclaration>()
+  private readonly _messageHandlers  = new Set<( m: WillMessage ) => void>()
+  private readonly _stateHandlers    = new Set<( s: WillStateSummary ) => void>()
+  private readonly _effectorHandlers = new Set<( a: WillEffectorAct ) => void>()
+  private readonly _emotionHandlers  = new Set<( a: WillAffect ) => void>()
+  private readonly _errorHandlers    = new Set<( e: Error ) => void>()
+  private readonly _utteranceWaiters = new Set<UtteranceWaiter>()
+  private _lastAffect: WillAffect | null = null
   private _unsub: ( () => void ) | null = null
 
   private constructor( stem: WillStem, id: string, name: string ){
@@ -127,8 +231,8 @@ export class Will {
     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 )
+    for( const [ name, entry ] of Object.entries( opts.effectors ?? {} ) )
+      will._register( name, entry )
 
     await stem.createWill( will._buildConfig( id, opts ) )
     will._attach()
@@ -148,8 +252,8 @@ export class Will {
     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 )
+    for( const [ name, entry ] of Object.entries( opts.effectors ?? {} ) )
+      will._register( name, entry )
 
     await stem.createWill(
       will._buildConfig( id, { ...opts, identity: { prompt: '', ...opts.identity } } ),
@@ -161,38 +265,107 @@ export class Will {
     return will
   }
 
-  // ── Talking ────────────────────────────────────────────────
+  // ── Perceiving ─────────────────────────────────────────────
 
   /**
-   * 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.
+   * Deliver a stimulus into the Will's sensory field. This is the one true
+   * intake — `say`/`tell` are sugar over it. It returns once the stimulus is
+   * *delivered*, NOT once the Will has responded: a response (if any) is a
+   * projection that arrives later on the `message` event, or via
+   * `nextUtterance()`. The Will may also stay silent — that is not an error.
    */
+  async perceive( stimulus: Stimulus ): Promise<void> {
+    const from = stimulus.from ?? 'user'
+    await this.stem.ingestText( this.id, {
+      kind:        'text',
+      entityId:    from,
+      threadId:    stimulus.thread ?? from,
+      content:     stimulus.text,
+      speakerName: stimulus.speaker ?? ( from === 'user' ? 'You' : from ),
+    } )
+  }
+
+  /** Perceive from the default user. Sugar over `perceive`. */
   async say( text: string ): Promise<void> {
-    return this.tell( 'user', 'You', text )
+    return this.perceive( { text, from: 'user', speaker: 'You' } )
   }
 
-  /** Speak as a specific interlocutor (multi-party conversations). */
+  /** Perceive from a specific interlocutor (multi-party). Sugar over `perceive`. */
   async tell( entityId: string, speakerName: string, text: string ): Promise<void> {
-    await this.stem.ingestText( this.id, {
-      kind: 'text', entityId, threadId: entityId, content: text, speakerName,
+    return this.perceive( { text, from: entityId, speaker: speakerName } )
+  }
+
+  /**
+   * Await the Will's *next spontaneous utterance* — a thin, honest adapter over
+   * the `message` projection stream for request/response callers. Resolves with
+   * the message, or `null` if the Will stays silent within `within` ms (default
+   * 5000). `null` is a real outcome — the Will chose not to speak — not a
+   * failure. Pass `to` to only accept an utterance addressed to that entity.
+   *
+   *   await will.perceive( { from: 'ada', text: 'Hi!' } )
+   *   const reply = await will.nextUtterance( { to: 'ada', within: 3000 } )
+   *   // reply is a WillMessage, or null if Ada got the silent treatment.
+   */
+  nextUtterance( opts: { within?: number; to?: string } = {} ): Promise<WillMessage | null> {
+    return new Promise<WillMessage | null>( resolve => {
+      const timer = setTimeout( () => {
+        this._utteranceWaiters.delete( waiter )
+        resolve( null )
+      }, opts.within ?? 5000 )
+      // Don't let a pending wait keep the host process alive.
+      ;( timer as { unref?: () => void } ).unref?.()
+      const waiter: UtteranceWaiter = { to: opts.to, resolve, timer }
+      this._utteranceWaiters.add( waiter )
     } )
   }
 
   // ── 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.
+   * Register an ability the Will can choose to enact, at runtime. `entry` is a
+   * bare handler or a full spec (`{ handler, description?, cost?, valence?,
+   * preconditions?, binds?, tags? }`). When the Will decides to use `name`, your
+   * handler runs with the arguments it chose; the return value feeds back as the
+   * outcome (the reafference loop that lets the Will learn the ability).
+   *
+   * The ability's schema is added to the live repertoire so it can actually be
+   * *afforded* immediately (a grant alone only gates), then granted. Note: this
+   * is a runtime mutation — the deterministic/replayable path is declaring
+   * effectors in `create()`'s `effectors` map.
    */
-  effector( name: string, handler: EffectorHandler ): this {
-    this._effectors.set( name, handler )
-    // Communication effectors + every registered custom name.
+  effector( name: string, entry: EffectorEntry ): this {
+    this._register( name, entry )
+    // Add its schema to the live repertoire (so it can be perceived + enacted),
+    // then grant it. Comms names are no-ops in registerEffector (grant-governed).
+    this.stem.registerEffector( this.id, this._effectorDecls.get( name )! )
     this.stem.setAllowedEffectors( this.id, [ ...COMMUNICATION, ...this._effectors.keys() ] )
     return this
   }
 
+  /** Split an effectors-map entry into a handler + an EffectorDeclaration. */
+  private _register( name: string, entry: EffectorEntry ): void {
+    if( typeof entry === 'function' ){
+      this._effectors.set( name, entry )
+      this._effectorDecls.set( name, name )          // bare name — uniform prior
+      return
+    }
+    this._effectors.set( name, entry.handler )
+    const hasMeta = entry.description !== undefined || entry.cost !== undefined
+      || entry.valence !== undefined || entry.preconditions !== undefined
+      || entry.binds !== undefined || entry.tags !== undefined
+    this._effectorDecls.set( name, hasMeta
+      ? {
+          name,
+          ...( entry.description   !== undefined ? { description:   entry.description   } : {} ),
+          ...( entry.cost          !== undefined ? { cost:          entry.cost          } : {} ),
+          ...( entry.valence       !== undefined ? { valence:       entry.valence       } : {} ),
+          ...( entry.preconditions !== undefined ? { preconditions: entry.preconditions } : {} ),
+          ...( entry.binds         !== undefined ? { binds:         entry.binds         } : {} ),
+          ...( entry.tags          !== undefined ? { tags:          entry.tags          } : {} ),
+        }
+      : name )
+  }
+
   // ── Introspection ──────────────────────────────────────────
 
   /** A compact snapshot of the mind's current inner state. */
@@ -215,13 +388,19 @@ export class Will {
 
   // ── 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: 'message',  handler: ( m: WillMessage ) => void ): this
+  on( event: 'state',    handler: ( s: WillStateSummary ) => void ): this
+  on( event: 'effector', handler: ( a: WillEffectorAct ) => void ): this
+  on( event: 'emotion',  handler: ( a: WillAffect ) => 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 )
+    switch( event ){
+      case 'message':  this._messageHandlers.add(  handler as ( m: WillMessage ) => void ); break
+      case 'state':    this._stateHandlers.add(    handler as ( s: WillStateSummary ) => void ); break
+      case 'effector': this._effectorHandlers.add( handler as ( a: WillEffectorAct ) => void ); break
+      case 'emotion':  this._emotionHandlers.add(  handler as ( a: WillAffect ) => void ); break
+      default:         this._errorHandlers.add(    handler as ( e: Error ) => void )
+    }
     return this
   }
 
@@ -231,9 +410,19 @@ export class Will {
   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.
+   * Checkpoint the living mind into a portable PMA artifact — NON-destructive.
+   * The Will keeps ticking; the snapshot is a point-in-time copy you can archive
+   * or wake elsewhere. Use this for periodic saves; use `hibernate()` to sleep.
+   */
+  async save(): Promise<PMASnapshot> {
+    return this.stem.distillPMA( this.id )
+  }
+
+  /**
+   * Distil the mind into a portable PMA artifact and archive it — DESTRUCTIVE:
+   * the tick loop stops (the Will sleeps). The returned snapshot restores the
+   * same self via `Will.wake()` — across a restart, a fork, or a machine
+   * boundary. For a copy that leaves the Will running, use `save()`.
    */
   async hibernate(): Promise<PMASnapshot> {
     const pma = this.stem.distillPMA( this.id )
@@ -243,6 +432,9 @@ export class Will {
 
   /** Tear the Will down (its tick loop stops; state is discarded unless persisted). */
   async stop(): Promise<void> {
+    // Resolve anyone awaiting an utterance — the Will won't speak again.
+    for( const w of this._utteranceWaiters ){ clearTimeout( w.timer ); w.resolve( null ) }
+    this._utteranceWaiters.clear()
     this._unsub?.()
     this._unsub = null
     await this.stem.archiveWill( this.id )
@@ -266,7 +458,7 @@ export class Will {
       persistentMemory: opts.persist ?? false,
       snapshotInterval: 100,
       tickIntervalMs:   opts.tickMs ?? 1000,
-      allowedGenericEffectors: [ ...COMMUNICATION, ...this._effectors.keys() ],
+      allowedGenericEffectors: [ ...COMMUNICATION, ...this._effectorDecls.values() ],
       initialGoals: opts.initialGoals ?? [],
       ...( opts.seed !== undefined ? { randomSeed: opts.seed, clock: { fixedDeltaMs: 1000, startTime: 0 } } : {} ),
     }
@@ -280,14 +472,22 @@ export class Will {
         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 )
+      // Effector invocations → project the motor act, then run the handler → ack.
+      for( const inv of invocations ){
+        this._emitEffectorAct( { name: inv.effectorName, args: inv.parameters, reasoning: inv.reasoning, to: inv.targetEntityId } )
         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 */ }
+      // Projections that read the state summary — compute it once, and only when
+      // something is actually observing (state() is cheap but not free). Isolated
+      // so a transient read error can never stall the tick loop.
+      if( this._stateHandlers.size > 0 || this._emotionHandlers.size > 0 ){
+        try {
+          const s = this.state()
+          for( const h of this._stateHandlers ) try { h( s ) } catch { /* isolate */ }
+          if( this._emotionHandlers.size > 0 ) this._maybeEmitAffect( s.metrics.valence, s.metrics.arousal )
+        }
+        catch( e ){ this._emitError( e as Error ) }
       }
     } ) ?? null
   }
@@ -304,7 +504,11 @@ export class Will {
     }
 
     try {
-      const raw = await handler( inv.parameters, { reasoning: inv.reasoning, targetEntityId: inv.targetEntityId } )
+      const raw = await handler( inv.parameters, {
+        reasoning: inv.reasoning,
+        targetEntityId: inv.targetEntityId,
+        ...( inv.description ? { description: inv.description } : {} ),
+      } )
       const result = typeof raw === 'string' ? { success: true, description: raw } : raw
       this.stem.confirmEffectorExecution( this.id, inv.decisionRecordId, result )
     }
@@ -318,6 +522,27 @@ export class Will {
 
   private _emitMessage( m: WillMessage ): void {
     for( const h of this._messageHandlers ) try { h( m ) } catch( e ){ this._emitError( e as Error ) }
+    // Wake any nextUtterance() awaiter this message satisfies.
+    if( this._utteranceWaiters.size > 0 ){
+      for( const w of [ ...this._utteranceWaiters ] ){
+        if( w.to !== undefined && w.to !== m.to ) continue
+        clearTimeout( w.timer )
+        this._utteranceWaiters.delete( w )
+        w.resolve( m )
+      }
+    }
+  }
+  private _emitEffectorAct( a: WillEffectorAct ): void {
+    for( const h of this._effectorHandlers ) try { h( a ) } catch( e ){ this._emitError( e as Error ) }
+  }
+  private _maybeEmitAffect( valence: number, arousal: number ): void {
+    const last = this._lastAffect
+    // Emit on the first read, then only when affect moves past the epsilon.
+    if( last
+      && Math.abs( last.valence - valence ) < AFFECT_EPSILON
+      && Math.abs( last.arousal - arousal ) < AFFECT_EPSILON ) return
+    this._lastAffect = { valence, arousal }
+    for( const h of this._emotionHandlers ) try { h( { valence, arousal } ) } 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 */ }

package/src/stem/index.ts

@@ -38,6 +38,8 @@ import { TransportController } from '#stem/tracts/transport.controller'
 import { InboundQueue } from '#stem/tracts/inbound.queue'
 import type { ExternalTransport } from '#stem/tracts/transport'
 import { effectorController } from '#stem/tracts/effector.controller'
+import { externalSchemas } from '#agency/schemas/external'
+import type { EffectorDeclaration } from '#agency/types'
 import { SensoryController } from '#stem/tracts/sensory.controller'
 import { BiographyWriter } from '#stem/tracts/biography.writer'
 import { HealthReporter } from '#stem/tracts/health.reporter'
@@ -772,6 +774,20 @@ export class WillStem {
     this._effector.setAllowed( this._get( id ), effectors )
   }
 
+  /**
+   * Register a host effector on a *running* Will (post-create `.effector()`).
+   * Builds its external schema and adds it to the live repertoire so the Will
+   * can actually perceive + enact it — a grant alone only gates; without the
+   * schema the ability could never be afforded. Comms names are no-ops here
+   * (governed by AccessGrants). This is a runtime mutation, like a grant change;
+   * the deterministic/replayable path is declaring effectors at create time.
+   */
+  registerEffector( id: string, declaration: EffectorDeclaration ): void {
+    const repertoire = this._get( id ).cognition.schemaRepertoire
+    for( const schema of externalSchemas( [ declaration ] ) )
+      repertoire.registerExternal( schema )
+  }
+
   /**
    * Called by the host/WorldInterface after executing a host-owned effector.
    * `invocationId` is the correlation handle the host echoed (the awaiting

package/src/stem/mind.ts

@@ -40,6 +40,7 @@ import { InstructionIntake }     from '#agency/engines/instruction.intake'
 import { SchemaRepertoire }      from '#agency/schemas/repertoire'
 import { INNATE_SCHEMAS }        from '#agency/schemas/innate'
 import { externalSchemas }       from '#agency/schemas/external'
+import { effectorName, type EffectorDeclaration } from '#agency/types'
 
 
 import {
@@ -260,8 +261,12 @@ export interface WillConfig {
    *
    * null or omitted = no communication effectors (minimal default).
    * Example: ['listen', 'talk', 'text'] enables inbound + text outbound.
+   *
+   * A domain effector may be a bare name or an object carrying its meaning +
+   * intrinsic priors: `{ name, description?, cost?, valence?, preconditions? }`
+   * (see EffectorDeclaration). Comms names are always bare.
    */
-  allowedGenericEffectors?: string[] | null
+  allowedGenericEffectors?: EffectorDeclaration[] | null
 
   /**
    * When true the executive engine uses a canned mock LLM response instead of
@@ -506,7 +511,7 @@ export function assembleMind( willId: string, config: WillConfig ): MindAssembly
   // creation; warnings surface; safe issues are sanitized in place.
   const idGuard = validateWillIdentity({
     identity:       config.identity,
-    effectors:      Array.isArray( config.allowedGenericEffectors ) ? config.allowedGenericEffectors : ( profile?.effectors ?? null ),
+    effectors:      ( Array.isArray( config.allowedGenericEffectors ) ? config.allowedGenericEffectors : ( profile?.effectors ?? null ) )?.map( effectorName ) ?? null,
     profileContext: profile?.context,
   })
   if( !idGuard.ok )
@@ -655,13 +660,15 @@ function _constructCognition(
   // This matters when a profile Will is created without specifying effectors:
   // the DB stores null, the service passes null, and profile effectors must win.
   // An empty array [] means "explicitly no effectors" (survives restart correctly).
-  const resolvedEffectors = Array.isArray( config.allowedGenericEffectors )
+  const resolvedEffectors: EffectorDeclaration[] | null = Array.isArray( config.allowedGenericEffectors )
     ? config.allowedGenericEffectors
     : ( profile?.effectors ?? null )
+  // Name-only view for the grant / permission surfaces (comms gating is by name).
+  const resolvedEffectorNames = resolvedEffectors?.map( effectorName ) ?? null
 
   // Agency-native permission / sense-gate authority, seeded from the resolved
   // grant list. The senses + reply path read this. (Replaced effectorRegistry.)
-  const accessGrants = new AccessGrants( resolvedEffectors )
+  const accessGrants = new AccessGrants( resolvedEffectorNames )
 
   // ── Executive Engine ────────────────────────────────────────
   // Created for all tiers so the Cognition type is always satisfied.

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

@@ -51,6 +51,7 @@ export class effectorController {
       parameters:       ( payload.parameters as Record<string, unknown> ) ?? {},
       targetEntityId:   payload.targetEntityId as string | undefined,
       reasoning:        ( payload.reasoning as string ) ?? '',
+      ...( typeof payload.description === 'string' ? { description: payload.description } : {} ),
       tick:             ( payload.tick as number ) ?? 0,
       timestamp:        Date.now()
     })

package/src/types.ts

@@ -29,6 +29,8 @@ export interface effectorInvocation {
   parameters:       Record<string, unknown>
   targetEntityId:   string | undefined
   reasoning:        string
+  /** The ability's declared meaning (from its EffectorDeclaration), when present. */
+  description?:     string
   tick:             number
   timestamp:        number
 }