@mindot/will 0.9.0 → 0.10.0

package/src/stem/tracts/effector/escalation.lifecycle.ts

@@ -0,0 +1,239 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/effector/escalation.lifecycle.ts
+// ─────────────────────────────────────────────────────────────
+//
+// SIGNAL_BOUNDARY P1a — the escalation seam, extracted verbatim from
+// `effector.controller.ts`. Hold, resolve, expire.
+//
+// An escalation is a Will asking before acting (POLICY_REAFFERENCE P4). The
+// intent is held so the executor stops timing it out, the ask is voiced ONCE,
+// and a host answer later approves (dispatch the withheld payload) or denies
+// (refuse it). Unanswered, it degrades to a light refusal at the TTL.
+//
+// `_voiceEscalation` is here for now and does not belong here — see the note on
+// the method. Moving it is P1a's third bullet, not this cut.
+
+import { logger } from '#core/logger'
+// The record type, not a string literal: `## What I've Said Lately` is built by
+// reading it, and a second spelling here would be a contract kept in two places.
+import { SENT_TYPE } from '#agency/conversation.aim'
+import type { WillInstance } from '#stem/index'
+import {
+  ESCALATION_TTL_TICKS,
+  type EffectorOps, type Escalation, type PendingResolution,
+} from './types'
+
+/** What the lifecycle needs from the seams either side of it. */
+export interface EscalationDeps extends EffectorOps {
+  /** Queue a refusal on the policy side — a denial or an expiry. */
+  queueRefusal(
+    instance: WillInstance, intentId: string, schema: string,
+    reasonCode: string, finality: 'class' | 'parameter' | 'context',
+  ): void
+}
+
+export class EscalationLifecycle {
+  /** Escalations awaiting their first application (mark intent + voice the ask). */
+  private _newEscalations   = new Map<string, Escalation[]>()
+  /** Escalations currently held, keyed by intent id — the resolvable set. */
+  private _activeEscalations = new Map<string, Map<string, Escalation>>()
+  /** Host answers awaiting application at the next tick boundary. */
+  private _pendingResolutions = new Map<string, PendingResolution[]>()
+
+  constructor( private readonly _deps: EscalationDeps ){}
+
+  /** Raise a new escalation, applied (marked + voiced) at the next boundary.
+   *  Called by policy enforcement when a verdict says 'escalate'. */
+  raise( instance: WillInstance, esc: Escalation ): void {
+    const escalations = this._newEscalations.get( instance.config.id ) ?? []
+    escalations.push( esc )
+    this._newEscalations.set( instance.config.id, escalations )
+  }
+
+  /**
+   * Record a host's answer to an escalation (POLICY_REAFFERENCE P4). Applied at
+   * the next tick boundary so every simulation-state write stays on the boundary:
+   * approve dispatches the held invocation to the world; deny refuses it. A
+   * no-op if the intent id is not (or no longer) an active escalation.
+   */
+  resolve( instance: WillInstance, intentId: string, approved: boolean ): void {
+    const queue = this._pendingResolutions.get( instance.config.id ) ?? []
+    queue.push({ intentId, approved })
+    this._pendingResolutions.set( instance.config.id, queue )
+  }
+
+  /** Apply host answers to active escalations (POLICY_REAFFERENCE P4). */
+  applyResolutions( instance: WillInstance ): void {
+    const queue = this._pendingResolutions.get( instance.config.id )
+    if( !queue || queue.length === 0 ) return
+    this._pendingResolutions.set( instance.config.id, [] )
+
+    const active = this._activeEscalations.get( instance.config.id )
+    for( const { intentId, approved } of queue ){
+      const esc = active?.get( intentId )
+      if( !esc ) continue                        // unknown / already resolved — ignore
+      active!.delete( intentId )
+      this._clearEscalated( instance, intentId ) // release the executor's hold
+      if( approved ){
+        this._deps.buffer( instance, esc.payload )  // dispatch the held invocation now
+        logger.info(`[policy] escalation APPROVED → dispatching "${esc.schema}" intent "${intentId}"`)
+      }
+      else {
+        this._deps.queueRefusal( instance, esc.intentId, esc.schema, esc.reasonCode, 'class')
+        logger.info(`[policy] escalation DENIED → refusing "${esc.schema}" intent "${intentId}"`)
+      }
+    }
+  }
+
+  /**
+   * Degrade escalations no one answered in time into light refusals (P4).
+   *
+   * Finality 'parameter' is chosen for its BEHAVIOUR, not its name: silence is
+   * not literally an argument problem, but the light-dent-with-recovery it
+   * produces is exactly right — a Will whose asks go unanswered should ask
+   * progressively less, and should resume asking if someone starts answering.
+   * 'class' would be a lie (nobody said never) and 'context' would teach
+   * nothing, leaving the mind to escalate forever into an empty room.
+   */
+  expire( instance: WillInstance, tick: number ): void {
+    const active = this._activeEscalations.get( instance.config.id )
+    if( !active || active.size === 0 ) return
+    for( const [ intentId, esc ] of active ){
+      if( tick < esc.expiresAt ) continue
+      active.delete( intentId )
+      this._clearEscalated( instance, intentId )
+      this._deps.queueRefusal( instance, esc.intentId, esc.schema, 'ESCALATION_EXPIRED', 'parameter')
+      logger.info(`[policy] escalation EXPIRED → refusing "${esc.schema}" intent "${intentId}"`)
+    }
+  }
+
+  /** Raise each newly-escalated intent (POLICY_REAFFERENCE P4): mark it held in
+   *  simulation state, voice the ask ONCE, and move it to the resolvable set. */
+  applyNew( instance: WillInstance, tick: number ): void {
+    const pending = this._newEscalations.get( instance.config.id )
+    if( !pending || pending.length === 0 ) return
+    this._newEscalations.set( instance.config.id, [] )
+
+    const active = this._activeEscalations.get( instance.config.id ) ?? new Map<string, Escalation>()
+    for( const esc of pending ){
+      esc.expiresAt = tick + ESCALATION_TTL_TICKS
+      this._markEscalated( instance, esc.intentId, esc.expiresAt )
+      this._voiceEscalation( instance, esc )
+      active.set( esc.intentId, esc )
+    }
+    this._activeEscalations.set( instance.config.id, active )
+  }
+
+  /** Mark the awaiting intent held: the executor stops timing it out (P4). */
+  private _markEscalated( instance: WillInstance, intentId: string, expiresAt: number ): void {
+    const intent = instance.simulation.stateManager.snapshot().entities.get( intentId )
+    if( !intent || intent.type !== 'agency.intent') return
+    instance.simulation.stateManager.setEntity({
+      id:       intent.id,
+      type:     intent.type,
+      metadata: { ...( intent.metadata ?? {} ), escalated: true, escalationExpiresAt: expiresAt },
+    })
+  }
+
+  /** Release the hold so the executor resumes normal timeout for this intent. */
+  private _clearEscalated( instance: WillInstance, intentId: string ): void {
+    const intent = instance.simulation.stateManager.snapshot().entities.get( intentId )
+    if( !intent || intent.type !== 'agency.intent') return
+    const meta = { ...( intent.metadata ?? {} ) } as Record<string, unknown>
+    delete meta['escalated']; delete meta['escalationExpiresAt']
+    instance.simulation.stateManager.setEntity({ id: intent.id, type: intent.type, metadata: meta })
+  }
+
+  /**
+   * Voice the escalation as a first-person broadcast ask — once, at raise time.
+   *
+   * THIS DOES NOT BELONG HERE, and the P1a note says so: speech is the outbox's
+   * job, and an escalation should *ask for* an utterance rather than compose
+   * one. `escalationAsk` below is a string template standing in for a facet
+   * that would say it in the Will's own voice. Left in place by this cut, which
+   * is a pure move — relocating it is a behaviour question about who authors
+   * the words, not a question about where the file boundary goes.
+   */
+  private _voiceEscalation( instance: WillInstance, esc: Escalation ): void {
+    // The SIMULATION clock, not the lifecycle's `tick`.
+    //
+    // Two counters live here and they are thousands apart. `applyPolicyOutcomes`
+    // passes `instance.tickCount` — a process-local counter that starts at 0 on
+    // every boot — and the whole escalation lifecycle is self-consistent in that
+    // space, so nothing else notices. `conversation.sent` is read in SIM-clock
+    // space by `readSpokenTurns` and `spokenAtByEntity`, where the state manager
+    // stamps `updatedAtTick` from the simulation clock.
+    //
+    // Written with the process counter, the ask landed ~17,000 ticks in the past
+    // on a live Will: it still existed, but `readSpokenTurns` sorts oldest-first
+    // and `## What I've Said Lately` keeps only the newest few — so the record
+    // was dropped from the one section it was added to appear in. Found by a live
+    // run, not by the suite: both halves were internally consistent.
+    const tick = instance.simulation.clock.currentTick
+    const content = escalationAsk( esc.schema, esc.reasonCode )
+    try {
+      instance.cognition.outboxWriter.enqueue({
+        targetEntityId: '*',
+        content,
+        effectorName:    'broadcast',
+      })
+    }
+    catch( err ){
+      logger.warn(`[policy] escalation voice failed for "${esc.schema}": ${errMsg( err )}`)
+      return
+    }
+
+    // Words that left the mind have to exist in its record of having said them.
+    //
+    // These did not. The ask goes out through the outbox directly — no intent,
+    // no `_deliver` — so nothing wrote the `conversation.sent` that
+    // `## What I've Said Lately` is built from, and the one thing she could not
+    // see was the one thing she was being asked about. Live: she broadcast
+    // "I want to discord_unban_member … May I go ahead?", was asked who she
+    // meant, and answered "I didn't send that. I've never asked to unban
+    // anyone" — seven times across four minutes, correctly, because from the
+    // inside she never had.
+    //
+    // Recorded AFTER the enqueue and skipped when it throws: a record of speech
+    // that never left is the same fault facing the other way.
+    try {
+      instance.simulation.stateManager.setEntity({
+        // Keyed by schema as well as tick — two intents can escalate on one
+        // tick, and a shared id would leave the mind remembering one ask.
+        id:   `conv-sent-escalation-${ esc.schema }-${ tick }`,
+        type: SENT_TYPE,
+        metadata: {
+          targetEntityId:   '*',
+          // She said it to the room. Naming it the way she would say it keeps
+          // the line readable next to the people in the same list.
+          targetEntityName: 'everyone here',
+          messageCount:     1,
+          preview:          content.slice( 0, 100 ),
+          effectorName:     'broadcast',
+          tick,
+          delivered:        false,
+        },
+      })
+    }
+    catch( err ){ logger.warn(`[policy] escalation record failed for "${esc.schema}": ${errMsg( err )}`) }
+  }
+}
+
+/** First-person ask for an escalated action, carrying the reason's MEANING (P4).
+ *  Kept template-simple here; the facet-authored version is a later refinement. */
+function escalationAsk( schema: string, reasonCode: string ): string {
+  const meaning = ESCALATION_MEANINGS[ reasonCode ] ?? 'I need your approval before I can do this'
+  return `I want to ${ schema }, but ${ meaning }. May I go ahead?`
+}
+
+/** reasonCode → human meaning. Unknown codes fall back to a generic phrase. */
+const ESCALATION_MEANINGS: Record<string, string> = {
+  APPROVAL_REQUIRED: 'I need your approval before I can on my own',
+  WRITE_REQUIRES_APPROVAL: "it writes to the world and I shouldn't on my own",
+  PAYMENT_REQUIRES_APPROVAL: 'it moves money and I must not do that unattended',
+  DEPLOY_REQUIRES_APPROVAL: 'it ships something and needs a human to sign off',
+}
+
+function errMsg( err: unknown ): string {
+  return err instanceof Error ? err.message : String( err )
+}

package/src/stem/tracts/effector/policy.enforcement.ts

@@ -0,0 +1,261 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/effector/policy.enforcement.ts
+// ─────────────────────────────────────────────────────────────
+//
+// SIGNAL_BOUNDARY P1a — the policy seam, extracted verbatim from
+// `effector.controller.ts`. Arbiter, verdicts, refusals.
+//
+// This is the PEP: the Policy Enforcement Point that consults the arbiter (the
+// PDP) before an invocation reaches the world, records the verdict on the tape,
+// and enforces it. A refusal does not raise a dialog — it is reconciled as a
+// failure ack, so the mind meets *world resistance* and learns from it
+// (POLICY_REAFFERENCE P1/P2).
+
+import { logger } from '#core/logger'
+import { NULL_ARBITER, isNullArbiter, finalityOf } from '#stem/policy/arbiter'
+import type {
+  PolicyArbiter, PolicyInvocation, Verdict, DenialFinality,
+} from '#stem/policy/arbiter'
+import {
+  getVerdictRecorder, getVerdictSource, type PolicyVerdictRecord,
+} from '#stem/policy/verdict.recorder'
+import type { WillInstance } from '#stem/index'
+import type { EffectorOps, Escalation, PendingRefusal } from './types'
+
+/**
+ * The verdict a fault produces (POLICY_REAFFERENCE P5, conformance S9).
+ *
+ * An arbiter that throws or rejects has always failed CLOSED — the effect is
+ * withheld — but it used to withhold *silently*, queueing no refusal. The held
+ * intent then expired at the executor's AWAIT_TIMEOUT and reconciled as a plain
+ * failure, landing on COMPETENCE: a PDP outage taught the mind it was unskilled
+ * at something it is perfectly capable of. So a fault now yields a real verdict:
+ *
+ *   • 'deny'    — still fail-closed, unchanged. The effect never reaches the world.
+ *   • 'context' — but it teaches NOTHING. The arbiter being unreachable is not a
+ *                 fact about the ability, so nothing about the ability may move.
+ *
+ * It goes through `_recordAndApply` rather than straight to the refusal queue so
+ * the fault lands on the VERDICT TAPE too. That closes a replay hole: an
+ * unrecorded fault left the source with nothing to re-feed, and a source miss
+ * reproduces a buffered ALLOW — so a live run that withheld the effect would
+ * have replayed as one that dispatched it.
+ */
+const ARBITER_FAULT_VERDICT: Readonly<Verdict> = Object.freeze({
+  decision:   'deny' as const,
+  reasonCode: 'ARBITER_UNAVAILABLE',
+  finality:   'context' as const,
+})
+
+/** What enforcement needs from the seams either side of it. */
+export interface PolicyDeps extends EffectorOps {
+  /** Hand an escalate verdict to the escalation lifecycle. */
+  raiseEscalation( instance: WillInstance, esc: Escalation ): void
+}
+
+export class PolicyEnforcement {
+  /** The Policy Decision Point consulted before an invocation reaches the world.
+   *  Defaults to the no-op arbiter, so an unconfigured Will is byte-identical. */
+  private _arbiter: PolicyArbiter = NULL_ARBITER
+
+  /**
+   * Denials queued during a step's flush, drained at the NEXT tick boundary
+   * (POLICY_REAFFERENCE P1). Keyed by willId — harness state, exactly like
+   * `pendingEffectorInvocations`; never simulation state, so it does not touch
+   * `simulation.step` determinism and is regenerated on any re-execution.
+   */
+  private _pendingRefusals = new Map<string, PendingRefusal[]>()
+
+  constructor( private readonly _deps: PolicyDeps ){}
+
+  /**
+   * Install a Policy Decision Point (POLICY_REAFFERENCE P0). Passing null
+   * restores the no-op default. The arbiter sees only the proposed act — never
+   * simulation state — and its verdict decides whether the invocation is
+   * handed to the host at all.
+   */
+  setArbiter( arbiter: PolicyArbiter | null ): void {
+    this._arbiter = arbiter ?? NULL_ARBITER
+  }
+
+  /**
+   * Consult the PDP for this invocation and enforce the answer. Falls through to
+   * a plain buffer when no policy is configured — the byte-identical fast path.
+   *
+   * `toPolicyInvocation` is supplied by the caller so the projection onto the
+   * policy boundary stays with the translation seam that owns the payload shape.
+   */
+  evaluate(
+    instance: WillInstance,
+    payload:  Record<string, unknown>,
+    project:  ( instance: WillInstance, payload: Record<string, unknown> ) => PolicyInvocation,
+  ): void {
+    const willId = instance.config.id
+
+    // Replay: a registered source re-feeds the recorded verdict instead of
+    // re-consulting a live (or absent) PDP — the arbiter is an external oracle,
+    // exactly like the LLM. Checked FIRST so replay never re-enters the arbiter.
+    const source = getVerdictSource( willId )
+    if( source ){
+      const invocation = project( instance, payload )
+      const record     = source.verdictFor( invocation.tick, invocation.intentId )
+      // A miss means the live run had no verdict here (null arbiter at record
+      // time) — the invocation was simply buffered, so reproduce that.
+      if( record ) this._applyVerdict( instance, payload, invocation, recordToVerdict( record ) )
+      else         this._deps.buffer( instance, payload )
+      return
+    }
+
+    // Fast path: no policy configured ⇒ the seam does not exist. No allocation,
+    // no branch beyond this one — the byte-identical guarantee.
+    if( isNullArbiter( this._arbiter ) ){
+      this._deps.buffer( instance, payload )
+      return
+    }
+
+    const invocation = project( instance, payload )
+    let verdict: Verdict | Promise<Verdict>
+
+    // An arbiter that throws must never become an implicit allow.
+    try { verdict = this._arbiter.evaluate( invocation ) }
+    catch( err ){
+      logger.error(`[policy] arbiter "${this._arbiter.name}" threw for "${invocation.schema}" — failing closed:`, err )
+      this._recordAndApply( instance, payload, invocation, ARBITER_FAULT_VERDICT )
+      return
+    }
+
+    if( verdict instanceof Promise ){
+      // An external PDP resolves out of tick. Safe by construction: the executor
+      // holds the intent 'awaiting' for AWAIT_TIMEOUT (15 ticks), and the refusal
+      // queue drains each tick, so a verdict landing a few ticks late still lands.
+      void verdict.then(
+        v => this._recordAndApply( instance, payload, invocation, v ),
+        err => {
+          logger.error(`[policy] arbiter "${this._arbiter.name}" rejected for "${invocation.schema}" — failing closed:`, err )
+          this._recordAndApply( instance, payload, invocation, ARBITER_FAULT_VERDICT )
+        },
+      )
+      return
+    }
+
+    this._recordAndApply( instance, payload, invocation, verdict )
+  }
+
+  /** Capture the verdict on the tape (if a recorder is attached), then enforce it. */
+  private _recordAndApply(
+    instance:   WillInstance,
+    payload:    Record<string, unknown>,
+    invocation: PolicyInvocation,
+    verdict:    Verdict,
+  ): void {
+    const sink = getVerdictRecorder( instance.config.id )
+    sink?.recordVerdict({
+      tick:       invocation.tick,
+      willId:     instance.config.id,
+      intentId:   invocation.intentId,
+      schema:     invocation.schema,
+      arbiter:    this._arbiter.name,
+      decision:   verdict.decision,
+      ...( verdict.reasonCode     ? { reasonCode:     verdict.reasonCode     } : {} ),
+      ...( verdict.finality       ? { finality:       verdict.finality       } : {} ),
+      ...( verdict.counterfactual ? { counterfactual: verdict.counterfactual } : {} ),
+      timestamp:  Date.now(),
+    })
+    this._applyVerdict( instance, payload, invocation, verdict )
+  }
+
+  /**
+   * Enforce a verdict (POLICY_REAFFERENCE P1). THE ROUTER, and the one method
+   * that reaches across both seams by design:
+   *
+   *   • allow    → hand the invocation to the world.
+   *   • deny     → queue a refusal ack, applied at the next tick boundary via
+   *                `confirmExecution` — the same lifecycle as a host rejection,
+   *                so the mind meets *world resistance*, not a permission dialog.
+   *   • escalate → raise a held escalation (POLICY_REAFFERENCE P4): the intent is
+   *                held (the executor stops timing it out), the Will voices a
+   *                first-person ask once, and a host resolution later approves
+   *                (dispatch) or denies (refuse). Unresolved, it degrades to a
+   *                refusal at ESCALATION_TTL_TICKS.
+   *
+   * P1's refusal reconciles as a plain FAILURE — safe, but the wrong learning
+   * signal (forbidden ≠ unskilled). P2 routes it to affordance AVAILABILITY
+   * instead of competence.
+   */
+  private _applyVerdict(
+    instance:   WillInstance,
+    payload:    Record<string, unknown>,
+    invocation: PolicyInvocation,
+    verdict:    Verdict,
+  ): void {
+    if( verdict.decision === 'allow'){
+      this._deps.buffer( instance, payload )
+      return
+    }
+
+    const cf = verdict.counterfactual
+    logger.info(
+      `[policy] ${verdict.decision.toUpperCase()} "${invocation.schema}" intent "${invocation.intentId}"` +
+      ` — ${verdict.reasonCode ?? 'no reason code'}` +
+      ( verdict.finality ? ` (${verdict.finality})` : '') +
+      ( cf ? ` [${cf.field}: requested ${JSON.stringify( cf.requested )}, allowed ${JSON.stringify( cf.allowed )}]` : ''),
+    )
+
+    if( verdict.decision === 'deny'){
+      const queue = this._pendingRefusals.get( instance.config.id ) ?? []
+      queue.push({
+        intentId:   invocation.intentId,
+        schema:     invocation.schema,
+        reasonCode: verdict.reasonCode ?? 'POLICY_DENIED',
+        finality:   finalityOf( verdict ),
+        ...( verdict.counterfactual ? { counterfactual: verdict.counterfactual } : {} ),
+      })
+      this._pendingRefusals.set( instance.config.id, queue )
+      return
+    }
+
+    // 'escalate' — raise a held escalation, applied (marked + voiced) at the boundary.
+    this._deps.raiseEscalation( instance, {
+      intentId:   invocation.intentId,
+      schema:     invocation.schema,
+      reasonCode: verdict.reasonCode ?? 'APPROVAL_REQUIRED',
+      payload,
+      expiresAt:  0,   // stamped when applied (we don't have the current tick here)
+    } )
+  }
+
+  /** Push a refusal onto the queue drained by `applyRefusals` this same tick. */
+  queueRefusal(
+    instance: WillInstance, intentId: string, schema: string, reasonCode: string, finality: DenialFinality,
+  ): void {
+    const queue = this._pendingRefusals.get( instance.config.id ) ?? []
+    queue.push({ intentId, schema, reasonCode, finality })
+    this._pendingRefusals.set( instance.config.id, queue )
+  }
+
+  /** Drain queued refusals into failure acks (POLICY_REAFFERENCE P1). */
+  applyRefusals( instance: WillInstance ): void {
+    const queue = this._pendingRefusals.get( instance.config.id )
+    if( !queue || queue.length === 0 ) return
+    this._pendingRefusals.set( instance.config.id, [] )
+
+    for( const refusal of queue )
+      this._deps.confirmExecution( instance, refusal.intentId, {
+        success:     false,
+        refused:     true,
+        finality:    refusal.finality,
+        ...( refusal.counterfactual ? { counterfactual: refusal.counterfactual } : {} ),
+        description: `refused by policy: ${refusal.reasonCode} (${refusal.finality})`,
+      } )
+  }
+}
+
+/** Reconstruct an enforceable Verdict from a recorded verdict (replay path). */
+function recordToVerdict( record: PolicyVerdictRecord ): Verdict {
+  return {
+    decision: record.decision,
+    ...( record.reasonCode     ? { reasonCode:     record.reasonCode     } : {} ),
+    ...( record.finality       ? { finality:       record.finality       } : {} ),
+    ...( record.counterfactual ? { counterfactual: record.counterfactual } : {} ),
+  }
+}

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

@@ -0,0 +1,110 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/effector/types.ts  —  the efference crossing, shared shapes
+// ─────────────────────────────────────────────────────────────
+//
+// SIGNAL_BOUNDARY P1a. `effector.controller.ts` had seven jobs; these are the
+// shapes its three real seams pass between them:
+//
+//   policy enforcement   arbiter · verdicts · refusals
+//   escalation lifecycle hold · resolve · expire
+//   agency↔host          buffer · drain · ack   (the controller itself)
+//
+// The seams were verified before the cut, not assumed: no method touched both
+// the policy fields (`_arbiter`, `_pendingRefusals`) and the escalation fields
+// (`_newEscalations`, `_activeEscalations`, `_pendingResolutions`) except
+// `_applyVerdict`, which is the ROUTER — deny goes one way, escalate the other.
+// A router across a seam is the seam working, not a tangle.
+
+import type { DenialFinality, PolicyCounterfactual } from '#stem/policy/arbiter'
+import type { WillInstance } from '#stem/index'
+
+/** A denial awaiting application as a refusal ack at the next tick boundary. */
+export interface PendingRefusal {
+  intentId:   string
+  schema:     string
+  reasonCode: string
+  finality:   DenialFinality
+  /** ENVELOPE_NARROWING P0 — what WOULD have been allowed, carried through to
+   *  the outcome the mind learns from. Absent on refusals that have no bound to
+   *  report (a flat ban, a fault, an unanswered escalation). */
+  counterfactual?: PolicyCounterfactual
+}
+
+/** An escalation the Will has raised: the intent is held, the ask is voiced once,
+ *  and the original payload is kept so an approval can dispatch it to the world. */
+export interface Escalation {
+  intentId:   string
+  schema:     string
+  reasonCode: string
+  /** The withheld invocation payload — replayed to the host on approval. */
+  payload:    Record<string, unknown>
+  expiresAt:  number
+}
+
+/** A host's answer to an escalation, applied at the next tick boundary. */
+export interface PendingResolution {
+  intentId: string
+  approved: boolean
+}
+
+/** What a host says came back. */
+export interface EffectorAck {
+  success:     boolean
+  /**
+   * How the act WENT. The fate of the attempt — landed, refused, failed — which
+   * is what the mind learns competence from. Not what the act revealed.
+   */
+  description: string
+  /**
+   * What the act REVEALED: new information about the world, as distinct from how
+   * the act went (SIGNAL_BOUNDARY P2).
+   *
+   * Present ⇒ this ack is ALSO afference. It arrives as a reafferent percept
+   * carrying `sourceIntentId`, so the mind perceives it, remembers it and can
+   * recall it — rather than only learning from it. `lookup`, `list_warnings`,
+   * `snapshot` carry one; `kick`, `warn`, a refusal do not.
+   *
+   * WHY THE HOST DECIDES, AND WHY THIS IS NOT INFERRED FROM `description`.
+   * An ack is not *always* new world information, and nothing inside the mind
+   * can tell "the kick landed" from "there are 47 people here" — both are
+   * strings that came back from an act. Only the host knows which it wrote.
+   * Same contract as `provenance`: asserted at the boundary, never guessed.
+   *
+   * Forcing every ack through the sense door would be the over-unification this
+   * epoch warns about — a mind perceiving "the kick landed" as a fresh event in
+   * the world, every time it kicks.
+   *
+   * ANY SHAPE, AND CARRIED WHOLE. A host with a member record, a channel
+   * snapshot, a list of warnings sends the record — not a paragraph about it.
+   * Making a host flatten its own data to prose is a quieter kind of cutting:
+   * it destroys the structure rather than the tail. Nothing here is truncated
+   * at any point on the way in; what the host sent is what the mind gets.
+   */
+  observation?: unknown
+  metrics?:    Record<string, number>
+  /** POLICY_REAFFERENCE P2 — set when the ack is a policy refusal, so the
+   *  ReafferenceEngine routes it to availability rather than competence. */
+  refused?:    boolean
+  finality?:   DenialFinality
+  /** ENVELOPE_NARROWING P0 — the bound that was exceeded, if the arbiter said. */
+  counterfactual?: PolicyCounterfactual
+}
+
+/**
+ * The translation seam, as the other two see it.
+ *
+ * Both collaborators need to put an invocation on the wire, and policy also
+ * needs to reconcile a refusal as an ack. Injected as plain functions rather
+ * than a controller reference: it keeps the dependency one-way at the type
+ * level, and it is what lets the controller wire a cycle (policy raises an
+ * escalation, an escalation queues a refusal) without either class importing
+ * the other.
+ */
+export interface EffectorOps {
+  buffer( instance: WillInstance, payload: Record<string, unknown> ): void
+  confirmExecution( instance: WillInstance, invocationId: string, result: EffectorAck ): void
+}
+
+/** How long an escalated intent is held awaiting a resolution before it degrades
+ *  to a refusal — 2× the host-ack timeout, so a human has real time to answer. */
+export const ESCALATION_TTL_TICKS = 30