@mindot/will 0.1.0

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

@@ -0,0 +1,241 @@
+// ─────────────────────────────────────────────────────────────
+// src/agency/reafference.engine.ts  —  prediction error → competence
+// ─────────────────────────────────────────────────────────────
+//
+// Reafference is the loop that makes the Will grow. Each tick it reads the
+// `agency.outcome` records the executor wrote, folds each into its schema's
+// LearnedSkill (value, habit, prediction error, param priors — see
+// repertoire.ts), and mirrors the updated skills into `agency.skill` state
+// entities so they snapshot, surface in telemetry, and travel in the PMA. It
+// likewise mirrors learned composite *templates* into `agency.schema` entities
+// so the invented multi-step programs survive a restore (the executor resolves
+// the template to expand a macro); restoreComposites() rehydrates them.
+//
+// The behavioural payoff closes the loop with selection: a schema that succeeds
+// reliably AND predictably crosses the proceduralization threshold, which both
+// raises its activation (additive habit bonus) and relaxes its deliberation
+// threshold — so it stops recruiting the LLM. Inference spend falls as the Will
+// learns. Disuse runs the forgetting curve in the other direction.
+// ─────────────────────────────────────────────────────────────
+
+import { logger } from '#core/logger'
+import type {
+  Duration, Tick, SimulationContext,
+  ReadonlySimulationState, StateCommands, EntityInput,
+} from '#core/types'
+import type { LearnedSkill } from '#agency/types'
+import type { CognitiveBus, CognitiveEvent } from '#cognition/bus'
+import type { CognitiveEngine, EngineResult } from '#cognition/types'
+import type { CognitiveEventSchema } from '#cognition/schema.registry'
+import type { SchemaRepertoire } from '#agency/schemas/repertoire'
+import { schemaEntityId } from '#agency/schemas/repertoire'
+
+const PROC_THRESHOLD = 0.60   // mirror of repertoire's threshold for the habitual-count metric
+
+export class ReafferenceEngine implements CognitiveEngine {
+  readonly name = 'reafference'
+
+  private _repertoire: SchemaRepertoire
+  private _bus: CognitiveBus | null = null
+
+  constructor( repertoire: SchemaRepertoire ){ this._repertoire = repertoire }
+
+  attachBus( bus: CognitiveBus ): void { this._bus = bus }
+
+  publishes(): CognitiveEventSchema[] {
+    return [
+      { type: 'agency.skill.proceduralized', version: 1, validate: () => null },
+      { type: 'agency.schema.discovered',    version: 1, validate: () => null },
+      // Async-acked outcomes (host-ack reconciliation) flow through here, not the
+      // executor — so for a plan-tagged reconciled outcome this engine emits the
+      // action.outcome the PlanningEngine advances on. (The executor is the emitter
+      // for sync/timeout outcomes; this is its async counterpart — one emitter each.)
+      { type: 'action.outcome',              version: 1, validate: () => null },
+    ]
+  }
+  /** Creation seam: register a composite proposed by the executive/deliberation facet. */
+  subscribes(): string[] { return [ 'agency.composite.proposed' ] }
+  onCognitiveEvent( e: CognitiveEvent ): void {
+    if( e.type !== 'agency.composite.proposed' ) return
+    const p = e.payload as { id?: string; name?: string; composedOf?: unknown; tags?: unknown; cost?: number }
+    const id    = p.id ?? p.name
+    const steps = Array.isArray( p.composedOf )
+      ? ( p.composedOf as unknown[] ).filter( ( s ): s is string => typeof s === 'string' )
+      : []
+    if( !id || steps.length < 2 ) return   // a composite needs a name + ≥2 sub-schemas
+
+    this._repertoire.registerComposite({
+      id, kind: 'composite', source: 'repertoire', binds: 'none',
+      cost: typeof p.cost === 'number' ? p.cost : 0.1,
+      composedOf: steps,
+      tags: Array.isArray( p.tags ) ? ( p.tags as unknown[] ).filter( ( t ): t is string => typeof t === 'string' ) : [ 'composite' ],
+    })
+    logger.info( `[reafference] registered proposed composite "${ id }" (${ steps.join( ' → ' ) })` )
+  }
+  snapshot(): Record<string, unknown> {
+    return { skills: this._repertoire.skills().size }
+  }
+
+  async react(
+    _delta:   Duration,
+    tick:     Tick,
+    state:    ReadonlySimulationState,
+    _context: SimulationContext,
+  ): Promise<EngineResult> {
+    const set:     EntityInput[]            = []
+    const del:     string[]                = []
+    const metrics: Array<[ string, number ]> = []
+
+    // ── 1. Fold each new outcome into its skill ──────────────────
+    let updates    = 0
+    let discovered = 0
+    for( const [ id, e ] of state.entities ){
+      if( e.type !== 'agency.outcome' ) continue
+      const m = ( e.metadata ?? {} ) as Record<string, unknown>
+      const schema = str( m['schema'] )
+      if( !schema ){ del.push( id ); continue }
+
+      const { skill, proceduralized } = this._repertoire.recordOutcome({
+        schema,
+        success:         m['success'] === true,
+        outcomeQuality:  num( m['outcomeQuality'],  0 ),
+        predictedReward: num( m['predictedReward'], 0.5 ),
+        params:          ( m['params'] as Record<string, unknown> ) ?? undefined,
+        tick,
+      })
+
+      set.push( skillEntity( skill ) )
+      del.push( id )                       // outcome consumed
+      // Host-ack reconciliation: a reconciled outcome carries the awaiting intent's
+      // id — free it so the serial Will can act again. The executor's own sync
+      // outcomes already deleted their intent, so this is a harmless no-op there.
+      const intentId = str( m['intentId'] )
+      if( intentId ) del.push( intentId )
+      updates++
+
+      // Plan advancement for the async path: a host-acked outcome that carries plan
+      // provenance is the ONLY signal the PlanningEngine will get (the executor never
+      // saw the ack — the intent was 'awaiting'). Emit the action.outcome it advances
+      // on. Sync/timeout outcomes never carry planId here (the executor emitted their
+      // action.outcome already), so this never double-advances.
+      const planId = str( m['planId'] )
+      if( planId )
+        this._emitPlanOutcome( planId, str( m['stepId'] ), schema, m['success'] === true, num( m['outcomeQuality'], 0 ), num( m['surprise'], 0 ), tick )
+
+      // Discovery: the first time the Will enacts a schema, it becomes a known part
+      // of its repertoire (the new model's "discovered" — earned by doing, not catalogued).
+      if( skill.enactments === 1 ){
+        discovered++
+        this._emitDiscovered( schema, tick )
+      }
+
+      if( proceduralized ){
+        this._emitProceduralized( skill, tick )
+        logger.info( `[reafference] "${ schema }" proceduralized (habit ${ skill.habitStrength.toFixed( 2 ) })` )
+      }
+    }
+
+    // ── 2. Forgetting curve over the competence layer ────────────
+    const dropped = this._repertoire.decay( tick )
+    for( const id of dropped ){
+      del.push( `agency-skill-${ id }` )
+      del.push( schemaEntityId( id ) )   // composite mirror (harmless no-op for primitives)
+    }
+
+    // ── 3. Mirror learned composite templates ────────────────────
+    // Skills become `agency.skill` (above); the invented composite *definitions*
+    // must travel too, or a snapshot/restore brings back a skill whose schema is
+    // gone and the executor can't expand it. Idempotent re-write each tick, like
+    // GoalManager._persistGoals. Empty until a composite is actually learned.
+    for( const e of this._repertoire.compositeEntities() ) set.push( e )
+
+    // ── 4. Telemetry ─────────────────────────────────────────────
+    const skills    = this._repertoire.skills()
+    const habitual  = [ ...skills.values() ].filter( s => s.habitStrength >= PROC_THRESHOLD ).length
+    metrics.push(
+      [ 'agency.learning.updates', updates ],
+      [ 'agency.discovered.count', discovered ],
+      [ 'agency.skill.count',      skills.size ],
+      [ 'agency.habitual.count',   habitual ],
+    )
+
+    return { commands: { set, delete: del, metrics } }
+  }
+
+  private _emitProceduralized( skill: LearnedSkill, tick: Tick ): void {
+    if( !this._bus ) return
+    try {
+      this._bus.publish({
+        type: 'agency.skill.proceduralized', version: 1, sourceEngine: this.name,
+        salience: 0.6,
+        payload: { schema: skill.schema, habitStrength: skill.habitStrength, tick },
+      })
+    }
+    catch( err ){ logger.warn( `[reafference] publish failed: ${ err instanceof Error ? err.message : String( err ) }` ) }
+  }
+
+  /**
+   * Emit the `action.outcome{planId,stepId}` for an async (host-acked) plan-step
+   * enaction. Mirrors the executor's `_emitActionOutcome` payload so the
+   * PlanningEngine's consumer can't tell which path produced it.
+   */
+  private _emitPlanOutcome(
+    planId: string, stepId: string | undefined, schema: string,
+    success: boolean, outcomeQuality: number, surprise: number, tick: Tick,
+  ): void {
+    if( !this._bus ) return
+    try {
+      this._bus.publish({
+        type: 'action.outcome', version: 1, sourceEngine: this.name,
+        salience: Math.min( 1, outcomeQuality * 0.6 ),
+        payload: {
+          actionType: schema, domain: schema, success, outcomeQuality, surprise,
+          description: success ? 'The world confirmed the action.' : 'The world rejected the action.',
+          planId,
+          ...( stepId ? { stepId } : {} ),
+          tick,
+        },
+      })
+    }
+    catch( err ){ logger.warn( `[reafference] plan outcome publish failed: ${ err instanceof Error ? err.message : String( err ) }` ) }
+  }
+
+  private _emitDiscovered( schema: string, tick: Tick ): void {
+    if( !this._bus ) return
+    try {
+      this._bus.publish({
+        type: 'agency.schema.discovered', version: 1, sourceEngine: this.name,
+        salience: 0.5, payload: { schema, tick },
+      })
+    }
+    catch( err ){ logger.warn( `[reafference] discovered publish failed: ${ err instanceof Error ? err.message : String( err ) }` ) }
+  }
+}
+
+// ─── entity mirroring ────────────────────────────────────────────────────────
+
+function skillEntity( s: LearnedSkill ): EntityInput {
+  return {
+    id: `agency-skill-${ s.schema }`,
+    type: 'agency.skill',
+    metadata: {
+      schema:             s.schema,
+      habitStrength:      s.habitStrength,
+      valueEstimate:      s.valueEstimate,
+      paramPriors:        s.paramPriors,
+      enactments:         s.enactments,
+      successes:          s.successes,
+      avgPredictionError: s.avgPredictionError,
+      lastEnactedTick:    s.lastEnactedTick,
+    },
+  }
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+function str( v: unknown ): string | undefined {
+  return typeof v === 'string' ? v : undefined
+}
+function num( v: unknown, fallback: number ): number {
+  return typeof v === 'number' && Number.isFinite( v ) ? v : fallback
+}

package/src/cognition/agency/execution.primitives.ts

@@ -0,0 +1,118 @@
+// ─────────────────────────────────────────────────────────────
+// src/agency/execution.primitives.ts  —  the bodies of primitive schemas
+// ─────────────────────────────────────────────────────────────
+//
+// A primitive schema's "body" is what actually happens when it is enacted.
+// Three execution modes:
+//
+//   • sync        — internal stances (orient, rest, reflect, …) resolve this
+//                   tick. Following the original "attentional directive" insight,
+//                   these are reportorial: they yield an honest outcome grounded
+//                   in body state and DO NOT directly mutate regulated metrics
+//                   (energy/stress are owned by the regulators — we don't fight
+//                   them). Wiring stance→regulator signals is a later concern.
+//   • communicate — an outward message; dispatched now, confirmed later (async).
+//   • external    — a host-owned effector; emitted now, acked later (async).
+//
+// Composite schemas never reach here — the executor expands them into ordered
+// primitive sub-intents.
+// ─────────────────────────────────────────────────────────────
+
+import type { MotorSchema } from '#agency/types'
+
+export type EnactionMode = 'sync' | 'communicate' | 'external'
+
+export interface Enaction {
+  mode:           EnactionMode
+  success:        boolean
+  /** 0..1 actual outcome quality (provisional for async — refined on reconciliation). */
+  outcomeQuality: number
+  /** −1..1 actual felt valence of the outcome. */
+  valence:        number
+  description:    string
+  /** Minimal, non-regulated metric nudges this stance legitimately owns. */
+  metricDeltas?:  Array<[ string, number ]>
+}
+
+export interface EnactionContext {
+  schema:          MotorSchema
+  parameters:      Record<string, unknown>
+  targetEntityId?: string
+  energy:          number   // 0..100
+  stress:          number   // 0..100
+}
+
+const COMM_SCHEMAS = new Set([ 'reach-out', 'talk', 'text', 'broadcast', 'gesture' ])
+
+/** Classify how a primitive schema executes. */
+export function modeOf( schema: MotorSchema ): EnactionMode {
+  if( schema.tags?.includes( 'external' ) ) return 'external'
+  if( schema.tags?.includes( 'communication' ) || COMM_SCHEMAS.has( schema.id ) ) return 'communicate'
+  return 'sync'
+}
+
+/** Enact a primitive schema, producing a state-grounded outcome. */
+export function enact( ctx: EnactionContext ): Enaction {
+  const mode = modeOf( ctx.schema )
+
+  if( mode === 'communicate' ){
+    const name = str( ctx.parameters['targetEntityName'] ) ?? ctx.targetEntityId ?? 'them'
+    return {
+      mode, success: true, outcomeQuality: 0.7, valence: 0.1,
+      description: `You reach toward ${ name }. The words are sent; their effect is not yet known.`,
+    }
+  }
+
+  if( mode === 'external' )
+    return {
+      mode, success: true, outcomeQuality: 0.5, valence: 0,
+      description: `"${ ctx.schema.id }" dispatched to the host; awaiting the world's reply.`,
+    }
+
+  return syncStance( ctx )
+}
+
+// ── sync stance bodies ───────────────────────────────────────────────────────
+
+function syncStance( ctx: EnactionContext ): Enaction {
+  const { schema, parameters, energy, stress } = ctx
+  const e01 = clamp01( energy / 100 )
+  const s01 = clamp01( stress / 100 )
+
+  switch( schema.id ){
+    case 'rest':
+      // More restorative the more depleted you were.
+      return sync( 0.5 + ( 1 - e01 ) * 0.4, 0.15, 'You let yourself recover; the pressure eases a little.' )
+    case 'withdraw':
+      return sync( 0.5 + s01 * 0.3, 0.05 + s01 * 0.1, 'You pull back from the press of things; the world quietens.' )
+    case 'reflect':
+      return sync( 0.6, 0.05, 'You turn inward; patterns from recent events settle into place.' )
+    case 'attend':
+      return sync( 0.6, 0.0, 'You concentrate, mobilizing more of your attention.' )
+    case 'orient':
+      return sync( 0.5, 0.0, 'Your awareness sweeps the situation, taking its measure.' )
+    case 'wait':
+      return sync( 0.5, 0.0, 'You let time pass; regulatory processes continue their quiet work.' )
+    case 'express':
+      return sync( 0.6, 0.1, 'Your inner state becomes outwardly visible.' )
+    case 'inspect': {
+      const focus = str( parameters['focus'] ) ?? 'it'
+      return sync( 0.65, 0.05, `You examine ${ focus } closely; more of its detail resolves.` )
+    }
+    default:
+      return sync( 0.5, 0.0, `You enact ${ schema.id }.` )
+  }
+}
+
+function sync( outcomeQuality: number, valence: number, description: string ): Enaction {
+  return { mode: 'sync', success: true, outcomeQuality: clamp01( outcomeQuality ), valence, description }
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+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/index.ts

@@ -0,0 +1,58 @@
+// ─────────────────────────────────────────────────────────────
+// src/engines/agency/index.ts  —  agency pipeline barrel
+// ─────────────────────────────────────────────────────────────
+//
+// The mind-like action layer: perception synthesizes a field of affordances, a
+// biased competition selects one (recruiting the LLM only when ambiguous or
+// high-stakes), the executor enacts it (running learned composites for real),
+// and reafference turns outcomes into competence that proceduralizes and travels
+// in the PMA. See AGENCY_PIPELINE_TODO.md.
+
+export * from '#agency/types'
+
+export { INNATE_SCHEMAS, INNATE_SCHEMA_BY_ID } from '#agency/schemas/innate'
+export { externalSchemas } from '#agency/schemas/external'
+export { SchemaRepertoire } from '#agency/schemas/repertoire'
+export type { OutcomeObservation } from '#agency/schemas/repertoire'
+
+export { AffordanceSynthesizer } from '#agency/engines/affordance.synthesizer'
+
+export { ActionSelector } from '#agency/engines/action.selector'
+export {
+  DeliberationEngine,
+  type DeliberationFacetProvider
+} from '#agency/engines/deliberation.engine'
+export {
+  scoreAffordance,
+  competitionEntropy,
+  stakes,
+  goalRelevance,
+  driveUrgency,
+  novelty,
+  risk,
+  DEFAULT_WEIGHTS, DEFAULT_TEMPERATURE,
+  type BiasContext,
+  type ScoreWeights,
+} from '#agency/selection.scoring'
+
+export { MotorSchemaExecutor } from '#agency/engines/motor.schema.executor'
+export { 
+  enact,
+  modeOf,
+  type Enaction,
+  type EnactionMode
+} from '#agency/execution.primitives'
+
+export { ReafferenceEngine } from '#agency/engines/reafference.engine'
+export {
+  reconcileInvocation,
+  type HostAckResult
+} from '#agency/reconcile.learning'
+
+export { AccessGrants, EXPLICIT_EFFECTORS } from '#agency/access.grants'
+
+export {
+  distillCompetence, loadCompetence, COMPETENCE_SCHEMA_VERSION,
+  type CompetenceSnapshot,
+  type DistillOptions,
+} from '#agency/competence.codec'