@sema-agent/core 7.5.1 → 7.6.0

package/dist/core/checkpoint-store.d.ts

@@ -1,3 +1,4 @@
+import type { CheckpointPause } from "./pause-registry.js";
 import type { SystemInjectionPriority } from "./task-notification.js";
 import { type QuestionAnswer } from "./ask-question.js";
 import type { ReadEntry } from "../tools/fs/safety.js";
@@ -439,10 +440,21 @@ export declare function buildRiskDescriptor(input: {
  * refuses to redeem such a row (the governed boundary must not vanish with a deployment's wiring).
  */
 export interface RealApprovalGateBit {
-    /** The three members of the closed ask-origin set that can mint the bit — derived FROM that set, so
-     *  the two vocabularies cannot drift into two spellings of one word. */
-    origin: Extract<import("./ask-origin.js").AskOrigin, "org_rule" | "org_unavailable" | "policy">;
+    /** The parked ask's ORIGIN word — a projection of the same closed set the card, the observer and the
+     *  `tool_end` frame carry ({@link import("./ask-origin.js").AskOrigin}), never a second vocabulary. It
+     *  is the ask's ROUTING word: a marked call reads `unresolvable` even when the org governs it, because
+     *  the ladder routes a marked call to the park before anything else. Rows minted before the projection
+     *  carried a three-word subset of this set (`org_rule` / `org_unavailable` / `policy`), so every stored
+     *  value is still a member. */
+    origin: import("./ask-origin.js").AskOrigin;
+    /** The ORG FACT the ask was minted under (`"rule"` = an org rule asked, `"unavailable"` = org adjudication
+     *  unreachable), kept beside the routing word because routing can outrank the word (a marked call reads
+     *  `unresolvable`) while the governance stays. The #120 governed mark and the resume belts read THIS
+     *  member through {@link realApprovalOrgFact} (absent on rows minted before it: the org words imply it). */
+    org?: "rule" | "unavailable";
 }
+/** The ONE read of a bit's governed fact (the member; the two org origin words for rows minted before it). */
+export declare function realApprovalOrgFact(bit: RealApprovalGateBit | undefined): "rule" | "unavailable" | undefined;
 export type CheckpointGate = 
 /** F4: a human (or any external authority) must allow/deny a pending tool call. design/80 §D-E:
  *  carries an OPTIONAL display-only {@link RiskDescriptor} (severity/axes/summary) for the supervisor
@@ -594,66 +606,38 @@ export type ResumeOutcome = {
      */
     answer?: QuestionAnswer;
     /**
-     * WHAT ENDED THIS APPROVAL — `"human"` (a person gave the final verdict), `"timeout"` (the
-     * configured window elapsed with no answer), or `"aborted"` (every other non-human end: the run
-     * was cancelled, the connection dropped, the store gave way, retries ran out). See
-     * {@link import("./tool-policy.js").ApprovalSettledBy} for the vocabulary itself.
+     * The host's DECISION FACTS — who ended this wait: a person (`"person"`, the decide an operator made
+     * through the deployment's approval channel, with the attribution that channel reports), or the
+     * host's own SLA sweep at the row's deadline (`"sla_timeout"` — FACET A of the deadline contract; only
+     * a sweep may say it, and a sweep cannot `allow`). REQUIRED: a decide that names nobody is not a
+     * record of anything that happened, and core does not guess.
      *
-     * Attribution travels WITH the decision because it is a property OF the decision, not something
-     * a later reader can reconstruct: by the time an approval reaches a consumer, "denied" and "the
-     * window closed" have already collapsed into the same `decision:"deny"`, and only the caller that
-     * settled it still knows which happened. Core does not derive it, does not default it, and never
-     * infers it from some other outcome — it carries what the settling caller wrote onto the
-     * `tool_end` frame of the call this resume resolves.
+     * The host supplies FACTS, never the settlement WORD: core mints the record
+     * ({@link import("./gate-outcome.js").GateOutcome} — `human_allowed` / `human_refused` / `park_sla_expired`,
+     * joined with the row's persisted `origin`) at the resume entry, writes it onto the resolved row
+     * (`resolvedOutcome.gateOutcome`) and projects it onto the resolved call's `tool_end` frame. A caller
+     * that supplies `gateOutcome` itself is refused pre-CAS.
      *
-     * **Fill it at every settlement site.** A deployment resolving an approval from several places
-     * (an operator decide, an SLA sweep at the deadline, a cancel path) names the cause at each of
-     * them. Deriving it once, centrally, from the last outcome at hand is precisely how a window that
-     * elapsed gets reported to a person as another person's refusal.
+     * `approver` — the attribution the approval channel reports for the party that ended the wait. Core
+     * AUTHENTICATES NOTHING: the identity work is the deployment's (its card, its signature check, its
+     * console). What core owns is that the claim is well-formed: a plain string, bounded, free of control
+     * characters, refused pre-CAS (`checkpoint.invalid_outcome`) otherwise — refused rather than dropped,
+     * because a settlement that silently lost its attributed party reads as unattributed.
      *
-     * OPTIONAL and additive: absent means the caller named no source (a caller written before this
-     * field existed), and a consumer must NOT read a semantic out of the absence — core neither
-     * substitutes a default nor guesses. A value outside the three words is refused pre-CAS
-     * (`checkpoint.invalid_outcome`), like every other out-of-domain field on this arm: a settlement
-     * source nobody can read is worse than none at all. So is one that contradicts its own decision:
-     * `decision:"allow"` accepts only `"human"` or omission, because "nobody answered, therefore it
-     * ran" is not a record of anything that happened (a deployment whose CONFIGURATION auto-allows an
-     * elapsed window omits the field — no one ended that wait).
-     *
-     * SCOPE — this rides the settlement, NOT the persisted winner: `winnerFromOutcome` records the
-     * decision (and its rewrite/answer/reason), which is what an `env_failed` replay must reproduce
-     * exactly, and the source is not part of that authorization. A replay therefore states its own
-     * source and is not held to the first one. Binding it into the persisted winner would also make a
-     * re-supply that merely OMITS the field fail closed on the recovery path, which is the wrong place
-     * to add a new refusal; carrying it into the durable row is a store-shape change owned jointly
-     * with the backends and belongs to its own change, not to this one.
+     * SCOPE — the facts ride the settlement, not the persisted winner: `winnerFromOutcome` records what an
+     * `env_failed` replay must reproduce exactly, and who reported a settlement is not part of that
+     * authorization; a replay states its own facts.
      */
-    settledBy?: import("./tool-policy.js").ApprovalSettledBy;
+    hostDecision: {
+        decidedBy: "person" | "sla_timeout";
+        approver?: string;
+    };
     /**
-     * design/252 G-7 — WHOSE settlement: the identifier the approval channel reports for the party
-     * that ended this wait, transcribed onto the resolved call's `tool_end` frame beside
-     * {@link settledBy}.
-     *
-     * Core AUTHENTICATES NOTHING here. On the durable lane the identity work is entirely the
-     * deployment's — its approval card, its signature check, its operator console decide who this
-     * was; a library holding no identity surface has nothing to check the claim against and does not
-     * pretend otherwise. What core owns is that the claim is well-formed: a plain string, bounded,
-     * free of control characters, refused pre-CAS (`checkpoint.invalid_outcome`) otherwise, like
-     * every other out-of-domain field on this arm. Refused rather than dropped, because a settlement
-     * that silently lost its attributed party reads as unattributed — the misreport this seat exists
-     * to end.
-     *
-     * SCOPE — like {@link settledBy}, this rides the SETTLEMENT and not the persisted winner:
-     * `winnerFromOutcome` records what an `env_failed` replay must reproduce exactly, and who
-     * reported a settlement is not part of that authorization. A replay states its own attribution
-     * and is not held to the first one; binding it into the durable row would also make a re-supply
-     * that merely omits the field fail closed on the recovery path. Carrying it into the row is a
-     * store-shape change owned jointly with the backends and belongs to its own change.
-     *
-     * OPTIONAL and additive: absent means the caller named nobody, which is not the same as "nobody
-     * approved this" and must not be read as one.
+     * CORE-MINTED, on the persisted twin only: the settlement record this decide produced. Present on
+     * the row's `resolvedOutcome` after the resolve, and on the `tool_end` frame of the resolved call.
+     * Never accepted from a caller (refused pre-CAS) — the host does not mint words.
      */
-    approver?: string;
+    gateOutcome?: import("./gate-outcome.js").GateOutcome;
 }
 /** design/74: continue a resource-suspended run with the next slice's allowance. NO decision payload and
  *  NO budget figure — the allowance is computed from {@link Checkpoint.resourceLedger}, so money never
@@ -874,6 +858,13 @@ export type PendingAction = {
     kind: "resource_limit";
     reason: ResourceLimitReason;
 }
+/** design/76 §2.5: paused at a POST-PREDICTION REVIEW (`CheckpointGate.kind === "needs_review"`). There is NO
+ *  pending tool to resolve — a human/judge reviews the buffered predicted state-diff (a PROFILE-held REF, never
+ *  stored here) — so this arm has no fields. Its OWN member: before the pause registry a `needs_review` row
+ *  borrowed another arm's seat, and the gate × pendingAction pairing lived in a comment. */
+ | {
+    kind: "review";
+}
 /** design/80 D-B (r3 — an EXPLICIT arm, NOT a reused `resource_limit` placeholder): paused at a PRE-ACTION
  *  PLAN REVIEW (`CheckpointGate.kind === "plan_review"`). There is NO pending tool to resolve — the human
  *  reviews the PLAN, not a tool call — so this arm has no tool fields. Every consumer that reads the
@@ -1496,6 +1487,11 @@ export interface ResolvedOutcome {
      *  the same decision" for no delivery benefit, since a replay is produced by re-presenting the same
      *  outcome, not by reconstructing an equivalent one. */
     reason?: string;
+    /** The settlement record core minted for this decide ({@link import("./gate-outcome.js").GateOutcome}):
+     *  the row's own copy of what the resolved call's `tool_end` frame carries, written with the winner so
+     *  an audit reading the row reads the same record the stream carried. NOT part of the replay equality
+     *  (`when` differs per replay; the record is a consequence of the decision, not its substance). */
+    gateOutcome?: import("./gate-outcome.js").GateOutcome;
 }
 /**
  * design/80 D-1: why a consumed checkpoint was {@link CheckpointStore.reopen | reopened} (resolved →
@@ -1579,7 +1575,9 @@ export type TerminalClaimOutcome = {
 };
 /** A persisted suspension point: enough to resume a task on any replica. `status` drives the 3-state
  *  machine (pending → resolved | expired) that makes resume idempotent (§5). */
-export interface Checkpoint {
+/** A durable checkpoint: the row's fields ({@link CheckpointRow}) plus its registry-bound pause pair. */
+export type Checkpoint = CheckpointRow & CheckpointPause;
+export interface CheckpointRow {
     token: CheckpointToken;
     /** Non-secret stable identity ({@link mintCheckpointId}) — the display/correlation twin of
      *  the secret `token` (identification vs capability, separate axes). Present on every row minted
@@ -1600,8 +1598,6 @@ export interface Checkpoint {
     sessionId: string;
     /** The session leaf the suspend happened at — the resume point (CAS write base, §5). */
     leafId: string;
-    gate: CheckpointGate;
-    pendingAction: PendingAction;
     state: CheckpointState;
     /** design/74 R3-B: cross-slice resource accounting. Present for a `resource_limit` gate (debited at the
      *  suspend's `put`; read on resume to size the next slice + aggregate the final stats). **design/80 D-E-core
@@ -2075,15 +2071,15 @@ export declare class CheckpointError extends Error {
      *  re-fetch the pending list), `"boundInputHash"` (the input you reviewed has changed under the same
      *  action: re-review), or `"answer"` (the content-ask answer is missing, or was attached to a
      *  decision that cannot carry one: re-decide with a well-formed answer — ruled 2026-08-04), or
-     *  `"settledBy"` (the settlement source is outside the three-word vocabulary: re-decide naming one
-     *  of them, or omit the field), or — design/252 G-7 — `"approver"` (the attribution is not a
+     *  `"hostDecision"` (the decision facts are missing, name a decider outside `person`/`sla_timeout`, pair
+     *  an SLA timeout with an allow, or try to supply the minted word), or — design/252 G-7 — `"approver"` (the attribution is not a
      *  well-formed identifier: re-decide with a plain, bounded, control-character-free string, or omit
      *  it). The throw
      *  sites always knew which arm fired; this carries that fact instead of dropping it (ruled
      *  2026-08-03, cross-repo HITL discussion). Additive and optional — `code` remains the only REQUIRED
      *  discriminant. */
     readonly detail?: {
-        field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy" | "approver";
+        field?: "boundCallId" | "boundInputHash" | "answer" | "hostDecision" | "approver";
         /** #449 G1 — on `resume.usage_window_exhausted`: how long until the binding window frees
          *  (the same wait a suspended row carries as `gate.resumeAfterMs`). design/380 O2 — on a
          *  retry-later `resume.preflight_rejected`: the deployment preflight's own wait hint, when it
@@ -2257,15 +2253,15 @@ export declare class CheckpointError extends Error {
      *  re-fetch the pending list), `"boundInputHash"` (the input you reviewed has changed under the same
      *  action: re-review), or `"answer"` (the content-ask answer is missing, or was attached to a
      *  decision that cannot carry one: re-decide with a well-formed answer — ruled 2026-08-04), or
-     *  `"settledBy"` (the settlement source is outside the three-word vocabulary: re-decide naming one
-     *  of them, or omit the field), or — design/252 G-7 — `"approver"` (the attribution is not a
+     *  `"hostDecision"` (the decision facts are missing, name a decider outside `person`/`sla_timeout`, pair
+     *  an SLA timeout with an allow, or try to supply the minted word), or — design/252 G-7 — `"approver"` (the attribution is not a
      *  well-formed identifier: re-decide with a plain, bounded, control-character-free string, or omit
      *  it). The throw
      *  sites always knew which arm fired; this carries that fact instead of dropping it (ruled
      *  2026-08-03, cross-repo HITL discussion). Additive and optional — `code` remains the only REQUIRED
      *  discriminant. */
     detail?: {
-        field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy" | "approver";
+        field?: "boundCallId" | "boundInputHash" | "answer" | "hostDecision" | "approver";
         /** #449 G1 — on `resume.usage_window_exhausted`: how long until the binding window frees
          *  (the same wait a suspended row carries as `gate.resumeAfterMs`). design/380 O2 — on a
          *  retry-later `resume.preflight_rejected`: the deployment preflight's own wait hint, when it
@@ -2674,22 +2670,28 @@ export interface CheckpointStore {
  * The SINGLE resolution of "which CheckpointStore does this run use" (ruled 2026-08-04; re-homed
  * from prepare-task with the design/173 wiring manifest so the static self-check half shares it
  * without a runtime cycle). The spec seat is three-valued — a store wins, `undefined` falls through
- * to the deployment's `RunnerDeps.checkpointStore`, and an explicit `null` means this run has NO
- * store at all (see `TaskSpec.checkpointStore`: the per-run off switch for the durable machine, so
- * a machine-started run cannot mint a checkpoint nobody will ever resolve).
+ * to the deployment's `RunnerDeps.checkpointStore`, and the explicit word `"disabled"` means this run
+ * has NO store at all (see `TaskSpec.checkpointStore`: the per-run off switch for the durable
+ * machine, so a machine-started run cannot mint a checkpoint nobody will ever resolve).
  *
- * Written as an explicit `=== null` test rather than the obvious `spec.checkpointStore ??
- * deps.checkpointStore` BECAUSE `??` treats `null` exactly like `undefined`: under a bare nullish
- * coalesce the null falls through and the run is handed the very deployment store the caller asked
- * it not to have, re-arming every suspend leg — silently, since the resulting run looks perfectly
- * normal right up until it parks forever. Every read of the pair goes through here so that trap has
- * ONE place to be wrong instead of nine.
+ * The off switch is a WORD, not `null`, on purpose: `??` treats `null` exactly like `undefined`, so
+ * the old null sentinel silently fell through a bare coalesce to the very deployment store the
+ * caller asked not to have — re-arming every suspend leg while the run looked perfectly normal right
+ * up until it parked forever — and every read of the pair had to remember a special `=== null` test.
+ * A string is never nullish, so the ordinary coalesce is the whole rule. The retired spelling is
+ * REFUSED loudly here (the one read every site goes through) rather than read as either value: a
+ * caller still writing `null` is told the word to write, at the first prepare, instead of being
+ * handed a store it asked not to have or a silent off switch it did not spell.
  */
 export declare function resolveCheckpointStore(spec: {
-    checkpointStore?: CheckpointStore | null;
+    checkpointStore?: CheckpointStore | "disabled";
 }, deps: {
     checkpointStore?: CheckpointStore;
 }): CheckpointStore | undefined;
+/** The ONE refusal of the retired `checkpointStore: null` spelling (the resolver and the workflow baseline overlay both throw it). */
+export declare function retiredCheckpointStoreNull(): Error & {
+    code: "config.invalid_checkpoint_store";
+};
 /**
  * design/80 D-1 (persist-winner): derive the durable {@link ResolvedOutcome} winner from a resume
  * `outcome`, or `undefined` when the outcome binds to no pending action. A `policy_ask` resume names a

package/dist/core/checkpoint-store.js

@@ -178,6 +178,13 @@ export function buildRiskDescriptor(input) {
         return { severity: 2, axes: {}, toolName: typeof toolName === "string" ? toolName : "" };
     }
 }
+export function realApprovalOrgFact(bit) {
+    if (bit === undefined)
+        return undefined;
+    if (bit.org !== undefined)
+        return bit.org;
+    return bit.origin === "org_rule" ? "rule" : bit.origin === "org_unavailable" ? "unavailable" : undefined;
+}
 export const CURRENT_CHECKPOINT_VERSION = 1;
 export const RESOURCE_CHECKPOINT_VERSION = 2;
 export const BINDING_CHECKPOINT_VERSION = 3;
@@ -356,10 +363,18 @@ function sameValueAt(a, b, depth, aToB, bToA) {
     }
 }
 export function resolveCheckpointStore(spec, deps) {
-    if (spec.checkpointStore === null)
+    if (Object.is(spec.checkpointStore, null))
+        throw retiredCheckpointStoreNull();
+    if (spec.checkpointStore === "disabled")
         return undefined;
     return spec.checkpointStore ?? deps.checkpointStore;
 }
+export function retiredCheckpointStoreNull() {
+    const e = new Error('TaskSpec.checkpointStore: null is not a value any more — write checkpointStore: "disabled" to run without a ' +
+        "checkpoint store (the per-run durable off switch), or leave the field unset to use the deployment's store.");
+    e.code = "config.invalid_checkpoint_store";
+    return e;
+}
 export function winnerFromOutcome(outcome) {
     if (outcome.gate === "plan_review" || outcome.gate === "dry_run_review") {
         const editedPlan = outcome.gate === "plan_review" ? outcome.editedPlan : undefined;
@@ -377,6 +392,7 @@ export function winnerFromOutcome(outcome) {
         decision: outcome.decision,
         ...(outcome.updatedInput === undefined ? {} : { updatedInput: outcome.updatedInput }),
         ...(outcome.answer === undefined ? {} : { answer: outcome.answer }),
+        ...(outcome.gateOutcome === undefined ? {} : { gateOutcome: outcome.gateOutcome }),
         ...(outcome.reason === undefined ? {} : { reason: outcome.reason }),
     };
 }

package/dist/core/gate-outcome.d.ts

@@ -0,0 +1,189 @@
+/**
+ * The settlement record and the gate outcome — the L0 vocabulary of what ONE tool-gate pass decided,
+ * what ask it settled and who asked. One structure, minted once (the gate's exit; the decide lane for a
+ * durable park) and projected three times without re-derivation: the `permissionDenied` observer's
+ * payload, the call's `tool_end` frame, and the durable row's resolved outcome. Lives beside
+ * `tool-policy.ts` rather than in it because it is a different concern from the permission verdict a
+ * policy composes: a policy says allow / ask / deny; this file says how the pass that consumed that
+ * verdict ended.
+ */
+import { type AskOrigin, type AssertAllKeysHandled } from "./ask-origin.js";
+/**
+ * How the wait an ask was in ENDED — the closed set. One word per way a wait can end; the `who` on the
+ * record says which party ended it and is fixed BY the word (see {@link Settlement}).
+ *  - `human_allowed` / `human_refused` — a person (or the approver acting for one) decided; the refusal's
+ *    own note, when the decider attached one, rides `note`.
+ *  - `approval_window_expired` — an approval window elapsed with no answer: the engine's own approval
+ *    factory window (`createApprovalPolicy.approvalTimeoutMs`), or a synchronous host approver that
+ *    reported its own window elapsed.
+ *  - `denial_limit_window_expired` — the classifier denial-limit fallback's auto-deny window (core's own
+ *    timer over the synchronous leg) elapsed with no answer.
+ *  - `park_sla_expired` — a DURABLE park's SLA deadline passed and the host's sweep resolved it as a deny
+ *    (FACET A). A store `expire`/`reap` produces no `tool_end` and therefore no settlement.
+ *  - `no_approver` — headless: no approver (or no question face) is wired, or the deny posture string.
+ *  - `approver_unavailable` — the approver (or an ancestor's frozen approver) answered the ROUTING question
+ *    "nobody reachable", and no park took the ask.
+ *  - `approver_error` — the approver threw.
+ *  - `approver_contract` — the approver answered outside its contract (a non-boolean verdict, an
+ *    unreadable member, a timeout-settled allow, a refused attribution…).
+ *  - `presentation_failed` — the args or the edit could not be safely presented/adopted (unclonable).
+ *  - `blanket_allow_refused` — a blanket `onAsk:"allow"` met a `requiresRealApproval` ask.
+ *  - `task_aborted` — the wait's abort signal ended it (the run's own end, or a turn-level interrupt).
+ */
+export declare const SETTLEMENT_KINDS: readonly ["human_allowed", "human_refused", "approval_window_expired", "denial_limit_window_expired", "park_sla_expired", "no_approver", "approver_unavailable", "approver_error", "approver_contract", "presentation_failed", "blanket_allow_refused", "task_aborted"];
+export type SettlementKind = (typeof SETTLEMENT_KINDS)[number];
+/** Membership test for {@link SettlementKind} — the word crosses process boundaries on `tool_end`, so a
+ *  consumer validating one it received must not hand-roll the set. */
+export declare function isSettlementKind(v: unknown): v is SettlementKind;
+/**
+ * The settlement record: WHAT ended the wait (`kind`), WHO ended it (`who` — its shape is decided by the
+ * word: the two human words carry a person, the window words say whose window, the park word the host,
+ * the fail-closed family nobody), WHEN (epoch ms, written at the settlement site), and for a person's
+ * refusal the decider's own NOTE when one was attached (a refusal WITHOUT a note is a bare "no", the arm
+ * the runner treats as a control-flow boundary for the issuing batch).
+ *
+ * It is a discriminated union and not a free product of `kind` × `who` on purpose: a free product can
+ * express "human_allowed, ended by the engine's window" — a structurally complete record that contradicts
+ * itself — and a consumer would then need the pairing rules this shape makes unwritable.
+ *
+ * @contract settlement.single_mint — every `Settlement` kind is composed by CORE at the site whose wait
+ * ended (the ask resolver's arms, the approval factory's arms, the decide lane over a host's decision
+ * FACTS). A host never mints a kind: a synchronous approver reports `"human"`/`"timeout"` on its outcome
+ * and a durable decide reports `hostDecision.decidedBy` (`"person"`/`"sla_timeout"`) — facts core turns
+ * into the word. Nothing on the caller-composable policy face (`PermissionResult`) carries a settlement,
+ * so a policy cannot self-declare one; the engine's own settlement sites that hand a settled decision
+ * back through a policy fold attest it through {@link engineSettlementOf}.
+ */
+export type Settlement = {
+    kind: "human_allowed" | "human_refused";
+    who: {
+        party: "person";
+        approver?: string;
+    };
+    when: number;
+    note?: string;
+} | {
+    kind: "approval_window_expired";
+    who: {
+        party: "engine";
+        window: "approval_factory";
+    } | {
+        party: "host";
+    };
+    when: number;
+} | {
+    kind: "denial_limit_window_expired";
+    who: {
+        party: "engine";
+        window: "denial_limit";
+    };
+    when: number;
+} | {
+    kind: "park_sla_expired";
+    who: {
+        party: "host";
+        approver?: string;
+    };
+    when: number;
+} | {
+    kind: "no_approver" | "approver_unavailable" | "approver_error" | "approver_contract" | "presentation_failed" | "blanket_allow_refused" | "task_aborted";
+    who: {
+        party: "none";
+    };
+    when: number;
+};
+/** Which settlement kinds are REFUSALS (the ask ended as a deny). Total over the closed set — the fence
+ *  below refuses a member without a row — so invariant I2 is a table lookup, not a list in a condition. */
+export declare const SETTLEMENT_IS_REFUSAL: {
+    readonly human_allowed: false;
+    readonly human_refused: true;
+    readonly approval_window_expired: true;
+    readonly denial_limit_window_expired: true;
+    readonly park_sla_expired: true;
+    readonly no_approver: true;
+    readonly approver_unavailable: true;
+    readonly approver_error: true;
+    readonly approver_contract: true;
+    readonly presentation_failed: true;
+    readonly blanket_allow_refused: true;
+    readonly task_aborted: true;
+};
+/** Compile-time fence: `never` while every settlement kind has a refusal row. */
+export type SettlementRefusalTableCoversEveryKind = AssertAllKeysHandled<Exclude<SettlementKind, keyof typeof SETTLEMENT_IS_REFUSAL>>;
+/**
+ * WHO REFUSED a call — the layer whose verdict is the deny. The other question a deny raises, "who ASKED",
+ * is answered by {@link GateOutcome.origin} (an {@link import("./ask-origin.js").AskOrigin}); the two used
+ * to share one seven-word list (`PermissionDeniedSource`) in which `classifier` meant both "the classifier
+ * asked" and "the classifier denied".
+ *  - `policy` — the deployment `ToolPolicy` denied (directly, or re-checking an approved edit), or the
+ *    approval-edit chain hit its round cap.
+ *  - `hook` — a PreToolUse hook denied, threw, or never answered (the engine's fail-closed block on a
+ *    hook that made no decision counts as the hook layer's refusal for attribution).
+ *  - `org` — an organization policy rule denied.
+ *  - `classifier` — the auto-mode classifier denied directly (its ASK-side role is `origin:
+ *    "denial_limit_fallback"`).
+ *  - `plan_mode` — plan mode's read-only block on a write tool.
+ *  - `compliance` — the compliance call-time lock.
+ *  - `write_protection` — an approved edit was rewritten by the restriction chain onto a write-protected
+ *    path that no approval covers.
+ *  - `ask_resolution` — the ask's own settlement is the refusal (a person said no, a window elapsed,
+ *    nobody could be asked…); the detail is on {@link GateOutcome.settlement}.
+ */
+export declare const DENIED_BY_VALUES: readonly ["policy", "hook", "org", "classifier", "plan_mode", "compliance", "write_protection", "ask_resolution"];
+export type DeniedBy = (typeof DENIED_BY_VALUES)[number];
+/** Membership test for {@link DeniedBy}. */
+export declare function isDeniedBy(v: unknown): v is DeniedBy;
+/** Which layers may VETO an approval a person already gave (invariant I3: a `human_allowed` settlement
+ *  beside a `denied` disposition names one of these). The approval-edit re-screen (hook), the policy and
+ *  org re-checks, and the write-protection re-judge run AFTER the person's yes; the classifier, plan mode
+ *  and compliance run before any ask exists, and `ask_resolution` IS the settlement, not a veto of it. */
+export declare const DENIED_BY_MAY_VETO: {
+    readonly policy: true;
+    readonly hook: true;
+    readonly org: true;
+    readonly classifier: false;
+    readonly plan_mode: false;
+    readonly compliance: false;
+    readonly write_protection: true;
+    readonly ask_resolution: false;
+};
+/** Compile-time fence: `never` while every deny layer has a veto row. */
+export type VetoTableCoversEveryDeniedBy = AssertAllKeysHandled<Exclude<DeniedBy, keyof typeof DENIED_BY_MAY_VETO>>;
+/** The final disposition of a gate pass. */
+export type GateDisposition = {
+    kind: "allowed";
+} | {
+    kind: "denied";
+    deniedBy: DeniedBy;
+};
+/**
+ * The WHOLE record of one tool-gate pass: the final disposition, plus — when this pass settled an ask —
+ * the settlement it consumed and the ask's origin. Minted ONCE (the gate's exit; the decide lane for a
+ * durable park) and projected three times without re-derivation: the `permissionDenied` observer's
+ * payload, the call's `tool_end` frame, and the durable row's resolved outcome. The three faces are the
+ * same object graph, so they cannot tell different stories.
+ *
+ * The three members are orthogonal but bound by four invariants ({@link screenGateOutcome}):
+ *  I1  `settlement` present ⇔ `origin` present (they describe the same ask);
+ *  I2  `disposition.deniedBy === "ask_resolution"` ⇒ `settlement` present and a refusal kind;
+ *  I3  `settlement.kind === "human_allowed"` ∧ `disposition.kind === "denied"` ⇒ `deniedBy` is a veto
+ *      layer ({@link DENIED_BY_MAY_VETO}) — a person approved, a later re-check refused; the approver stays
+ *      on the settlement (it is not the approver's refusal);
+ *  I4  `disposition.kind === "allowed"` ⇒ `settlement` absent or `human_allowed`.
+ * Nothing here is read out of an ABSENCE: an ordinary allow with no ask is `{ disposition: { kind: "allowed" } }`,
+ * a direct policy deny is `{ disposition: { kind: "denied", deniedBy: "policy" } }`, and neither carries a
+ * settlement because neither settled one.
+ */
+export interface GateOutcome {
+    disposition: GateDisposition;
+    settlement?: Settlement;
+    origin?: AskOrigin;
+}
+/**
+ * The one invariant screen for a {@link GateOutcome} (I1–I4 above, plus the shape of each member). Runs
+ * where an outcome enters a wire face — the engine's settlement sideband before the `tool_end` frame, and
+ * the decide lane before a durable row is resolved. Returns the defects as sentences (an empty list is a
+ * clean record); the caller decides the fail-loud form (report + withhold, or refuse), never silently
+ * repairs the record.
+ */
+export declare function screenGateOutcome(g: GateOutcome): string[];

package/dist/core/gate-outcome.js

@@ -0,0 +1,70 @@
+import { isAskOrigin } from "./ask-origin.js";
+export const SETTLEMENT_KINDS = [
+    "human_allowed",
+    "human_refused",
+    "approval_window_expired",
+    "denial_limit_window_expired",
+    "park_sla_expired",
+    "no_approver",
+    "approver_unavailable",
+    "approver_error",
+    "approver_contract",
+    "presentation_failed",
+    "blanket_allow_refused",
+    "task_aborted",
+];
+const SETTLEMENT_KIND_SET = new Set(SETTLEMENT_KINDS);
+export function isSettlementKind(v) {
+    return SETTLEMENT_KIND_SET.has(v);
+}
+export const SETTLEMENT_IS_REFUSAL = {
+    human_allowed: false,
+    human_refused: true,
+    approval_window_expired: true,
+    denial_limit_window_expired: true,
+    park_sla_expired: true,
+    no_approver: true,
+    approver_unavailable: true,
+    approver_error: true,
+    approver_contract: true,
+    presentation_failed: true,
+    blanket_allow_refused: true,
+    task_aborted: true,
+};
+export const DENIED_BY_VALUES = ["policy", "hook", "org", "classifier", "plan_mode", "compliance", "write_protection", "ask_resolution"];
+const DENIED_BY_SET = new Set(DENIED_BY_VALUES);
+export function isDeniedBy(v) {
+    return DENIED_BY_SET.has(v);
+}
+export const DENIED_BY_MAY_VETO = {
+    policy: true,
+    hook: true,
+    org: true,
+    classifier: false,
+    plan_mode: false,
+    compliance: false,
+    write_protection: true,
+    ask_resolution: false,
+};
+export function screenGateOutcome(g) {
+    const defects = [];
+    const d = g.disposition;
+    if (d.kind === "denied" && !isDeniedBy(d.deniedBy))
+        defects.push(`disposition.deniedBy "${String(d.deniedBy)}" is outside the closed set`);
+    const s = g.settlement;
+    if (s !== undefined && !isSettlementKind(s.kind))
+        defects.push(`settlement.kind "${String(s.kind)}" is outside the closed set`);
+    if (g.origin !== undefined && !isAskOrigin(g.origin))
+        defects.push(`origin "${String(g.origin)}" is outside the closed set`);
+    if ((s !== undefined) !== (g.origin !== undefined))
+        defects.push("I1: settlement and origin must be present together — they describe the same ask");
+    if (d.kind === "denied" && d.deniedBy === "ask_resolution" && (s === undefined || !isSettlementKind(s.kind) || !SETTLEMENT_IS_REFUSAL[s.kind])) {
+        defects.push("I2: deniedBy ask_resolution requires a settlement whose kind is a refusal");
+    }
+    if (s !== undefined && s.kind === "human_allowed" && d.kind === "denied" && isDeniedBy(d.deniedBy) && !DENIED_BY_MAY_VETO[d.deniedBy]) {
+        defects.push(`I3: a human_allowed settlement beside a deny must name a veto layer, not "${d.deniedBy}"`);
+    }
+    if (d.kind === "allowed" && s !== undefined && s.kind !== "human_allowed")
+        defects.push(`I4: an allowed disposition cannot carry a "${s.kind}" settlement`);
+    return defects;
+}