@mindot/will 0.1.0

package/src/cognition/agency/schemas/repertoire.ts

@@ -0,0 +1,246 @@
+// ─────────────────────────────────────────────────────────────
+// src/agency/schemas/repertoire.ts  —  the store of what the Will can do
+// ─────────────────────────────────────────────────────────────
+//
+// The repertoire holds two things: the schema TEMPLATES the Will can enact
+// (innate floor + learned composites) and the per-schema LearnedSkill stats that
+// accrete from experience. It is the competence layer — the part of a Will that
+// makes it *act like itself*, and the part the PMA must carry across re-embodiment
+// (Phase 6). It is an in-memory manager (like GoalManager); the ReafferenceEngine
+// mirrors per-schema skills into `agency.skill` state entities AND learned
+// composite templates into `agency.schema` entities, so both survive a
+// snapshot/restore. The skills carry habit/value; the composites carry the
+// invented multi-step *programs* the executor must resolve to run a macro.
+// restoreComposites() rehydrates those templates after a restore reconstructs
+// the repertoire innate-only — analogous to GoalManager rehydrating `goal`s.
+//
+// Learning rules (the proceduralization curve):
+//   valueEstimate  — EMA toward observed outcome quality
+//   habitStrength  — rises only on CONFIDENT success (low prediction error);
+//                    a surprising or failed outcome erodes it. This is the
+//                    instrumental→habitual gradient: an action becomes a habit
+//                    by working reliably AND predictably, not merely often.
+//   avgPredictionError — EMA of |predicted − actual|; the destabilizer
+//   paramPriors    — last known-good parameters become defaults
+// ─────────────────────────────────────────────────────────────
+
+import type { MotorSchema, LearnedSkill } from '#agency/types'
+import type { EntityInput, ReadonlySimulationState } from '#core/types'
+import { INNATE_SCHEMAS } from '#agency/schemas/innate'
+
+const VALUE_ALPHA       = 0.2   // value EMA rate
+const ERROR_BETA        = 0.2   // prediction-error EMA rate
+const HABIT_GAIN        = 0.12  // habit growth on confident success
+const HABIT_FAIL_DECAY  = 0.10  // habit erosion on surprise / failure
+const CONFIDENT_ERROR   = 0.30  // prediction error below this counts as "predictable"
+const PROC_THRESHOLD    = 0.60  // habit at/above this is "proceduralized"
+
+const IDLE_TICKS        = 200   // ticks of disuse before forgetting starts
+const DECAY_RATE        = 0.02  // habit lost per decay application
+const DROP_HABIT        = 0.05  // below this (and learned) the skill is forgotten
+
+export interface OutcomeObservation {
+  schema:         string
+  success:        boolean
+  outcomeQuality: number
+  predictedReward: number
+  /** Last-known-good parameters to fold into priors (only kept on success). */
+  params?:        Record<string, unknown>
+  tick:           number
+}
+
+export class SchemaRepertoire {
+  private _templates = new Map<string, MotorSchema>()
+  private _skills    = new Map<string, LearnedSkill>()
+  /** Tracks which templates were learned at runtime (vs innate) so decay can forget them. */
+  private _learned   = new Set<string>()
+
+  constructor( seed: MotorSchema[] = INNATE_SCHEMAS ){
+    for( const s of seed ) this._templates.set( s.id, s )
+  }
+
+  // ── templates ─────────────────────────────────────────────────
+  schemas(): MotorSchema[] { return [ ...this._templates.values() ] }
+  getSchema( id: string ): MotorSchema | undefined { return this._templates.get( id ) }
+
+  /** Register a learned composite skill template (starts with no habit). */
+  registerComposite( schema: MotorSchema ): void {
+    this._templates.set( schema.id, schema )
+    this._learned.add( schema.id )
+    if( !this._skills.has( schema.id ) )
+      this._skills.set( schema.id, freshSkill( schema.id, 0.4, 0 ) )
+  }
+
+  // ── skills ────────────────────────────────────────────────────
+  skills(): ReadonlyMap<string, LearnedSkill> { return this._skills }
+  getSkill( id: string ): LearnedSkill | undefined { return this._skills.get( id ) }
+
+  /**
+   * Fold one outcome into the schema's learned skill. Returns the updated skill
+   * and whether it just crossed the proceduralization threshold this update.
+   */
+  recordOutcome( o: OutcomeObservation ): { skill: LearnedSkill; proceduralized: boolean } {
+    const prior = this._skills.get( o.schema ) ?? freshSkill( o.schema, o.predictedReward, o.tick )
+    const wasProceduralized = prior.habitStrength >= PROC_THRESHOLD
+
+    const error     = clamp01( Math.abs( o.predictedReward - o.outcomeQuality ) )
+    const confident = o.success && error < CONFIDENT_ERROR
+
+    const habitStrength = clamp01(
+      confident
+        ? prior.habitStrength + HABIT_GAIN * ( 1 - prior.habitStrength )
+        : prior.habitStrength - HABIT_FAIL_DECAY * prior.habitStrength,
+    )
+
+    const skill: LearnedSkill = {
+      schema:             o.schema,
+      habitStrength,
+      valueEstimate:      clamp01( prior.valueEstimate + VALUE_ALPHA * ( o.outcomeQuality - prior.valueEstimate ) ),
+      paramPriors:        o.success && o.params ? { ...prior.paramPriors, ...o.params } : prior.paramPriors,
+      enactments:         prior.enactments + 1,
+      successes:          prior.successes + ( o.success ? 1 : 0 ),
+      avgPredictionError: prior.avgPredictionError + ERROR_BETA * ( error - prior.avgPredictionError ),
+      lastEnactedTick:    o.tick,
+    }
+
+    this._skills.set( o.schema, skill )
+    return { skill, proceduralized: !wasProceduralized && habitStrength >= PROC_THRESHOLD }
+  }
+
+  /**
+   * Forgetting curve over the competence layer. Skills unused for IDLE_TICKS
+   * lose habit; learned composites that fall below DROP_HABIT are dropped
+   * entirely (template + skill). Returns the schema ids that were forgotten.
+   */
+  decay( tick: number ): string[] {
+    const dropped: string[] = []
+    for( const [ id, skill ] of this._skills ){
+      if( tick - skill.lastEnactedTick <= IDLE_TICKS ) continue
+
+      const habitStrength = clamp01( skill.habitStrength - DECAY_RATE )
+      if( this._learned.has( id ) && habitStrength < DROP_HABIT ){
+        this._skills.delete( id )
+        this._templates.delete( id )
+        this._learned.delete( id )
+        dropped.push( id )
+        continue
+      }
+      this._skills.set( id, { ...skill, habitStrength } )
+    }
+    return dropped
+  }
+
+  // ── PMA portability (Phase 6 reads these) ─────────────────────
+  /** Learned composite templates + all skills above a confidence floor. */
+  export( minHabit = 0.0 ): { composites: MotorSchema[]; skills: LearnedSkill[] } {
+    return {
+      composites: [ ...this._learned ].map( id => this._templates.get( id ) ).filter( ( s ): s is MotorSchema => !!s ),
+      skills:     [ ...this._skills.values() ].filter( s => s.habitStrength >= minHabit ),
+    }
+  }
+
+  import( data: { composites?: MotorSchema[]; skills?: LearnedSkill[] } ): void {
+    for( const c of data.composites ?? [] ){ this._templates.set( c.id, c ); this._learned.add( c.id ) }
+    for( const s of data.skills ?? [] ) this._skills.set( s.schema, s )
+  }
+
+  // ── snapshot / replay portability (deterministic state path) ──
+  // Skills mirror to `agency.skill`; the invented composite *definitions* must
+  // travel too, or a snapshot/restore brings back an `agency.skill` whose schema
+  // is gone and the MotorSchemaExecutor can't expand it (it misroutes the intent
+  // to the host and times out). compositeEntities() is the write side (the
+  // ReafferenceEngine pushes these each tick); restoreComposites() is the read
+  // side, called from the first agency engine after a restore.
+
+  /** Learned composite templates encoded as `agency.schema` state entities. */
+  compositeEntities(): EntityInput[] {
+    const out: EntityInput[] = []
+    for( const id of this._learned ){
+      const s = this._templates.get( id )
+      if( s && s.kind === 'composite' ) out.push( schemaEntity( s ) )
+    }
+    return out
+  }
+
+  /**
+   * Re-register learned composites from `agency.schema` state entities after a
+   * restore rebuilt the repertoire innate-only. Idempotent — skips composites
+   * already present and never seeds a fresh skill (the restored `agency.skill`
+   * entity and future outcomes own the habit; seeding here would reset it).
+   * Mirrors GoalManager._syncFromStateGoals.
+   */
+  restoreComposites( entities: ReadonlySimulationState['entities'] ): void {
+    for( const e of entities.values() ){
+      if( e.type !== SCHEMA_ENTITY_TYPE ) continue
+      const s = readSchema( e.metadata as Record<string, unknown> | undefined )
+      if( !s || this._templates.has( s.id ) ) continue
+      this._templates.set( s.id, s )
+      this._learned.add( s.id )
+    }
+  }
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+function freshSkill( schema: string, value: number, tick: number ): LearnedSkill {
+  return {
+    schema,
+    habitStrength:      0,
+    valueEstimate:      clamp01( value ),
+    paramPriors:        {},
+    enactments:         0,
+    successes:          0,
+    avgPredictionError: 0,
+    lastEnactedTick:    tick,
+  }
+}
+
+function clamp01( n: number ): number {
+  return n < 0 ? 0 : n > 1 ? 1 : n
+}
+
+// ─── composite ⇄ state-entity codec (snapshot/replay) ────────────────────────
+
+/** State-entity type for a mirrored composite template. */
+export const SCHEMA_ENTITY_TYPE = 'agency.schema'
+
+/** Stable entity id for a schema's mirror (no timestamp → idempotent re-writes). */
+export function schemaEntityId( schemaId: string ): string { return `agency-schema-${ schemaId }` }
+
+/** Encode a composite template as a state entity (round-trips via readSchema). */
+function schemaEntity( s: MotorSchema ): EntityInput {
+  return {
+    id:   schemaEntityId( s.id ),
+    type: SCHEMA_ENTITY_TYPE,
+    metadata: {
+      id:            s.id,
+      kind:          s.kind,
+      source:        s.source,
+      cost:          s.cost,
+      binds:         s.binds,
+      preconditions: s.preconditions,
+      composedOf:    s.composedOf,
+      baseValence:   s.baseValence,
+      tags:          s.tags,
+    },
+  }
+}
+
+/** Decode a mirrored schema entity back into a MotorSchema (undefined if malformed). */
+function readSchema( m: Record<string, unknown> | undefined ): MotorSchema | undefined {
+  const meta = m ?? {}
+  const id   = typeof meta['id'] === 'string' ? meta['id'] as string : undefined
+  const kind = meta['kind']
+  if( !id || ( kind !== 'composite' && kind !== 'primitive' ) ) return undefined
+  return {
+    id,
+    kind,
+    source:        ( meta['source'] as MotorSchema['source'] ) ?? 'repertoire',
+    cost:          typeof meta['cost'] === 'number' ? meta['cost'] as number : 0,
+    binds:         ( meta['binds'] as MotorSchema['binds'] ) ?? 'none',
+    preconditions: meta['preconditions'] as MotorSchema['preconditions'],
+    composedOf:    Array.isArray( meta['composedOf'] ) ? meta['composedOf'] as string[] : undefined,
+    baseValence:   typeof meta['baseValence'] === 'number' ? meta['baseValence'] as number : undefined,
+    tags:          Array.isArray( meta['tags'] ) ? meta['tags'] as string[] : undefined,
+  }
+}

package/src/cognition/agency/selection.scoring.ts

@@ -0,0 +1,191 @@
+// ─────────────────────────────────────────────────────────────
+// src/agency/selection.scoring.ts  —  the competition's activation function
+// ─────────────────────────────────────────────────────────────
+//
+// A mind does not pick a tool off a menu; affordances *compete*, and the
+// competition is biased by what the body needs, what it wants, what it has
+// learned, and what it fears. This is the basal-ganglia Go/NoGo arithmetic,
+// kept pure so it is trivially testable and replay-deterministic.
+//
+//   activation = goalRelevance + expectedReward + novelty + driveUrgency
+//              + habitStrength·W                              (additive habit bonus)
+//              + planBias·W                                   (top-down prior)
+//              − cost − inhibition − risk
+//
+// The habit term is additive (per design decision): an overlearned schema wins
+// cheaply AND lowers its own deliberation threshold (see selector.ts), which is
+// how the instrumental→habitual gradient cashes out as falling LLM spend.
+// ─────────────────────────────────────────────────────────────
+
+import type { Affordance } from '#agency/types'
+import type { ReadonlySimulationState } from '#core/types'
+
+/** Bias signals assembled from live state + the cognitive bus each tick. */
+export interface BiasContext {
+  /** Entity ids that an active goal is directed at. */
+  goalTargets:  ReadonlySet<string>
+  /** Priority of the highest-priority active goal (0..1). */
+  maxGoalPriority: number
+  /** Homeostatic drive pressures, each 0..1 (0 = satisfied). */
+  drives:       { energy: number; sleep: number; stress: number; social: number }
+  /** Ambient threat 0..1. */
+  threat:       number
+  /** Global NoGo pressure 0..1 from the InhibitionController. */
+  inhibition:   number
+}
+
+export interface ScoreWeights {
+  goal:    number
+  reward:  number
+  novelty: number
+  drive:   number
+  habit:   number
+  /** Top-down planning prior — how strongly an executing plan biases the competition. */
+  plan:    number
+  cost:    number
+  inhib:   number
+  risk:    number
+}
+
+export const DEFAULT_WEIGHTS: ScoreWeights = {
+  goal:    0.30,
+  reward:  0.25,
+  novelty: 0.10,
+  drive:   0.25,
+  habit:   0.20,
+  plan:    0.30,
+  cost:    0.20,
+  inhib:   0.30,
+  risk:    0.20,
+}
+
+/**
+ * Decision temperature for the entropy softmax. Activations live in a narrow
+ * band (~0..1), so a low temperature is needed for a real activation gap to read
+ * as a confident winner rather than near-uniform noise. Lower = sharper / more
+ * decisive; this is the knob a future arousal signal would modulate.
+ */
+export const DEFAULT_TEMPERATURE = 0.15
+
+/**
+ * Active-goal targets → the highest priority directed at each entity. Relevance is
+ * structural (target match), never lexical: a goal links to an entity EITHER via
+ * its `targetEntityId`/`requestingEntityId` metadata OR via a `keid:<id>` tag —
+ * the convention KnownEntityTracker uses for the curiosity goals it forms. Shared
+ * by the synthesizer (to lift goal-relevant affordances at the attention cap) and
+ * the selector (to score goalRelevance), so both stages see the same links.
+ */
+export function collectGoalTargets( state: ReadonlySimulationState ): Map<string, number> {
+  const targets = new Map<string, number>()
+  for( const e of state.entities.values() ){
+    if( e.type !== 'goal' ) continue
+    const m = e.metadata as Record<string, unknown> | undefined
+    const status = typeof m?.['status'] === 'string' ? m['status'] : undefined
+    if( status !== 'active' && status !== 'in_progress' ) continue
+    const priority = typeof m?.['priority'] === 'number' ? m['priority'] as number : 0
+    const link = ( id: unknown ): void => {
+      if( typeof id !== 'string' || !id ) return
+      targets.set( id, Math.max( targets.get( id ) ?? 0, priority ) )
+    }
+    link( m?.['targetEntityId'] )
+    link( m?.['requestingEntityId'] )
+    if( Array.isArray( m?.['tags'] ) )
+      for( const t of m['tags'] as unknown[] )
+        if( typeof t === 'string' && t.startsWith( 'keid:' ) ) link( t.slice( 5 ) )
+  }
+  return targets
+}
+
+/** Goal relevance: structural (target match), not lexical. 0 when the affordance has no goal-linked target. */
+export function goalRelevance( a: Affordance, bias: BiasContext ): number {
+  if( a.targetEntityId && bias.goalTargets.has( a.targetEntityId ) )
+    return bias.maxGoalPriority
+  return 0
+}
+
+/** Homeostatic urgency routed to the affordance by its schema tags. */
+export function driveUrgency( a: Affordance, bias: BiasContext ): number {
+  const t = a.tags
+  if( t.includes( 'regulatory' ) || t.includes( 'self-care' ) || t.includes( 'rest' ) )
+    return Math.max( bias.drives.energy, bias.drives.sleep )
+  if( t.includes( 'social' ) )
+    return bias.drives.social
+  if( t.includes( 'self-protection' ) )
+    return Math.max( bias.drives.stress, bias.threat )
+  return 0
+}
+
+/** Curiosity pull toward the unpracticed — proxied by the inverse of habit until a novelty engine feeds in. */
+export function novelty( a: Affordance ): number {
+  return clamp01( 1 - a.habitStrength )
+}
+
+/** Risk from anticipated negative affect and ambient threat. */
+export function risk( a: Affordance, bias: BiasContext ): number {
+  return clamp01( Math.max( 0, -a.expectedValence ) * 0.5 + bias.threat * 0.5 )
+}
+
+/** Full competition activation for one affordance. */
+export function scoreAffordance(
+  a:    Affordance,
+  bias: BiasContext,
+  w:    ScoreWeights = DEFAULT_WEIGHTS,
+): number {
+  return (
+      w.goal    * goalRelevance( a, bias )
+    + w.reward  * a.expectedReward
+    + w.novelty * novelty( a )
+    + w.drive   * driveUrgency( a, bias )
+    + w.habit   * a.habitStrength
+    + w.plan    * ( a.planBias ?? 0 )
+    - w.cost    * a.cost
+    - w.inhib   * bias.inhibition
+    - w.risk    * risk( a, bias )
+  )
+}
+
+/**
+ * Stakes of committing to `winner` — how consequential the leading choice is.
+ * High stakes recruit deliberation even when the field is not ambiguous.
+ */
+export function stakes( winner: Affordance, bias: BiasContext ): number {
+  // Consequence, not unfamiliarity: ambient threat and the affective charge of
+  // the leading choice dominate. Novelty contributes only weakly — a brand-new
+  // schema is novel (1) but that alone should not force the LLM on every action
+  // before any habit has formed; curiosity already lives in the activation.
+  return clamp01( Math.max(
+    bias.threat,
+    Math.abs( winner.expectedValence ),
+    novelty( winner ) * 0.5,
+  ) )
+}
+
+/**
+ * Normalized competition entropy (0..1). 0 = a single dominant winner; 1 = a
+ * flat field with no clear choice. Softmax over activations, Shannon-normalized
+ * by log(n). This is the ambiguity signal that recruits the executive.
+ */
+export function competitionEntropy(
+  activations: number[],
+  temperature: number = DEFAULT_TEMPERATURE,
+): number {
+  const n = activations.length
+  if( n <= 1 ) return 0
+
+  const t    = temperature > 0 ? temperature : DEFAULT_TEMPERATURE
+  const max  = Math.max( ...activations )
+  const exps = activations.map( a => Math.exp( ( a - max ) / t ) )
+  const sum  = exps.reduce( ( s, e ) => s + e, 0 )
+  if( sum === 0 ) return 1
+
+  let h = 0
+  for( const e of exps ){
+    const p = e / sum
+    if( p > 0 ) h -= p * Math.log( p )
+  }
+  return clamp01( h / Math.log( n ) )
+}
+
+function clamp01( n: number ): number {
+  return n < 0 ? 0 : n > 1 ? 1 : n
+}

package/src/cognition/agency/types.ts

@@ -0,0 +1,165 @@
+// ─────────────────────────────────────────────────────────────
+// src/agency/types.ts  —  core contracts for the agency pipeline
+// ─────────────────────────────────────────────────────────────
+//
+// The vocabulary of a mind that *finds* its actions in the situation rather
+// than looking them up in a catalog. An Affordance is a possibility the current
+// state affords; a MotorSchema is the control program that would enact it; a
+// LearnedSkill is what the Will has accreted about running that schema; a
+// SchemaOutcome is the reafference that teaches it. Nothing here owns behaviour —
+// these are the stable nouns every agency engine references.
+//
+// See AGENCY_PIPELINE_TODO.md for the end-to-end design.
+// ─────────────────────────────────────────────────────────────
+
+/** Where an affordance came from — its evoking origin in the perception field. */
+export type AffordanceSource =
+  | 'innate'      // always-on floor; needs no object (orient, rest, reflect, wait)
+  | 'perceptual'  // evoked by a salient percept (inspect this, attend to that)
+  | 'social'      // evoked by a known sentient entity (reach out to them)
+  | 'repertoire'  // a learned composite skill whose trigger matches now
+  | 'ideomotor'   // pre-activated by the executive imagining the outcome
+  | 'plan'        // pre-activated by an executing plan's current frontier step (top-down prior)
+  | 'external'    // a host-owned domain effector (move, attack, trade …) dispatched to the world
+
+/** A body-state gate. If any precondition fails, the affordance is unavailable. */
+export interface SchemaPrecondition {
+  metric: string
+  op:     'gt' | 'lt' | 'gte' | 'lte' | 'eq'
+  value:  number
+}
+
+/** What kind of target a schema binds when it becomes an affordance. */
+export type SchemaBinding = 'none' | 'entity' | 'percept'
+
+/**
+ * A MotorSchema — a parameterized control program, not a flat effector row.
+ * `kind: 'primitive'` runs a body directly (an internal stance, a communication,
+ * or an external host invocation). `kind: 'composite'` expands into an ordered
+ * policy over sub-schemas (this is where a *created* skill actually executes).
+ */
+export interface MotorSchema {
+  id:            string
+  kind:          'primitive' | 'composite'
+  source:        AffordanceSource
+  /** Normalized intrinsic cost 0..1 (effort / energy demand). */
+  cost:          number
+  /** What this schema binds to when afforded. */
+  binds:         SchemaBinding
+  /** Body-state gates evaluated against live metrics. */
+  preconditions?: SchemaPrecondition[]
+  /** Sub-schema ids, in policy order — composite schemas only. */
+  composedOf?:   string[]
+  /** Intrinsic affective prior (−1..1) before any learning has occurred. */
+  baseValence?:  number
+  tags?:         string[]
+}
+
+/**
+ * An Affordance — a possibility the current state affords *for this body now*,
+ * with its parameters already bound from the thing that evoked it. Parameters
+ * are never separated from the situation that supplies them, so there is no
+ * "empty params" failure mode. Affordances are transient: the field is rebuilt
+ * every tick from live perception.
+ */
+export interface Affordance {
+  id:              string
+  /** The MotorSchema this would enact. */
+  schema:          string
+  source:          AffordanceSource
+  /** Parameters bound from the evoking context (e.g. focus text, target name). */
+  parameters:      Record<string, unknown>
+  /** Bound target entity id, when the schema binds an entity. */
+  targetEntityId?: string
+  /** Entity id of the percept / known-entity that evoked this (provenance). */
+  evokedBy?:       string
+  /** Anticipated affective outcome −1..1 (learned, falling back to schema prior). */
+  expectedValence: number
+  /** Learned value estimate 0..1 for this schema in like contexts. */
+  expectedReward:  number
+  /** Normalized cost 0..1 in the current body state. */
+  cost:            number
+  /** Proceduralization 0..1 of the underlying schema (0 = deliberate, 1 = habit). */
+  habitStrength:   number
+  /** Preconditions satisfied in the current state. */
+  available:       boolean
+  /** Schema tags, carried so selection can route drives/risk without the registry. */
+  tags:            string[]
+  /**
+   * Top-down planning bias 0..1 — set when an executing plan's frontier step
+   * projected this affordance (source 'plan'). It lifts activation in the
+   * competition WITHOUT bypassing it (the plan biases; the field still decides).
+   */
+  planBias?:       number
+  /** Provenance: the plan whose frontier step projected this affordance. */
+  planId?:         string
+  /** Provenance: the frontier step id — flows through to action.outcome so the plan advances. */
+  stepId?:         string
+  tick:            number
+}
+
+/**
+ * EfferenceCopy — the forward model's prediction of an action's own consequences,
+ * emitted *before* enaction so reafference has something to compare against.
+ */
+export interface EfferenceCopy {
+  expectedValence:       number
+  expectedReward:        number
+  /** Optional predicted metric deltas the schema expects to cause. */
+  predictedMetricDeltas?: Record<string, number>
+}
+
+/**
+ * SchemaOutcome — reafference. The actual result of an enaction paired with what
+ * was predicted, yielding the prediction error that drives all learning.
+ */
+export interface SchemaOutcome {
+  schema:         string
+  affordanceId:   string
+  success:        boolean
+  /** Actual outcome quality 0..1. */
+  outcomeQuality: number
+  predicted:      EfferenceCopy
+  /** |predicted − actual| — the teaching signal. */
+  surprise:       number
+  tick:           number
+}
+
+/**
+ * LearnedSkill — the persisted competence unit. This, not the transient
+ * affordance field, is what travels in the PMA and makes a grown Will *act like
+ * itself* after re-embodiment.
+ */
+export interface LearnedSkill {
+  schema:            string
+  /** Proceduralization 0..1 — rises with low-error success, decays with disuse. */
+  habitStrength:     number
+  /** Expected reward 0..1 (EMA over outcomes). */
+  valueEstimate:     number
+  /** Learned default parameters for this schema. */
+  paramPriors:       Record<string, unknown>
+  enactments:        number
+  successes:         number
+  /** Rolling mean |prediction error|. */
+  avgPredictionError: number
+  lastEnactedTick:   number
+}
+
+/** An affordance with its computed competition activation. */
+export interface ScoredAffordance {
+  affordance: Affordance
+  activation: number
+}
+
+/**
+ * SelectionResult — the outcome of the competition. `needsDeliberation` is set
+ * when the field is ambiguous (high entropy) or the stakes are high, recruiting
+ * the executive (LLM); otherwise the winner is enacted directly (System 1).
+ */
+export interface SelectionResult {
+  winner:           ScoredAffordance | null
+  field:            ScoredAffordance[]
+  /** 0..1 ambiguity of the competition (1 = flat field, no clear winner). */
+  entropy:          number
+  needsDeliberation: boolean
+}