@mindot/will 0.9.0 → 0.10.0

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

@@ -32,6 +32,7 @@ import { schemaEntityId, availabilityEntityId } from '#agency/schemas/repertoire
 import { asFinality } from '#stem/policy/arbiter'
 import { AWAIT_TIMEOUT } from '#agency/engines/motor.schema.executor'
 import { readEffectiveParams } from '#cognition/persona.prior'
+import { asProvenance } from '#senses/provenance'
 import {
   SENT_TYPE, DEFAULT_REPLY_WINDOW_TICKS, resolveReplyExpectations,
 } from '#agency/conversation.aim'
@@ -161,7 +162,11 @@ export class ReafferenceEngine implements CognitiveEngine {
     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
+      // asProvenance(), not a literal compare: this is an untyped read out of
+      // entity metadata, exactly what that normalizer exists for. Behaviour is
+      // unchanged — absent and garbage both normalize to 'exafferent', which
+      // fails this test the same way `str()` returning undefined did.
+      if( asProvenance( m['provenance'] ) !== 'reafferent') continue
       const iid = str( m['sourceIntentId'] )
       if( !iid || gradedIntentIds.has( iid ) || sensedIntentIds.has( iid ) ) continue
       const aw = awaiting.get( iid )
@@ -201,6 +206,7 @@ export class ReafferenceEngine implements CognitiveEngine {
     let updates    = 0
     let discovered = 0
     let refused    = 0
+    let withheld   = 0
     for( const { id, meta: m, fromState } of outcomes ){
       const schema = str( m['schema'] )
       if( !schema ){ if( fromState ) del.push( id ); continue }
@@ -210,6 +216,25 @@ export class ReafferenceEngine implements CognitiveEngine {
       // 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.
+      // Chosen silence. The mind considered speaking and decided not to, which
+      // is a decision — not a failure, and not a refusal either: nothing forbade
+      // it, so availability must not be dented and `recordRefusal` must not run.
+      // Free the intent, signal any plan step, and teach NOTHING: the question
+      // was never whether it can speak.
+      //
+      // Before this, a declined outreach timed out at AWAIT_TIMEOUT and folded
+      // into `reach-out`'s competence as a failure — the mind learning it is bad
+      // at speaking from the times it chose not to speak.
+      if( m['withheld'] === true ){
+        if( fromState ) del.push( id )
+        const heldIntent = str( m['intentId'] )
+        if( heldIntent ) del.push( heldIntent )
+        const heldPlan = str( m['planId'] )
+        if( heldPlan ) this._emitPlanOutcome( heldPlan, str( m['stepId'] ), schema, false, 0, 0, tick )
+        withheld++
+        continue
+      }
+
       if( m['refused'] === true ){
         const finality = asFinality( m['finality'] )
 
@@ -251,13 +276,13 @@ export class ReafferenceEngine implements CognitiveEngine {
       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
+      // the plan link 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 )
+        this._emitPlanOutcome( planId, str( m['stepId'] ), schema, m['success'] === true, num( m['outcomeQuality'], 0 ), num( m['surprise'], 0 ), tick, str( m['description'] ) )
 
       // 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).
@@ -320,6 +345,10 @@ export class ReafferenceEngine implements CognitiveEngine {
     // 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 ])
+    // Counted separately from refusals on purpose: one is the world saying no,
+    // the other is the mind saying not now. Collapsing them would read as a
+    // policy problem in the telemetry when nothing was forbidden.
+    if( withheld > 0 ) metrics.push([ 'agency.withheld.count', withheld ])
 
     return { commands: { set, delete: del, metrics } }
   }
@@ -435,6 +464,9 @@ export class ReafferenceEngine implements CognitiveEngine {
   private _emitPlanOutcome(
     planId: string, stepId: string | undefined, schema: string,
     success: boolean, outcomeQuality: number, surprise: number, tick: Tick,
+    /** The host's own words for what happened. Absent on withheld/refused paths,
+     *  where there was no host and nothing to say beyond the fate. */
+    description?: string,
   ): void {
     if( !this._bus ) return
     try {
@@ -443,7 +475,14 @@ export class ReafferenceEngine implements CognitiveEngine {
         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.',
+          // The host's own words for what happened, not a stock sentence. This
+          // hardcoded `'The world confirmed the action.'` — and since
+          // `action.record` is built from this payload, that phrase (or nothing,
+          // from the executor's side) is ALL the prompt's `## Recent Action
+          // Outcomes` ever showed. The `agency.outcome` entity has carried the
+          // real description the whole time (`reconcile.learning.ts:89`); it was
+          // read here as `m['description']` and dropped on the floor.
+          description: description ?? ( success ? 'The world confirmed the action.' : 'The world rejected the action.'),
           planId,
           ...( stepId ? { stepId } : {} ),
           tick,

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

@@ -95,10 +95,23 @@ function syncStance( ctx: EnactionContext ): Enaction {
       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.')
-    case 'inspect': {
-      const focus = str( parameters['focus'] ) ?? 'it'
-      return sync( 0.65, 0.05, `I examine ${ focus } closely; more of its detail resolves.`)
-    }
+    // No `inspect` case, deliberately.
+    //
+    // Looking is now outward ONLY — a question put to the world, tagged external
+    // and dispatched. Turning attention inward already has three names on this
+    // very floor: `orient` sweeps the situation, `attend` mobilises attention,
+    // `reflect` turns inward and lets patterns settle. `inspect` naming that too
+    // was a second name for an act that already had one.
+    //
+    // The cost of the collision was not stylistic. The two readings have
+    // DIFFERENT failure modes — "I hold no record of it" versus "the world did not
+    // answer" — and one verb covering both meant a pure function needed three
+    // flags passed in to tell which it was. Live, the inward reading could not
+    // fail at all: a fresh Will proceduralized inspect to habit 0.64 in fifteen
+    // ticks, examining its own affordance entities and being told it went well.
+    //
+    // Outward-only, that is structurally impossible rather than conditionally
+    // caught. An unanswered look fails because nothing answered.
     default:
       return sync( 0.5, 0.0, `I enact ${ schema.id }.`)
   }

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

@@ -17,6 +17,7 @@
 
 import type { EntityInput, Tick } from '#core/types'
 import type { DenialFinality, PolicyCounterfactual } from '#stem/policy/arbiter'
+import type { PlanLink } from '#agency/types'
 
 export interface HostAckResult {
   success:        boolean
@@ -55,7 +56,7 @@ export interface HostAckResult {
  * `agency.invocation` payload); `predictedReward`/`predictedValence` are the
  * efference copy the executor persisted on the intent, so surprise is honest.
  *
- * `provenance` carries the awaiting intent's plan link (planId/stepId) when it was
+ * `planLink` carries the awaiting intent's plan step (planId/stepId) when it was
  * committed from a plan's frontier prior. It rides on the agency.outcome so the
  * ReafferenceEngine — the engine that consumes async-acked outcomes — can emit the
  * `action.outcome{planId,stepId}` the PlanningEngine advances on. (The executor
@@ -68,7 +69,7 @@ export function reconcileInvocation(
   result:   HostAckResult,
   tick:     Tick,
   predicted: { reward: number; valence: number } = { reward: 0.5, valence: 0 },
-  provenance: { planId?: string; stepId?: string } = {},
+  planLink: PlanLink = {},
 ): EntityInput {
   const outcomeQuality = result.outcomeQuality ?? ( result.success ? 0.8 : 0.1 )
   const valence        = result.valence ?? ( result.success ? 0.2 : -0.2 )
@@ -94,8 +95,8 @@ export function reconcileInvocation(
       // Only when the arbiter actually reported a bound — a refusal without one
       // writes no key at all, so the quiet path is unchanged.
       ...( result.refused && result.counterfactual ? { counterfactual: result.counterfactual } : {} ),
-      ...( provenance.planId ? { planId: provenance.planId } : {} ),
-      ...( provenance.stepId ? { stepId: provenance.stepId } : {} ),
+      ...( planLink.planId ? { planId: planLink.planId } : {} ),
+      ...( planLink.stepId ? { stepId: planLink.stepId } : {} ),
     },
   }
 }

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

@@ -92,7 +92,102 @@ export const INNATE_SCHEMAS: MotorSchema[] = [
     cost:       0.06,
     preconditions: [ { metric: 'energy.level', op: 'gt', value: 8 } ],
     baseValence: 0.05,
-    tags:       [ 'perception', 'information' ],
+    /**
+     * Outward only — a question put to the world, which is the only thing that
+     * can answer it.
+     *
+     * Turning attention inward already has three names on this very floor:
+     * `orient` sweeps the situation, `attend` mobilises attention, `reflect`
+     * turns inward and lets patterns settle. `inspect` naming that too was a
+     * second name for an act that already had one.
+     *
+     * The collision was not stylistic. The two readings have DIFFERENT failure
+     * modes — "I hold no record of it" versus "the world did not answer" — so one
+     * verb covering both forced three disambiguation flags into a pure function,
+     * and left the inward reading unable to fail at all. Live, a fresh Will
+     * proceduralized this to habit 0.64 within fifteen ticks of birth and spent
+     * five of its first eight decisions on it, examining its own affordance
+     * entities and being told each time that it went well.
+     *
+     * Tagged external it rides the path `reach-out` already rides: dispatched to
+     * the host, held awaiting, acked or timed out. The ACK ITSELF carries the
+     * answer — `observation`, in whatever shape the host keeps it — and the
+     * engine turns that into a reafferent percept the mind judges for itself
+     * (SIGNAL_BOUNDARY P2). One act, one answer, one percept.
+     *
+     * This paragraph used to say the opposite: that an ack carried only
+     * `{success, description}` and so a host CANNOT hand facts back, which
+     * obliged every host to call `perceive()` a second time with its own result
+     * — the laundering that made a Will's own act arrive looking like news from
+     * the world. P2 removed the obligation; this comment outlived it by two
+     * merges, which is the ordinary way a false comment survives: nothing
+     * compiles it.
+     *
+     * A look nothing answers still fails, and that is what teaches a mind to
+     * stop examining what will not resolve. Through the SDK an effector with no
+     * handler is acked failed inside the tick; a host driving the stem directly
+     * leaves the intent awaiting until AWAIT_TIMEOUT abandons it.
+     *
+     * Innate AND host-dependent is not a contradiction; `reach-out` is both.
+     * Every mind can look, but whether looking finds anything depends on there
+     * being a world.
+     */
+    tags:       [ 'perception', 'information', 'external' ],
+  },
+  {
+    /**
+     * Look at a clock.
+     *
+     * WHY THIS IS AN ACT AND NOT A FACT THE PROMPT HANDS OVER. A body knows its
+     * own rhythm — tired, alert, trough — because a rhythm is something a body
+     * DOES. It does not know that it is 15:42, because that is a fact about the
+     * world, and the only way a fact about the world reaches a mind is by the
+     * mind going and getting it. Every prompt used to carry the hour for free,
+     * and it was wrong in three ways at once precisely because nobody had to
+     * ask where it came from.
+     *
+     * Innate AND host-dependent, exactly as `inspect` and `reach-out` are:
+     * every mind can ask what time it is; whether anything answers depends on
+     * there being a world with a clock in it.
+     *
+     * A host that has one answers on the ack — `observation`, in whatever shape
+     * it keeps time: an ISO string, an hour and a zone, a mission-elapsed count.
+     * It does not have to phrase it, and it should not: the mind reads the data
+     * and makes the meaning of it (SIGNAL_BOUNDARY P2). The answer lands as a
+     * reafferent percept stamped with the intent that sought it, so what she
+     * knows about the hour is something she went and found, with a record of
+     * having found it.
+     *
+     * A host that has none never answers, and the failure is honest in either
+     * shape it takes: through the SDK an unregistered effector is acked failed
+     * inside the tick ("No handler registered for effector ..."), through the
+     * raw stem the intent sits awaiting until AWAIT_TIMEOUT abandons it. Either
+     * way the mind learns that time is not available here — which is a true
+     * thing about this world — rather than being handed a fiction.
+     *
+     * That degradation is the point of putting it here rather than in a config.
+     * A clock injected per-host is a fact one Will has and another does not,
+     * with no way for either to know which it is. Sought, it is the same
+     * mechanism for all of them, and the answer — or its absence — is
+     * something the mind can weigh.
+     *
+     * `binds: 'none'` because the time is not a referent. There is nothing to
+     * point at; you just look.
+     */
+    id:         'check-time',
+    kind:       'primitive',
+    // 'innate', not 'perceptual'. `inspect` is perceptual because a percept
+    // EVOKES it — it binds the thing it looks at. Nothing evokes this; it is
+    // always there, like `orient` and `rest`. The synthesizer caps
+    // percept-evoked affordances at attention capacity and never caps the
+    // floor, and a glance at a clock belongs to the floor.
+    source:     'innate',
+    binds:      'none',
+    // Cheaper than `inspect` (0.06): a glance at a clock, not an examination.
+    cost:       0.03,
+    preconditions: [ { metric: 'energy.level', op: 'gt', value: 5 } ],
+    baseValence: 0.0,
+    tags:       [ 'perception', 'information', 'external' ],
   },
   {
     id:         'reach-out',

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

@@ -24,10 +24,11 @@
 //   paramPriors    — last known-good parameters become defaults
 // ─────────────────────────────────────────────────────────────
 
+import { logger } from '#core/logger'
 import type { MotorSchema, LearnedSkill } from '#agency/types'
 import type { EntityInput, ReadonlySimulationState } from '#core/types'
 import type { DenialFinality } from '#stem/policy/arbiter'
-import { INNATE_SCHEMAS } from '#agency/schemas/innate'
+import { INNATE_SCHEMAS, INNATE_SCHEMA_BY_ID } from '#agency/schemas/innate'
 
 const VALUE_ALPHA       = 0.2   // value EMA rate
 const ERROR_BETA        = 0.2   // prediction-error EMA rate
@@ -99,6 +100,23 @@ export class SchemaRepertoire {
    * reafference then builds skill on. Idempotent; re-registering updates it.
    */
   registerExternal( schema: MotorSchema ): void {
+    // An innate schema is part of the body, not a slot a tenant may redefine.
+    //
+    // This sets by id, so a host registering a handler for a name the floor
+    // already uses would REPLACE the innate schema with a generated one —
+    // silently dropping its `binds`, cost, preconditions and tags. `inspect` is
+    // the live case: a Discord bridge answering inquiries would have overwritten
+    // the very schema whose `binds: 'percept'` is how inquiry finds its targets,
+    // and the mind would have lost the ability to look at what it cannot place in
+    // exchange for gaining an answerer.
+    //
+    // Registering the HANDLER is still what the host wanted and still happens —
+    // only the redeclaration is refused. The container supplies the mechanism; a
+    // tenant supplies what answers it.
+    if( INNATE_SCHEMA_BY_ID.has( schema.id ) ){
+      logger.debug(`[repertoire] "${ schema.id }" is innate — keeping the body's schema, binding the handler only`)
+      return
+    }
     this._templates.set( schema.id, schema )
   }
 

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

@@ -77,6 +77,20 @@ export interface ScoreWeights {
    * pressing reason to speak again still wins.
    */
   repeat:  number
+  /**
+   * How strongly a verdict System 2 already reached holds the competition.
+   *
+   * Peer of `will` and `repeat` in magnitude, and for the same reason each of
+   * those is: having thought a choice through should weigh about what willing it
+   * does, and no more. Large enough that the settled option clears the
+   * selector's ambiguity gate (0.06) for most of the settlement's life, so the
+   * same question is not re-deliberated every few ticks; small enough that a
+   * genuinely pressing affordance — threat, a person waiting, a drive gone
+   * urgent — still out-competes a standing verdict.
+   *
+   * Decays to 0 with the settlement, so the question re-opens on its own.
+   */
+  settled: number
 }
 
 export const DEFAULT_WEIGHTS: ScoreWeights = {
@@ -92,6 +106,7 @@ export const DEFAULT_WEIGHTS: ScoreWeights = {
   inhib:   0.30,
   risk:    0.20,
   repeat:  0.30,
+  settled: 0.30,
 }
 
 /**
@@ -190,6 +205,7 @@ export function scoreAffordance(
     - w.inhib   * bias.inhibition
     - w.risk    * risk( a, bias )
     - w.repeat  * ( a.justEnacted ?? 0 )
+    + w.settled * ( a.settled ?? 0 )
   )
   // POLICY_REAFFERENCE P2 — policy availability damps a POSITIVE activation only,
   // never flipping its sign: a refused ability competes weakly (so it is rarely

package/src/cognition/agency/settlement.ts

@@ -0,0 +1,203 @@
+// ─────────────────────────────────────────────────────────────
+// src/agency/settlement.ts  —  having thought about it
+// ─────────────────────────────────────────────────────────────
+//
+// The agency has always been able to represent having ACTED. It could not
+// represent having DECIDED.
+//
+// System 2 is recruited when the field is ambiguous — `margin < marginGate` in
+// the ActionSelector, where margin is the activation gap between the top two
+// affordances. The DeliberationEngine then resolves the contest and writes back
+// exactly one thing: that intent flipped to 'selected', carrying `deliberated:
+// true`. Nothing reads `deliberated`. The synthesizer rebuilds the field from
+// scratch next tick, the same rivals score the same, the margin is again below
+// the gate, and the same question is deliberated again.
+//
+// Measured on a live COO over 7 hours: 149 deliberations, median gap between
+// them 17 seconds, 139 of 148 gaps under a minute — one LLM call every ~3 ticks
+// for the whole run, and the single largest line in her cost. She could see it
+// and had no mechanism to leave it:
+//
+//   "Nothing has changed since my last ten deliberation cycles. Goal-7 is
+//    externally blocked — this is a fact, not a diagnosis I need to reach again."
+//   "I have composed the same message to FKEM across twelve deliberation cycles
+//    and not sent it."
+//   "There is nothing left to deliberate. I am looking."
+//
+// So: a settlement is the trace a verdict leaves in the field it was called in
+// to resolve. It is the missing peer of a family the engine already has —
+// having acted damps re-acting (`justEnacted`), having spoken damps re-speaking
+// (`spokeAnywhereAt`), having committed can be withdrawn (revocation
+// tombstones) — and having thought damped nothing at all.
+//
+// The mechanism is deliberately ONE quantity doing both jobs. Raising the
+// settled option's activation means (a) the verdict has force, so System 1 does
+// not coin-flip its way to a different answer on the next tick of the same flat
+// field, and (b) the margin to the runner-up widens past the gate, so System 2
+// is not recruited for a question it has already answered. The flatness is what
+// summoned deliberation; the verdict is what gives the field the shape it
+// lacked.
+//
+// And it DECAYS, like everything else here. This is a refractory period, not a
+// lock — the user's objection to "a hard conditional gate that does not promise
+// any flexibility or dynamism of the mind" is the whole design constraint. As
+// the settlement ages the field flattens again and the question genuinely
+// re-opens; a rupture revokes it outright through the machinery that already
+// exists. A mind may always change its mind. It should not have to reach the
+// same conclusion every three seconds to keep holding it.
+// ─────────────────────────────────────────────────────────────
+
+import type { EntityInput, Tick } from '#core/types'
+
+export const SETTLEMENT_TYPE = 'agency.settlement'
+
+/**
+ * Ticks a verdict holds before the question is genuinely open again.
+ *
+ * Set to the satiation window rather than the echo window, and the symmetry is
+ * the argument: having thought about something should hold about as long as
+ * having done it. The echo window (`CONSEQUENCE_TTL_TICKS`, 30) answers "could
+ * the world still be replying to me" — a different and necessarily shorter
+ * question that has nothing to do with whether a choice is settled.
+ *
+ * At the COO's observed rate (~5s/tick) this is roughly five minutes of held
+ * verdict, against a mind that was re-deciding every three ticks.
+ */
+export const SETTLEMENT_TTL_TICKS = 60
+
+export interface SettlementDescriptor {
+  /** The act that won the contest. */
+  schema:          string
+  /** Its object, when it has one — keyed exactly as satiation is, on purpose. */
+  targetEntityId?: string
+  /**
+   * The rivals it was weighed against.
+   *
+   * Not used for matching — a settlement is keyed on what WON, so a slightly
+   * differently-framed contest still meets a verdict the mind has already
+   * reached. Carried because "I decided this over that" is the introspectable
+   * fact, and a settlement with no memory of what it beat is a preference with
+   * no reason attached.
+   */
+  over?:           readonly string[]
+  tick:            Tick
+  expiresAt:       Tick
+}
+
+/** Stable id — one settlement per (schema, target), so re-deciding refreshes it. */
+export function settlementId( schema: string, targetEntityId?: string ): string {
+  return `agency-settlement-${ schema }${ targetEntityId ? `-${ targetEntityId }` : '' }`
+}
+
+/** Build the settlement entity. Ordinary state, so it snapshots and replays (FN9). */
+export function settlementEntity( d: SettlementDescriptor ): EntityInput {
+  return {
+    id:   settlementId( d.schema, d.targetEntityId ),
+    type: SETTLEMENT_TYPE,
+    metadata: { ...d, ...( d.over ? { over: [ ...d.over ] } : {} ) },
+  }
+}
+
+/**
+ * Read a settlement back off entity metadata.
+ *
+ * Decoded field-for-field, including `over`. A value written by one side and
+ * never read by the other is the defect shape this codebase has now hit six
+ * times, and it is the exact defect this module exists to fix — `deliberated:
+ * true` was written on every deliberated intent and read by nobody.
+ */
+export function readSettlement(
+  m: ReadonlyMap<string, unknown> | Record<string, unknown> | undefined,
+): SettlementDescriptor | null {
+  const meta = ( m instanceof Map ? Object.fromEntries( m ) : m ?? {} ) as Record<string, unknown>
+  const schema = typeof meta['schema'] === 'string' ? meta['schema'] as string : undefined
+  if( !schema ) return null
+
+  const over = Array.isArray( meta['over'] )
+    ? ( meta['over'] as unknown[] ).filter( ( x ): x is string => typeof x === 'string' )
+    : undefined
+
+  return {
+    schema,
+    targetEntityId: typeof meta['targetEntityId'] === 'string' ? meta['targetEntityId'] as string : undefined,
+    ...( over && over.length > 0 ? { over } : {} ),
+    tick:      typeof meta['tick']      === 'number' ? meta['tick']      as number : 0,
+    expiresAt: typeof meta['expiresAt'] === 'number' ? meta['expiresAt'] as number : 0,
+  }
+}
+
+/** The live (unexpired) settlements in frozen state, in stable id order. */
+export function liveSettlements(
+  entities: ReadonlyMap<string, { type: string; metadata?: ReadonlyMap<string, unknown> | Record<string, unknown> }>,
+  tick:     Tick,
+  /**
+   * alias id → anchor id. Settlement is keyed exactly as satiation is — see the
+   * note on `settlementForce` — so it has to share satiation's id space too, or a
+   * verdict reached about a person under one id would not hold about them under
+   * the other. A function, not the table: see `liveConsequences`.
+   */
+  canon?: ( id: string ) => string,
+): SettlementDescriptor[] {
+  const out: Array<{ id: string; d: SettlementDescriptor }> = []
+
+  for( const [ id, e ] of entities ){
+    if( e.type !== SETTLEMENT_TYPE ) continue
+    const d = readSettlement( e.metadata )
+    if( !d ) continue
+    // Stamped LATER than now ⇒ restored from a previous session, where the tick
+    // counter restarts at 1 on wake. Without this a woken mind reads every
+    // settlement it ever made as freshly decided and cannot deliberate at all.
+    // The same trap `liveConsequences` documents, and the same fix.
+    if( d.tick > tick ) continue
+    if( tick < d.expiresAt )
+      out.push({ id, d: canon && d.targetEntityId
+        ? { ...d, targetEntityId: canon( d.targetEntityId ) }
+        : d })
+  }
+
+  return out.sort( ( a, b ) => ( a.id < b.id ? -1 : a.id > b.id ? 1 : 0 ) ).map( x => x.d )
+}
+
+/** Settlement ids that have aged out — swept by the DeliberationEngine. */
+export function expiredSettlementIds(
+  entities: ReadonlyMap<string, { type: string; metadata?: ReadonlyMap<string, unknown> | Record<string, unknown> }>,
+  tick:     Tick,
+): string[] {
+  const out: string[] = []
+  for( const [ id, e ] of entities ){
+    if( e.type !== SETTLEMENT_TYPE ) continue
+    const d = readSettlement( e.metadata )
+    if( d && tick >= d.expiresAt ) out.push( id )
+  }
+  return out
+}
+
+/**
+ * How much of a verdict on this (schema, target) is still standing, 1 → 0.
+ *
+ * Linear decay over the window, matching `enactionFootprint` — the two are
+ * mirror images and should feel the same from inside: one is the fading pull
+ * not to repeat an act, this is the fading weight of having already chosen.
+ *
+ * An objectless act matches an objectless settlement only. Deciding to `rest`
+ * says nothing about whether to `reach-out` to Ada, and a verdict that leaked
+ * across objects would be a mind that mistakes one question for another.
+ */
+export function settlementForce(
+  settlements:    readonly SettlementDescriptor[],
+  schema:         string,
+  targetEntityId: string | undefined,
+  tick:           Tick,
+  windowTicks:    number = SETTLEMENT_TTL_TICKS,
+): number {
+  if( windowTicks <= 0 ) return 0
+
+  let strongest = 0
+  for( const s of settlements ){
+    if( s.schema !== schema || s.targetEntityId !== targetEntityId ) continue
+    const remaining = ( windowTicks - ( tick - s.tick ) ) / windowTicks
+    if( remaining > strongest ) strongest = remaining
+  }
+
+  return strongest < 0 ? 0 : strongest > 1 ? 1 : strongest
+}

package/src/cognition/agency/types.ts

@@ -118,7 +118,7 @@ export interface Affordance {
   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). */
+  /** Entity id of the percept / known-entity that evoked this. */
   evokedBy?:       string
   /** Anticipated affective outcome −1..1 (learned, falling back to schema prior). */
   expectedValence: number
@@ -184,6 +184,26 @@ export interface Affordance {
    * each time as though it were the first.
    */
   justEnacted?:    number
+  /**
+   * How much of a DELIBERATED verdict on this act is still standing, 1 → 0.
+   *
+   * The mirror of `justEnacted`: that one is the fading pull not to repeat
+   * something done, this is the fading weight of having already chosen. Set
+   * when System 2 resolved a contest in this act's favour and the settlement
+   * has not yet aged out.
+   *
+   * It does two things with one quantity, which is why it is a quantity and not
+   * a flag. The verdict gets force, so System 1 does not coin-flip its way to a
+   * different answer on the next tick of the same flat field; and the margin to
+   * the runner-up widens past the selector's gate, so System 2 is not recruited
+   * for a question it has already answered. Flatness is what summons
+   * deliberation — the verdict is what gives the field the shape it lacked.
+   *
+   * Without it, a live COO deliberated 149 times in 7 hours, median 17s apart,
+   * re-reaching the same conclusion about an externally-blocked goal until she
+   * wrote "this is a fact, not a diagnosis I need to reach again".
+   */
+  settled?:        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. */
@@ -191,6 +211,23 @@ export interface Affordance {
   tick:            number
 }
 
+/**
+ * PlanLink — where an act sits in a plan: the frontier step it serves, if any.
+ * Rides on the `agency.outcome` so the PlanningEngine can advance the step the
+ * act was committed from.
+ *
+ * NAMED, AND NAMED THIS, BECAUSE IT USED TO BE CALLED `provenance`
+ * (SIGNAL_BOUNDARY P3). Two unrelated concepts shared that word in one codebase:
+ * this one, and `SignalProvenance` — whether a signal came from the world or
+ * from the mind's own act. The signal sense is the one the vocabulary needs, so
+ * this one gives the word up. An inline `{ planId?, stepId? }` in three
+ * signatures is also how the collision stayed invisible; a name can be grepped.
+ */
+export interface PlanLink {
+  planId?: string
+  stepId?: string
+}
+
 /**
  * EfferenceCopy — the forward model's prediction of an action's own consequences,
  * emitted *before* enaction so reafference has something to compare against.

package/src/cognition/config.mirror.entities.ts

@@ -103,7 +103,6 @@ export function buildEngineConfigEntities( config: WillConfig, executiveInterval
       params: {
         maxPerceptsPerTick: 50,
         defaultSalience:    0.3,
-        emitPerceptEvents:  1,
       },
     },
     {

package/src/cognition/event.schemas.ts

@@ -74,14 +74,6 @@ globalSchemaRegistry.register({
   },
 })
 
-globalSchemaRegistry.register({
-  type: 'percept.batch.ingested', version: 1,
-  validate( p ){
-    if( !isObj(p) ) return 'payload must be object'
-    return hasNum( p, 'count')
-  },
-})
-
 globalSchemaRegistry.register({
   type: 'social.agents.present', version: 1,
   validate( p ){