@mindot/will 0.5.0 → 0.7.0

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

@@ -28,10 +28,39 @@ 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'
+import { schemaEntityId, availabilityEntityId } from '#agency/schemas/repertoire'
+import { AWAIT_TIMEOUT } from '#agency/engines/motor.schema.executor'
 
 const PROC_THRESHOLD = 0.60   // mirror of repertoire's threshold for the habitual-count metric
 
+/**
+ * EXAFFERENCE P5 — soft outcome quality for a purely *sensory* confirmation: the
+ * world echoed our action back (a reafferent percept), but no host ack graded it.
+ * A modest positive — "it manifested" — below a host ack's 0.8, enough to free the
+ * awaiting intent and accrue competence instead of letting it time out as a failure.
+ */
+const SENSORY_SOFT_QUALITY = 0.6
+
+/**
+ * Registry #5 — the affect→percept valence seam, consumed. The echo now carries
+ * how the mind FEELS about what came back (Exteroception stamps it), so a
+ * sensory confirmation is graded rather than flat: quality = the soft base
+ * shifted by that valence within a bounded band.
+ *
+ * Two spans, because the two valence sources are not equal evidence:
+ *  • `'entity'` — the KnownEntityTracker's felt valence toward this very thing.
+ *    Real appraisal of the outcome ⇒ the wider span.
+ *  • `'ambient'` — the mind's mood at perception time. Weak context, NOT a
+ *    judgement of this action ⇒ a narrow span, so a bad mood cannot teach the
+ *    Will that a working skill failed.
+ *
+ * Neutral (or absent) valence reproduces the pre-seam 0.6 exactly.
+ */
+const SENSORY_VALENCE_SPAN_ENTITY  = 0.25
+const SENSORY_VALENCE_SPAN_AMBIENT = 0.10
+/** Below this the world's reflection reads as a failed outcome, not a success. */
+const SENSORY_SUCCESS_FLOOR = 0.5
+
 export class ReafferenceEngine implements CognitiveEngine {
   readonly name = 'reafference'
 
@@ -56,11 +85,11 @@ export class ReafferenceEngine implements CognitiveEngine {
   /** 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
+    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' )
+      ? ( 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
 
@@ -68,9 +97,9 @@ export class ReafferenceEngine implements CognitiveEngine {
       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' ],
+      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( ' → ' ) })` )
+    logger.info(`[reafference] registered proposed composite "${ id }" (${ steps.join(' → ') })`)
   }
   snapshot(): Record<string, unknown> {
     return { skills: this._repertoire.skills().size }
@@ -86,14 +115,102 @@ export class ReafferenceEngine implements CognitiveEngine {
     const del:     string[]                = []
     const metrics: Array<[ string, number ]> = []
 
-    // ── 1. Fold each new outcome into its skill ──────────────────
-    let updates    = 0
-    let discovered = 0
+    // ── 0. Gather outcomes: real ones from state + synthesized sensory ones ──
+    // A `reafferent` percept (P2) carrying a `sourceIntentId` is the world echoing
+    // our own action back. If that intent is still `awaiting` and no outcome graded
+    // it this tick (a host ack / sync / timeout — those WIN), synthesize a soft
+    // outcome so the skill learns and the intent is freed through the senses rather
+    // than timing out as a failure (EXAFFERENCE P5). Ack-less awaiting intents only.
+    const outcomes: Array<{ id: string; meta: Record<string, unknown>; fromState: boolean }> = []
+    const gradedIntentIds = new Set<string>()
     for( const [ id, e ] of state.entities ){
-      if( e.type !== 'agency.outcome' ) continue
+      if( e.type !== 'agency.outcome') continue
+      const m = ( e.metadata ?? {} ) as Record<string, unknown>
+      outcomes.push({ id, meta: m, fromState: true })
+      const iid = str( m['intentId'] ); if( iid ) gradedIntentIds.add( iid )
+    }
+
+    const awaiting = new Map<string, { schema: string; predictedReward: number; predictedValence: number }>()
+    for( const [ id, e ] of state.entities ){
+      if( e.type !== 'agency.intent' || str( e.metadata?.['status'] ) !== 'awaiting') continue
+      const m = ( e.metadata ?? {} ) as Record<string, unknown>
+      // Timeout boundary: at tick - dispatchedAt ≥ AWAIT_TIMEOUT the executor
+      // (which ran earlier this tick, off the same frozen snapshot) is writing
+      // its timeout-failure outcome right now — stand down so one enaction is
+      // never scored twice (soft success here + failure next tick).
+      if( tick - num( m['dispatchedAt'], tick ) >= AWAIT_TIMEOUT ) continue
+      awaiting.set( id, {
+        schema:           str( m['schema'] ) ?? '',
+        predictedReward:  num( m['predictedReward'],  0.5 ),
+        predictedValence: num( m['predictedValence'], 0 ),
+      })
+    }
+
+    let sensory = 0
+    const sensedIntentIds = new Set<string>()
+    for( const [ , e ] of state.entities ){
+      if( e.type !== 'percept') continue
       const m = ( e.metadata ?? {} ) as Record<string, unknown>
+      if( str( m['provenance'] ) !== 'reafferent') continue
+      const iid = str( m['sourceIntentId'] )
+      if( !iid || gradedIntentIds.has( iid ) || sensedIntentIds.has( iid ) ) continue
+      const aw = awaiting.get( iid )
+      if( !aw || !aw.schema ) continue          // only ack-less awaiting intents
+      sensedIntentIds.add( iid )
+      sensory++
+
+      // Registry #5: grade the confirmation by how the echo FELT, within a band
+      // whose width reflects how much that valence really says about THIS action.
+      const feltRaw = m['valence']
+      const felt    = typeof feltRaw === 'number' && Number.isFinite( feltRaw ) ? feltRaw : undefined
+      const span    = str( m['valenceSource'] ) === 'entity'
+        ? SENSORY_VALENCE_SPAN_ENTITY
+        : SENSORY_VALENCE_SPAN_AMBIENT
+      const quality = felt === undefined
+        ? SENSORY_SOFT_QUALITY
+        : clamp01( SENSORY_SOFT_QUALITY + Math.max( -1, Math.min( 1, felt ) ) * span )
+
+      outcomes.push({ id: `agency-outcome-${ tick }-${ iid }-sensory`, fromState: false, meta: {
+        schema:           aw.schema,
+        intentId:         iid,
+        success:          quality >= SENSORY_SUCCESS_FLOOR,
+        outcomeQuality:   quality,
+        valence:          felt ?? aw.predictedValence,
+        predictedReward:  aw.predictedReward,
+        predictedValence: aw.predictedValence,
+        surprise:         clamp01( Math.abs( aw.predictedReward - quality ) ),
+        mode:             'external',
+        reconciled:       true,
+        sensory:          true,
+        ...( felt !== undefined ? { sensoryValence: felt, valenceSource: str( m['valenceSource'] ) } : {} ),
+        tick,
+      } })
+    }
+
+    // ── 1. Fold each outcome into its skill ──────────────────────
+    let updates    = 0
+    let discovered = 0
+    let refused    = 0
+    for( const { id, meta: m, fromState } of outcomes ){
       const schema = str( m['schema'] )
-      if( !schema ){ del.push( id ); continue }
+      if( !schema ){ if( fromState ) del.push( id ); continue }
+
+      // POLICY_REAFFERENCE P2 — a refusal is NOT a failure. Route it to the
+      // availability layer and stop: it must never touch LearnedSkill (value,
+      // habit, param priors), or the Will learns it is unskilled at something it
+      // is merely forbidden to do. The awaiting intent is still freed, and a
+      // refused plan step is signalled unsuccessful so the plan doesn't hang.
+      if( m['refused'] === true ){
+        const finality = str( m['finality'] ) === 'class' ? 'class' : 'instance'
+        this._repertoire.recordRefusal( schema, finality, tick )
+        if( fromState ) del.push( id )
+        const refusedIntent = str( m['intentId'] )
+        if( refusedIntent ) del.push( refusedIntent )
+        const refusedPlan = str( m['planId'] )
+        if( refusedPlan ) this._emitPlanOutcome( refusedPlan, str( m['stepId'] ), schema, false, 0, 0, tick )
+        refused++
+        continue
+      }
 
       const { skill, proceduralized } = this._repertoire.recordOutcome({
         schema,
@@ -105,10 +222,11 @@ export class ReafferenceEngine implements CognitiveEngine {
       })
 
       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.
+      if( fromState ) del.push( id )       // real outcome consumed (synthetic ones were never in state)
+      // Host-ack reconciliation OR sensory confirmation: the 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++
@@ -131,23 +249,27 @@ export class ReafferenceEngine implements CognitiveEngine {
 
       if( proceduralized ){
         this._emitProceduralized( skill, tick )
-        logger.info( `[reafference] "${ schema }" proceduralized (habit ${ skill.habitStrength.toFixed( 2 ) })` )
+        logger.info(`[reafference] "${ schema }" proceduralized (habit ${ skill.habitStrength.toFixed( 2 ) })`)
       }
     }
 
-    // ── 2. Forgetting curve over the competence layer ────────────
+    // ── 2. Forgetting curve over the competence layer + availability recovery ──
     const dropped = this._repertoire.decay( tick )
-    for( const id of dropped ){
-      del.push( `agency-skill-${ id }` )
+    for( const id of dropped.skills ){
+      del.push(`agency-skill-${ id }`)
       del.push( schemaEntityId( id ) )   // composite mirror (harmless no-op for primitives)
     }
+    for( const id of dropped.availability )
+      del.push( availabilityEntityId( id ) )   // fully-recovered ⇒ remove the mirror
 
-    // ── 3. Mirror learned composite templates ────────────────────
+    // ── 3. Mirror learned composite templates + availability ─────
     // 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 )
+    for( const e of this._repertoire.compositeEntities() )   set.push( e )
+    // Availability entries (P2) mirror the same way — empty until a refusal lands.
+    for( const e of this._repertoire.availabilityEntities() ) set.push( e )
 
     // ── 4. Telemetry ─────────────────────────────────────────────
     const skills    = this._repertoire.skills()
@@ -157,7 +279,11 @@ export class ReafferenceEngine implements CognitiveEngine {
       [ 'agency.discovered.count', discovered ],
       [ 'agency.skill.count',      skills.size ],
       [ 'agency.habitual.count',   habitual ],
+      [ 'agency.sensory.confirmed', sensory ],
     )
+    // Only emit the refusal metric when it fired — a never-refused Will writes
+    // nothing here, preserving the byte-identical quiet path (cf. EXAFFERENCE P3).
+    if( refused > 0 ) metrics.push([ 'agency.refused.count', refused ])
 
     return { commands: { set, delete: del, metrics } }
   }
@@ -171,7 +297,7 @@ export class ReafferenceEngine implements CognitiveEngine {
         payload: { schema: skill.schema, habitStrength: skill.habitStrength, tick },
       })
     }
-    catch( err ){ logger.warn( `[reafference] publish failed: ${ err instanceof Error ? err.message : String( err ) }` ) }
+    catch( err ){ logger.warn(`[reafference] publish failed: ${ err instanceof Error ? err.message : String( err ) }`) }
   }
 
   /**
@@ -197,7 +323,7 @@ export class ReafferenceEngine implements CognitiveEngine {
         },
       })
     }
-    catch( err ){ logger.warn( `[reafference] plan outcome publish failed: ${ err instanceof Error ? err.message : String( err ) }` ) }
+    catch( err ){ logger.warn(`[reafference] plan outcome publish failed: ${ err instanceof Error ? err.message : String( err ) }`) }
   }
 
   private _emitDiscovered( schema: string, tick: Tick ): void {
@@ -208,7 +334,7 @@ export class ReafferenceEngine implements CognitiveEngine {
         salience: 0.5, payload: { schema, tick },
       })
     }
-    catch( err ){ logger.warn( `[reafference] discovered publish failed: ${ err instanceof Error ? err.message : String( err ) }` ) }
+    catch( err ){ logger.warn(`[reafference] discovered publish failed: ${ err instanceof Error ? err.message : String( err ) }`) }
   }
 }
 
@@ -239,3 +365,6 @@ function str( v: unknown ): string | undefined {
 function num( v: unknown, fallback: number ): number {
   return typeof v === 'number' && Number.isFinite( v ) ? v : fallback
 }
+function clamp01( n: number ): number {
+  return n < 0 ? 0 : n > 1 ? 1 : n
+}

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

@@ -46,8 +46,8 @@ const COMM_SCHEMAS = new Set([ 'reach-out', 'talk', 'text', 'broadcast', 'gestur
 
 /** 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'
+  if( schema.tags?.includes('external') ) return 'external'
+  if( schema.tags?.includes('communication') || COMM_SCHEMAS.has( schema.id ) ) return 'communicate'
   return 'sync'
 }
 
@@ -55,7 +55,7 @@ export function modeOf( schema: MotorSchema ): EnactionMode {
 export function enact( ctx: EnactionContext ): Enaction {
   const mode = modeOf( ctx.schema )
 
-  if( mode === 'communicate' ){
+  if( mode === 'communicate'){
     const name = str( ctx.parameters['targetEntityName'] ) ?? ctx.targetEntityId ?? 'them'
     return {
       mode, success: true, outcomeQuality: 0.7, valence: 0.1,
@@ -63,7 +63,7 @@ export function enact( ctx: EnactionContext ): Enaction {
     }
   }
 
-  if( mode === 'external' )
+  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.`,
@@ -82,25 +82,25 @@ function syncStance( ctx: EnactionContext ): Enaction {
   switch( schema.id ){
     case 'rest':
       // More restorative the more depleted the Will was.
-      return sync( 0.5 + ( 1 - e01 ) * 0.4, 0.15, 'I let myself recover; the pressure eases a little.' )
+      return sync( 0.5 + ( 1 - e01 ) * 0.4, 0.15, 'I let myself recover; the pressure eases a little.')
     case 'withdraw':
-      return sync( 0.5 + s01 * 0.3, 0.05 + s01 * 0.1, 'I pull back from the press of things; the world quietens.' )
+      return sync( 0.5 + s01 * 0.3, 0.05 + s01 * 0.1, 'I pull back from the press of things; the world quietens.')
     case 'reflect':
-      return sync( 0.6, 0.05, 'I turn inward; patterns from recent events settle into place.' )
+      return sync( 0.6, 0.05, 'I turn inward; patterns from recent events settle into place.')
     case 'attend':
-      return sync( 0.6, 0.0, 'I concentrate, mobilizing more of my attention.' )
+      return sync( 0.6, 0.0, 'I concentrate, mobilizing more of my attention.')
     case 'orient':
-      return sync( 0.5, 0.0, 'My awareness sweeps the situation, taking its measure.' )
+      return sync( 0.5, 0.0, 'My awareness sweeps the situation, taking its measure.')
     case 'wait':
-      return sync( 0.5, 0.0, 'I let time pass; regulatory processes continue their quiet work.' )
+      return sync( 0.5, 0.0, 'I let time pass; regulatory processes continue their quiet work.')
     case 'express':
-      return sync( 0.6, 0.1, 'My inner state becomes outwardly visible.' )
+      return sync( 0.6, 0.1, 'My inner state becomes outwardly visible.')
     case 'inspect': {
       const focus = str( parameters['focus'] ) ?? 'it'
-      return sync( 0.65, 0.05, `I examine ${ focus } closely; more of its detail resolves.` )
+      return sync( 0.65, 0.05, `I examine ${ focus } closely; more of its detail resolves.`)
     }
     default:
-      return sync( 0.5, 0.0, `I enact ${ schema.id }.` )
+      return sync( 0.5, 0.0, `I enact ${ schema.id }.`)
   }
 }
 

package/src/cognition/agency/proactive.communicator.ts

@@ -203,7 +203,7 @@ export class ProactiveCommunicator {
         content:     bubble,
         effectorName,
         replyToMessageId,
-      }, `-${ i }` ) )
+      }, `-${ i }`) )
     })
 
     // Write the intent record at push time so context-builder can see what we said.

package/src/cognition/agency/reconcile.learning.ts

@@ -24,6 +24,14 @@ export interface HostAckResult {
   /** −1..1 felt valence of the outcome. */
   valence?:       number
   description?:   string
+  /**
+   * POLICY_REAFFERENCE P2 — this ack is a policy REFUSAL, not a world failure.
+   * The ReafferenceEngine routes it to the availability layer (NOT competence):
+   * a refusal must never teach the Will it is unskilled at something it is merely
+   * forbidden to do. `finality` decides how hard availability is cut.
+   */
+  refused?:       boolean
+  finality?:      'class' | 'instance'
 }
 
 /**
@@ -67,10 +75,11 @@ export function reconcileInvocation(
       predictedReward:  predicted.reward,
       predictedValence: predicted.valence,
       surprise,
-      description:      result.description ?? ( result.success ? 'The world confirmed the action.' : 'The world rejected the action.' ),
+      description:      result.description ?? ( result.success ? 'The world confirmed the action.' : 'The world rejected the action.'),
       mode:             'external',
       tick,
       reconciled:       true,
+      ...( result.refused ? { refused: true, finality: result.finality ?? 'instance' } : {} ),
       ...( provenance.planId ? { planId: provenance.planId } : {} ),
       ...( provenance.stepId ? { stepId: provenance.stepId } : {} ),
     },

package/src/cognition/agency/revocation.ts

@@ -0,0 +1,79 @@
+// ─────────────────────────────────────────────────────────────
+// src/agency/revocation.ts  —  commitment-revocation tombstones
+// ─────────────────────────────────────────────────────────────
+//
+// EXAFFERENCE P4. When the world ruptures hard enough (rupture ≥
+// RUPTURE_REVOKE_GATE), the ActionSelector doesn't just soften its switch cost
+// (P3) — it *lets go* of a commitment it was still weighing: a `deliberating`
+// intent. But the selector cannot delete that intent directly. Registration
+// order is Selector → Deliberation → Executor, and each engine reads the frozen
+// tick-start snapshot, so a same-tick selector-delete + deliberation-set on the
+// same intent applies set-after-delete → the intent is RESURRECTED as `selected`
+// and enacted despite revocation (the P0 audit's resurrection race).
+//
+// The tombstone breaks that race by construction: the selector writes a SEPARATE
+// `agency.revocation` entity keyed by the intent id (no same-entity write). One
+// tick later both honorers see it from frozen state:
+//   • the Deliberation engine skips + deletes tombstoned `deliberating` intents;
+//   • the Executor refuses to enact a tombstoned `selected` intent (the half-race
+//     where deliberation committed `selected` the same tick the tombstone landed).
+// Revocation commits NO successor — the field re-forms and next tick selects.
+// A short TTL reaps a tombstone whose intent already vanished for another reason.
+// ─────────────────────────────────────────────────────────────
+
+import type { EntityInput, Tick } from '#core/types'
+
+export const REVOCATION_TYPE = 'agency.revocation'
+
+/** Rupture at/above which a still-deliberating commitment is revoked (rarer than
+ *  P3's recruitment-grade softening — letting go is a bigger step than easing up). */
+export const RUPTURE_REVOKE_GATE = 0.7
+
+/** Safety reap: a tombstone whose intent disappeared otherwise dies after this. */
+export const REVOCATION_TTL_TICKS = 5
+
+export function revocationId( intentId: string ): string {
+  return `agency-revocation-${ intentId }`
+}
+
+/** Build the tombstone for a revoked intent (keyed by intent id — one per intent). */
+export function revocationEntity(
+  intentId: string, schema: string, rupture: number, tick: Tick,
+): EntityInput {
+  return {
+    id:   revocationId( intentId ),
+    type: REVOCATION_TYPE,
+    metadata: { intentId, schema, rupture, tick, expiresAt: tick + REVOCATION_TTL_TICKS },
+  }
+}
+
+/** Intent ids under a live (unexpired) revocation tombstone, from frozen state. */
+export function revokedIntentIds(
+  entities: ReadonlyMap<string, { type: string; metadata?: ReadonlyMap<string, unknown> | Record<string, unknown> }>,
+  tick:     Tick,
+): Set<string> {
+  const out = new Set<string>()
+  for( const [ , e ] of entities ){
+    if( e.type !== REVOCATION_TYPE ) continue
+    const m = ( e.metadata ?? {} ) as Record<string, unknown>
+    const intentId = typeof m['intentId'] === 'string' ? m['intentId'] as string : undefined
+    const expiresAt = typeof m['expiresAt'] === 'number' ? m['expiresAt'] as number : 0
+    if( intentId && tick < expiresAt ) out.add( intentId )
+  }
+  return out
+}
+
+/** Ids of expired tombstones to sweep (TTL reap for intents that vanished otherwise). */
+export function staleRevocationIds(
+  entities: ReadonlyMap<string, { type: string; metadata?: ReadonlyMap<string, unknown> | Record<string, unknown> }>,
+  tick:     Tick,
+): string[] {
+  const stale: string[] = []
+  for( const [ id, e ] of entities ){
+    if( e.type !== REVOCATION_TYPE ) continue
+    const m = ( e.metadata ?? {} ) as Record<string, unknown>
+    const expiresAt = typeof m['expiresAt'] === 'number' ? m['expiresAt'] as number : 0
+    if( tick >= expiresAt ) stale.push( id )
+  }
+  return stale
+}

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

@@ -39,6 +39,23 @@ 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
 
+// ── availability layer (POLICY_REAFFERENCE P2) ────────────────
+// Availability is NOT competence. It answers "may I use this schema", learned
+// from policy refusals, and is kept strictly apart from LearnedSkill so a
+// refusal never teaches the Will it is *unskilled* at something it is merely
+// *forbidden* to do. A `class` refusal ("never, under this policy") drives
+// availability down hard; an `instance` refusal ("not with those parameters")
+// dents it lightly — the Will should keep reaching for the ability, just not
+// that way. Recovery is slow but real, so a policy change is re-discoverable:
+// availability never floors at zero, and it climbs back toward 1 with disuse of
+// the refusal. P2 keys availability by SCHEMA; per-(schema, params) envelope
+// narrowing is a follow-up that belongs at selection time, not fielding time.
+const AVAIL_DROP_CLASS    = 0.50  // multiplicative cut on a class-final refusal
+const AVAIL_DROP_INSTANCE = 0.12  // lighter cut on an instance-final refusal
+const AVAIL_FLOOR         = 0.05  // never zero — re-probe must always be possible
+const AVAIL_RECOVERY      = 0.02  // per-decay climb back toward 1
+const AVAIL_RECOVERED     = 0.999 // at/above this the entry is dropped (quiet path)
+
 export interface OutcomeObservation {
   schema:         string
   success:        boolean
@@ -54,6 +71,9 @@ export class SchemaRepertoire {
   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>()
+  /** Availability layer (P2): schema → { value 0..1, lastRefusedTick }. Empty until
+   *  a refusal lands — a never-refused Will writes nothing here (byte-identical). */
+  private _availability = new Map<string, { value: number; lastRefusedTick: number }>()
 
   constructor( seed: MotorSchema[] = INNATE_SCHEMAS ){
     for( const s of seed ) this._templates.set( s.id, s )
@@ -85,6 +105,32 @@ export class SchemaRepertoire {
   skills(): ReadonlyMap<string, LearnedSkill> { return this._skills }
   getSkill( id: string ): LearnedSkill | undefined { return this._skills.get( id ) }
 
+  // ── availability (P2) ─────────────────────────────────────────
+  availability(): ReadonlyMap<string, { value: number; lastRefusedTick: number }> { return this._availability }
+
+  /**
+   * How available a schema is right now, 0..1. Absent from the ledger ⇒ 1
+   * (fully available — the common case). This is the ONLY value the
+   * AffordanceSynthesizer reads; it never touches competence.
+   */
+  availabilityOf( schema: string ): number {
+    return this._availability.get( schema )?.value ?? 1
+  }
+
+  /**
+   * Fold a policy refusal into the availability layer (NOT competence). A
+   * `class` refusal cuts availability hard; an `instance` refusal dents it
+   * lightly. Multiplicative so repeated refusals compound toward — but never
+   * reach — zero, keeping re-probe alive.
+   */
+  recordRefusal( schema: string, finality: 'class' | 'instance', tick: number ): number {
+    const prev = this._availability.get( schema )?.value ?? 1
+    const drop = finality === 'class' ? AVAIL_DROP_CLASS : AVAIL_DROP_INSTANCE
+    const value = Math.max( AVAIL_FLOOR, prev * ( 1 - drop ) )
+    this._availability.set( schema, { value, lastRefusedTick: tick } )
+    return value
+  }
+
   /**
    * Fold one outcome into the schema's learned skill. Returns the updated skill
    * and whether it just crossed the proceduralization threshold this update.
@@ -118,12 +164,14 @@ export class SchemaRepertoire {
   }
 
   /**
-   * 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.
+   * Forgetting curve over the competence layer, plus availability recovery.
+   * Skills unused for IDLE_TICKS lose habit; learned composites below DROP_HABIT
+   * are dropped entirely (template + skill). Availability entries climb back
+   * toward 1 and are dropped once fully recovered. Returns the ids that were
+   * removed from each layer so their mirrored state entities can be deleted.
    */
-  decay( tick: number ): string[] {
-    const dropped: string[] = []
+  decay( tick: number ): { skills: string[]; availability: string[] } {
+    const skills: string[] = []
     for( const [ id, skill ] of this._skills ){
       if( tick - skill.lastEnactedTick <= IDLE_TICKS ) continue
 
@@ -132,12 +180,23 @@ export class SchemaRepertoire {
         this._skills.delete( id )
         this._templates.delete( id )
         this._learned.delete( id )
-        dropped.push( id )
+        skills.push( id )
         continue
       }
       this._skills.set( id, { ...skill, habitStrength } )
     }
-    return dropped
+
+    // Availability recovery (P2): each entry climbs slowly back toward 1, so a
+    // policy change is re-discoverable. A fully-recovered entry is dropped, so a
+    // Will that was refused long ago returns to the byte-identical quiet path.
+    const availability: string[] = []
+    for( const [ id, avail ] of this._availability ){
+      const value = avail.value + AVAIL_RECOVERY * ( 1 - avail.value )
+      if( value >= AVAIL_RECOVERED ){ this._availability.delete( id ); availability.push( id ) }
+      else this._availability.set( id, { ...avail, value } )
+    }
+
+    return { skills, availability }
   }
 
   // ── PMA portability (Phase 6 reads these) ─────────────────────
@@ -167,7 +226,7 @@ export class SchemaRepertoire {
     const out: EntityInput[] = []
     for( const id of this._learned ){
       const s = this._templates.get( id )
-      if( s && s.kind === 'composite' ) out.push( schemaEntity( s ) )
+      if( s && s.kind === 'composite') out.push( schemaEntity( s ) )
     }
     return out
   }
@@ -188,6 +247,30 @@ export class SchemaRepertoire {
       this._learned.add( s.id )
     }
   }
+
+  /** Availability ledger encoded as `agency.availability` state entities (P2).
+   *  Empty until a refusal lands, so the quiet path writes nothing. */
+  availabilityEntities(): EntityInput[] {
+    const out: EntityInput[] = []
+    for( const [ schema, a ] of this._availability )
+      out.push( availabilityEntity( schema, a.value, a.lastRefusedTick ) )
+    return out
+  }
+
+  /** Rehydrate the availability ledger from state after a restore. Idempotent;
+   *  keeps whichever value is more restrictive so a concurrent refusal isn't lost. */
+  restoreAvailability( entities: ReadonlySimulationState['entities'] ): void {
+    for( const e of entities.values() ){
+      if( e.type !== AVAILABILITY_ENTITY_TYPE ) continue
+      const m = ( e.metadata ?? {} ) as Record<string, unknown>
+      const schema = typeof m['schema'] === 'string' ? m['schema'] : ''
+      if( !schema ) continue
+      const value = typeof m['value'] === 'number' ? m['value'] : 1
+      const tick  = typeof m['lastRefusedTick'] === 'number' ? m['lastRefusedTick'] : 0
+      const prev  = this._availability.get( schema )
+      if( !prev || value < prev.value ) this._availability.set( schema, { value, lastRefusedTick: tick } )
+    }
+  }
 }
 
 // ─── helpers ─────────────────────────────────────────────────────────────────
@@ -209,6 +292,23 @@ function clamp01( n: number ): number {
   return n < 0 ? 0 : n > 1 ? 1 : n
 }
 
+// ─── availability ⇄ state-entity codec (P2) ──────────────────────────────────
+
+/** State-entity type for a mirrored availability entry. */
+export const AVAILABILITY_ENTITY_TYPE = 'agency.availability'
+
+/** Stable entity id for a schema's availability mirror (idempotent re-writes). */
+export function availabilityEntityId( schema: string ): string { return `agency-availability-${ schema }` }
+
+/** Encode one availability entry as a state entity. */
+function availabilityEntity( schema: string, value: number, lastRefusedTick: number ): EntityInput {
+  return {
+    id:   availabilityEntityId( schema ),
+    type: AVAILABILITY_ENTITY_TYPE,
+    metadata: { schema, value, lastRefusedTick },
+  }
+}
+
 // ─── composite ⇄ state-entity codec (snapshot/replay) ────────────────────────
 
 /** State-entity type for a mirrored composite template. */
@@ -242,7 +342,7 @@ function readSchema( m: Record<string, unknown> | undefined ): MotorSchema | und
   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
+  if( !id || ( kind !== 'composite' && kind !== 'primitive') ) return undefined
   return {
     id,
     kind,