@decidio/sdk 0.1.12 → 0.2.1

package/dist/resume.d.ts

@@ -1,5 +1,10 @@
 import type { RequestListener } from "node:http";
 import { type EvidenceOutcome, type EvidenceTier } from "./evidence.js";
+export declare function signEvidence(decisionId: string, attemptId: string | null, evidence: unknown, agentKey?: string, webhookSecret?: string): {
+    kind: "ed25519" | "hmac";
+    sig: string;
+} | undefined;
+export declare function verifyEvidence(rec: ExecutionRecord, agentKey?: string, webhookSecret?: string): "ok" | "mismatch" | "unbound" | "unverifiable";
 /** A routed action parked on the agent side, awaiting human approval. The `args`
  *  are the original call arguments, replayed verbatim when the action resumes. */
 export interface PendingAction {
@@ -29,59 +34,278 @@ export interface PendingAction {
 /** Where suspended actions live between request and approval. The default is a
  *  file store; swap in Redis/Postgres/your queue for production. AGENT-SIDE only —
  *  Decidio never sees this. */
+/** The durable execution state machine (v2).
+ *
+ *  parked → claimed_preinvoke → invoking → (executed_unreported | indeterminate) → reported
+ *
+ *  THE ONE RULE: nothing transitions BACK to parked once `invoking` has been written. Deletion
+ *  is cleanup, never the single-use guarantee — that was the 0.1.x model, and a store whose
+ *  delete() failed (or silently kept the row) let a fresh process execute an already-committed
+ *  action a second time. The state IS the guarantee now; a failed delete is a tidiness problem.
+ *
+ *  `indeterminate` is the honest answer to the case an SDK cannot decide: the handler was
+ *  invoked and then threw. Whether the downstream write committed is not knowable from here, so
+ *  the action is never automatically retried — it waits for `reconcile()`. */
+export type ExecutionState = "parked" | "claimed_preinvoke" | "invoking" | "executed_unreported" | "indeterminate" | "reported";
+/** Ordered weakest→strongest. Resolution ALWAYS takes the strongest state present for a
+ *  decision, which is what makes a partially-failed transition safe: if a crash leaves both the
+ *  old and new markers on disk, the stronger one wins and an executed action can never read
+ *  back as parked. */
+export declare const EXECUTION_STATES: readonly ExecutionState[];
+/** States from which the handler must NEVER be invoked again automatically. */
+export declare const NON_REPLAYABLE: readonly ExecutionState[];
+export interface ExecutionRecord {
+    decisionId: string;
+    state: ExecutionState;
+    /** The attempt that owns (or last owned) this decision. A fencing token: a write from a
+     *  stale attempt is refused. */
+    attemptId: string | null;
+    action?: string;
+    /** The canonical reported value — present from `executed_unreported` onward. This is what
+     *  `reconfirm()` re-sends; it carries no handler binding, so replaying it can only ever
+     *  re-send a report, never re-run the action. */
+    evidence?: unknown;
+    /** Whether `evidence` was actually recorded. Separate from `evidence` because `null` is a
+     *  legitimate reported value (an action whose return could not be mapped still reports a null
+     *  captured response), so presence cannot be inferred from the value. Python has carried this
+     *  flag from the start; TypeScript inferring presence from `!== undefined` was a twin
+     *  divergence waiting to disagree about a null-evidence decision. */
+    hasEvidence?: boolean;
+    /** Set when the evidence MAPPER failed, so `evidence` is null because nothing could be captured
+     *  — not because the action returned null. The ledger could not previously tell those apart, and
+     *  the difference decides whether an operator may fill the value: a null the SDK OBSERVED is a
+     *  measurement, a null it failed to produce is a gap. */
+    evidenceError?: string;
+    /** Integrity binding over {decisionId, attemptId, evidence}, written when the evidence is
+     *  recorded. `reconfirm()` verifies it before re-signing, so a record altered in a shared store
+     *  is refused rather than attested. Absent when the agent has no key material — the same
+     *  "unbound" state the parked args can be in, reported the same way. */
+    evidenceSig?: {
+        kind: "ed25519" | "hmac";
+        sig: string;
+    };
+    /** Set when this row was reconstructed by an upgrade rather than written by a live execution —
+     *  currently only `"0.1.x report journal"`. Such a row predates evidence binding and can never
+     *  carry a valid signature, so the strict check exempts it EXPLICITLY. The exemption must be a
+     *  positive flag: exempting "anything with no signature" would hand an attacker the bypass. */
+    migratedFrom?: string;
+    /** Why the outcome is unknown — present on `indeterminate`. */
+    error?: string;
+    /** The tier Decidio recorded — present on `reported`. */
+    confirmation?: string;
+    /** Set when an OPERATOR settled this decision rather than the SDK observing it. Kept so an
+     *  audit of the agent-side ledger can tell an observed execution from an asserted one. */
+    reconciled?: {
+        outcome: SettleOutcome;
+        reason?: string;
+        at: string;
+    };
+    at: string;
+}
+export type SettleOutcome = "committed" | "not_committed";
+/** Refuse a reconciliation that would be a fabrication. Shared by every store so the rule cannot
+ *  drift between implementations — a store that allowed `committed` from `parked` would let an
+ *  operator mint an execution report for an action nothing ever invoked. */
+/** A decision an operator SETTLED as committed is finished: its report is recorded and sent. A
+ *  late write from the attempt that was still running would produce a second authority report for
+ *  one decision, so it is refused here rather than in each store. `not_committed` settlements are
+ *  deliberately not covered — that outcome exists so a new attempt can run and record. */
+/** The ledger row is owned by a NEWER attempt. Typed for the same reason `DecidioAlreadySettled`
+ *  is: `reportAfterExecution` must keep going when the ledger fails, so a bare Error here read as
+ *  "the disk write failed" and the stale attempt went on to POST — a second authority report for
+ *  one decision. Reachable through the SDK's own documented flow: `reconcile(id, not_committed)`
+ *  releases a decision whose original attempt is still alive (recover() invites exactly that, since
+ *  it says the process "died" when it may not have), the release is legitimate and the new attempt
+ *  SHOULD run — but the old attempt's report must not be sent. */
+export declare class DecidioStaleAttemptError extends Error {
+    decisionId: string;
+    owner: string | null;
+    state: ExecutionState;
+    constructor(decisionId: string, owner: string | null, state: ExecutionState);
+}
+export declare class DecidioAlreadySettledError extends Error {
+    decisionId: string;
+    constructor(decisionId: string);
+}
+export declare const SETTLE_OUTCOMES: readonly SettleOutcome[];
+export declare function assertSettlable(id: string, state: ExecutionState, outcome: SettleOutcome, hasObservedEvidence?: boolean): void;
+export interface ClaimResult {
+    /** True only when THIS attempt may proceed to invoke. */
+    ok: boolean;
+    /** The state that refused the claim, when ok is false — so a caller can tell "another worker
+     *  has it" from "this already executed and must be reconciled". */
+    state?: ExecutionState;
+    reason?: string;
+}
+/** Agent-side durable state. The shipped stores are file- and memory-backed; swap in
+ *  Redis/Postgres/your queue for production. AGENT-SIDE only — Decidio never sees this.
+ *
+ *  v2 (0.2.0) makes the state machine MANDATORY. The 0.1.x contract left `claim()` optional and
+ *  fell back to a process-local set, which cannot survive a restart and therefore could not
+ *  carry a single-execution guarantee across processes at all. Every method below must be
+ *  atomic against concurrent callers — compare-and-swap, a transaction, or an equivalent
+ *  fencing token. */
 export interface PendingStore {
     put(p: PendingAction): Promise<void>;
     get(decisionId: string): Promise<PendingAction | null>;
+    /** CLEANUP ONLY. Removing a row must never be what prevents a second execution. */
     delete(decisionId: string): Promise<void>;
+    /** Parked entries only — anything claimed or beyond is excluded. */
     list(): Promise<PendingAction[]>;
-    /** Atomically take ownership of a parked action for execution. Returns true if THIS
-     *  caller claimed it, false if it's already claimed/gone — the cross-process single-use
-     *  guarantee (a production store backs this with rename/SETNX/SELECT-FOR-UPDATE). A
-     *  claimed entry is excluded from list(). Optional: if absent, the controller falls
-     *  back to an in-process guard (same-process only). */
-    claim?(decisionId: string): Promise<boolean>;
-    /** Undo a claim so a failed execution is retryable. */
-    release?(decisionId: string): Promise<void>;
-    /** Entries currently CLAIMED (excluded from list()). Needed for honest recovery reporting —
-     *  a claimed entry with no journalled result is the indeterminate case. */
-    listClaimed?(): Promise<PendingAction[]>;
+    /** Atomically take ownership for THIS attempt. Must refuse when the decision is already
+     *  claimed by a live attempt, or is in any NON_REPLAYABLE state. */
+    claim(decisionId: string, attemptId: string): Promise<ClaimResult>;
+    /** The handler is about to be called. After this point the store must never report the
+     *  decision as executable again, whatever else fails. */
+    markInvoking(decisionId: string, attemptId: string): Promise<void>;
+    /** The handler returned. `evidence` is the canonical reported value. */
+    recordExecuted(decisionId: string, attemptId: string, evidence: unknown, evidenceSig?: ExecutionRecord["evidenceSig"], evidenceError?: string): Promise<void>;
+    /** The handler was invoked and threw: the downstream outcome is unknown. */
+    markIndeterminate(decisionId: string, attemptId: string, error: string): Promise<void>;
+    /** Decidio accepted the execution report. */
+    markReported(decisionId: string, attemptId: string, confirmation: string): Promise<void>;
+    /** The authoritative state for one decision, or null if this store has never seen it. */
+    getExecution(decisionId: string): Promise<ExecutionRecord | null>;
+    /** Every execution record the store holds — the basis for honest recovery reporting. */
+    listExecutions(): Promise<ExecutionRecord[]>;
+    /** Operator reconciliation — the only legal backwards transition, and the only exit from
+     *  `indeterminate`. Never called by any automatic path.
+     *
+     *  A CUSTOM STORE MUST RAISE THE TYPED ERRORS at its own fences: `DecidioStaleAttemptError` when
+     *  a superseded attempt writes, and `DecidioAlreadySettledError` when a second execution report
+     *  lands on a decision an operator settled as committed. The reporting stage deliberately keeps
+     *  going when the ledger fails — that is what stops an evidence gap from costing an execution —
+     *  so a store that raises a generic error for either case sends a duplicate authority report
+     *  instead of stopping. */
+    settle(decisionId: string, outcome: SettleOutcome, opts?: {
+        evidence?: unknown;
+        reason?: string;
+        evidenceSig?: ExecutionRecord["evidenceSig"];
+    }): Promise<void>;
+    /** Release a claim taken BEFORE invocation, so a pre-invoke failure stays retryable. It is a
+     *  contract error to call this once `markInvoking` has been written, and a conforming store
+     *  must refuse it. */
+    releasePreinvoke(decisionId: string, attemptId: string): Promise<void>;
 }
+/** In-memory store. Single-process only BY CONSTRUCTION — it is the right choice for tests and
+ *  for a worker that owns its queue, and the wrong one for two processes sharing work, which is
+ *  exactly what `FilePendingStore` (atomic renames on one volume) or a real database is for. */
 export declare class MemoryPendingStore implements PendingStore {
     private m;
-    private claimed;
+    private x;
+    private rec;
+    /** Advance only. A write from a stale attempt, or one that would move the state BACKWARDS,
+     *  is refused — the in-memory expression of the same rule the file store gets from
+     *  strongest-wins resolution. */
+    private advance;
     put(p: PendingAction): Promise<void>;
     get(id: string): Promise<PendingAction | null>;
     delete(id: string): Promise<void>;
     list(): Promise<PendingAction[]>;
-    claim(id: string): Promise<boolean>;
-    release(id: string): Promise<void>;
-    listClaimed(): Promise<PendingAction[]>;
+    claim(id: string, attemptId: string): Promise<ClaimResult>;
+    markInvoking(id: string, attemptId: string): Promise<void>;
+    recordExecuted(id: string, attemptId: string, evidence: unknown, evidenceSig?: ExecutionRecord["evidenceSig"], evidenceError?: string): Promise<void>;
+    markIndeterminate(id: string, attemptId: string, error: string): Promise<void>;
+    markReported(id: string, attemptId: string, confirmation: string): Promise<void>;
+    getExecution(id: string): Promise<ExecutionRecord | null>;
+    listExecutions(): Promise<ExecutionRecord[]>;
+    /** OPERATOR RECONCILIATION — the ONE legal backwards transition, and the only exit from
+     *  `indeterminate` or a stalled claim. It is legal only because a human asserted the downstream
+     *  truth this machine cannot observe, so no automatic path may call it.
+     *
+     *  `committed`     → `executed_unreported` carrying the operator's evidence, so the ordinary
+     *                    reporting path can send it. The handler is NEVER invoked.
+     *  `not_committed` → back to `parked`, permitting exactly one more ordinary attempt. */
+    settle(id: string, outcome: SettleOutcome, opts?: {
+        evidence?: unknown;
+        reason?: string;
+        evidenceSig?: ExecutionRecord["evidenceSig"];
+    }): Promise<void>;
+    releasePreinvoke(id: string, attemptId: string): Promise<void>;
 }
 /** Restrict a directory to its owner. On Windows POSIX modes are a no-op, so strip inheritance
  *  and grant only the effective user. A FAILURE IS SAID, never swallowed: these files hold the
  *  arguments of actions awaiting approval, and "silently kept the directory's inherited
  *  permissions" is exactly the outcome an operator must not discover from an auditor. */
 export declare function hardenDir(dir: string): void;
-/** File-backed store so a COLD process (the original requester long gone) can still
- *  resume — the proof that nothing is "kept alive". One JSON file per decision. A claim
- *  renames `<id>.json` → `<id>.claimed` atomically (same-volume rename), so two processes
- *  sharing the dir can't both execute. (A stale `.claimed` from a crash mid-execute needs
- *  TTL recovery — tracked in the backlog.) */
+/** File-backed store so a COLD process (the original requester long gone) can still resume — the
+ *  proof that nothing is "kept alive". One JSON file per decision holds the parked payload, and
+ *  one marker file per execution state holds the ledger.
+ *
+ *  A claim is `link()`, not `rename()`: link fails when the target exists, so two processes racing
+ *  for the same decision produce one winner and one clean refusal, while rename would silently
+ *  overwrite and let both proceed. (0.1.x renamed `<id>.json` → `<id>.claimed`, and a stale
+ *  `.claimed` from a crash then needed a TTL nobody had written — that gap is closed by the
+ *  `claimed_stalled` state and `reconcile()`, which release it explicitly rather than on a timer.
+ *  A timer would have to guess whether the handler ran.) */
 export declare class FilePendingStore implements PendingStore {
     private dir;
     constructor(dir: string);
     private key;
     private path;
-    private claimedPath;
+    /** One marker file per state. The FILENAME carries the state so a scan never has to parse,
+     *  and the content carries the record. */
+    private statePath;
+    /** Durable write: temp file in the SAME directory → fsync → atomic rename. A crash can then
+     *  only leave the old complete file or the new complete file, never a truncated one. The
+     *  0.1.x journal wrote straight to its final path with O_TRUNC, so a crash mid-write
+     *  destroyed the record that proved an action had already run. */
+    private writeAtomic;
+    /** The authoritative record: the STRONGEST state present on disk. A crash between "write the
+     *  new marker" and "remove the old one" leaves two markers; taking the strongest means an
+     *  executed action can never read back as parked, so a partial transition is safe rather than
+     *  merely unlikely. Corruption is reported, never silently treated as absent. */
+    private resolve;
+    private setState;
     put(p: PendingAction): Promise<void>;
     get(id: string): Promise<PendingAction | null>;
+    /** CLEANUP ONLY — the payload goes, the execution record STAYS. That is the whole point of
+     *  the v2 model: a failed or skipped delete can no longer make an executed action runnable. */
     delete(id: string): Promise<void>;
     list(): Promise<PendingAction[]>;
-    claim(id: string): Promise<boolean>;
-    release(id: string): Promise<void>;
-    /** Claimed entries (`.claimed` files) — invisible to list() by design, but a stranded one is
-     *  exactly what recovery must surface. */
-    listClaimed(): Promise<PendingAction[]>;
+    claim(id: string, attemptId: string): Promise<ClaimResult>;
+    markInvoking(id: string, attemptId: string): Promise<void>;
+    recordExecuted(id: string, attemptId: string, evidence: unknown, evidenceSig?: ExecutionRecord["evidenceSig"], evidenceError?: string): Promise<void>;
+    markIndeterminate(id: string, attemptId: string, error: string): Promise<void>;
+    markReported(id: string, attemptId: string, confirmation: string): Promise<void>;
+    getExecution(id: string): Promise<ExecutionRecord | null>;
+    listExecutions(): Promise<ExecutionRecord[]>;
+    /** OPERATOR RECONCILIATION — see MemoryPendingStore.settle. Writes the new marker first and
+     *  then clears every other state file for this decision, including the STRONGER ones: this is
+     *  the single place where a state legitimately moves backwards, so leaving a stronger marker
+     *  behind would let resolve()'s strongest-wins rule undo the operator's decision. */
+    settle(id: string, outcome: SettleOutcome, opts?: {
+        evidence?: unknown;
+        reason?: string;
+        evidenceSig?: ExecutionRecord["evidenceSig"];
+    }): Promise<void>;
+    releasePreinvoke(id: string, attemptId: string): Promise<void>;
+    /** ONE-WAY MIGRATION from the 0.1.x layout, run once at construction. `<id>.json` → parked;
+     *  `<id>.claimed` → INDETERMINATE, never parked: a claimed 0.1.x entry may have been mid-flight
+     *  when the process died, and assuming it did not run is the assumption that duplicates a
+     *  payment. Nothing ambiguous is made executable by an upgrade. */
+    migrateLegacy(): {
+        migrated: number;
+        indeterminate: number;
+        reports: number;
+    };
+    /** 0.1.x wrote execution reports to `<pendingDir>/reports/<id>.json` — evidence that an action
+     *  ALREADY RAN and still owes Decidio a report. 0.2.0 keeps that in the ledger, so without this
+     *  those files become invisible: `recover()` returns nothing and `reconfirm()` answers "nothing
+     *  is recorded for X … or this process never executed it" about an action that demonstrably
+     *  did. That is the SDK losing a durable authority fact on upgrade, so the reports are pulled
+     *  into `executed_unreported` rows where reconfirm() can actually re-send them.
+     *
+     *  The file is CONSUMED (renamed to `.migrated`) rather than deleted: if anything here is
+     *  wrong, the original bytes are still on disk to inspect. */
+    private migrateLegacyReports;
+}
+/** The state on disk could not be read. Never silently treated as "nothing here": an
+ *  unreadable record is the one that proves an action already ran. */
+export declare class DecidioStateCorruptError extends Error {
+    decisionId: string;
+    details: string[];
+    constructor(decisionId: string, details: string[]);
 }
 /** Thrown by a `withApproval`-wrapped call when the action is routed and configured
  *  for async resume: the action is now SUSPENDED (parked in the store), not failed.
@@ -92,29 +316,21 @@ export declare class DecidioSuspendedError extends Error {
     action: string;
     constructor(decisionId: string, action: string);
 }
-export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown";
-/** A durable note that an action ALREADY RAN and what must still be reported. It lives OUTSIDE
- *  the pending store on purpose: a journal entry carries no handler binding, so replaying it can
- *  only ever re-send a report — it can never re-run the business action. That is what makes
- *  recovery safe on stores with and without claim(). */
-export interface ExecutionJournalEntry {
-    decisionId: string;
-    action: string;
-    /** The canonical value that was reported — the durable FACT, journalled before the first
-     *  attempt. Deliberately NOT the signed request: both proofs on a confirm are short-lived (the
-     *  identity proof lives 120s, the execution report 5 minutes), so a replayed envelope is
-     *  refused by the server for any outage longer than that — which is every outage worth
-     *  recovering from. `reconfirm` re-signs at SEND time over these same bytes, so the report
-     *  stays replay-safe (it still cannot re-run anything: no handler is journalled) while staying
-     *  usable a week later. */
-    reported: unknown;
-    at: string;
-}
+/** `indeterminate` (0.2.0): the handler was INVOKED and then threw. Whether the downstream
+ *  effect committed is not knowable from here, so the action is never retried automatically —
+ *  it waits for reconcile(). Callers that switch exhaustively on this union must handle it. */
+export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown" | "indeterminate";
 /** The states a durable action can actually be in — every one of them nameable, including the
  *  one nobody likes. */
 export type RecoveryState = 
 /** Parked, waiting on a human. Nothing has executed. */
 "parked"
+/** Claimed by an attempt that never reached the invocation boundary, so the handler PROVABLY
+ *  did not run — but the row is not parked either: `list()` excludes it and every ordinary
+ *  signal answers `unknown`, so nothing will pick it up on its own. It is stalled until an
+ *  operator releases it. Reporting this as "parked" (as 0.2.0's first draft did) told a UI an
+ *  approved action was still queued to resume when in fact it had been silently dropped. */
+ | "claimed_stalled"
 /** Claimed for execution and NOT journalled: the process died somewhere between claiming and
  *  recording the result. The action MAY OR MAY NOT have run — this cannot be resolved locally
  *  and must never be retried automatically. */
@@ -128,6 +344,28 @@ export interface RecoveryItem {
     /** What a human should do about it, in words. */
     guidance: string;
 }
+/** What the SDK knows about THIS execution, handed to a handler that opts in with
+ *  `withContext: true`.
+ *
+ *  The point is `idempotencyKey`. This SDK can guarantee it will not invoke your handler twice;
+ *  it cannot guarantee your downstream API only commits once, because that is the vendor's
+ *  property, not ours. Passing this key to Stripe/Salesforce/your own service is what closes the
+ *  remaining window — and until now the handler had no way to reach the decision id at all, so
+ *  the one thing that could close it was the one thing a caller could not get.
+ *
+ *  Opt-in, never inferred from arity. A signature check would have to guess whether a bound
+ *  method, a *args function or a decorated tool wanted the context, and guessing wrong means
+ *  passing a context object as someone's first business argument — in a library whose whole job
+ *  is not doing surprising things to a payment call. */
+export interface ExecutionContext {
+    decisionId: string;
+    /** The attempt that owns this execution. Null on the inline path, where there is no durable
+     *  attempt — the value is honest about which door you came through. */
+    attemptId: string | null;
+    /** Defaults to `decisionId`. Stable across every attempt at the same decision, which is exactly
+     *  what a downstream idempotency key must be. */
+    idempotencyKey: string;
+}
 export interface ResumeOutcome {
     status: ResumeStatus;
     decisionId: string;
@@ -147,6 +385,14 @@ export interface ResumeOutcome {
     executionReportVerified?: boolean;
     /** executed only: why the evidence landed where it did, when that is worth explaining. */
     diagnostic?: string;
+    /** The four fields the INLINE door returns. The durable door computed the same outcome and kept
+     *  three of them for its own prose, so the same question got a field on one path and a sentence
+     *  on the other — and `reportJournalled` was worst, because the durable path is the one where
+     *  `reconfirm()` genuinely CAN help and it never said so. */
+    executionReportReason?: string;
+    confirmationRetryable?: boolean;
+    reportJournalled?: boolean;
+    evidenceError?: string;
 }
 /** Minimal config the controller needs to confirm outcomes + poll status. Shared
  *  with GuardConfig (apiUrl/apiToken). */
@@ -165,8 +411,12 @@ export interface ResumeConfig {
     /** Shared secret Decidio signs the resume webhook with (HMAC-SHA256). Defaults to
      *  the API token if unset. Verified before any re-execution. */
     webhookSecret?: string;
-    /** Where the execution journal lives (default `<pending dir>/reports`). Separate from the
-     *  pending store by design: journal entries can only re-send a report, never re-run an action. */
+    /** @deprecated Ignored since 0.2.0 and accepted only so existing callers keep compiling.
+     *  Execution evidence now lives in the PendingStore's own execution record, beside the state
+     *  that makes a decision non-replayable. 0.1.x kept it in a separate local directory, so two
+     *  workers sharing one Redis/Postgres store still held two disjoint journals and neither could
+     *  reconfirm the other's work — and a store-recorded execution could read back as "nothing has
+     *  executed" if the local file was lost. One store, one truth. */
     reportDir?: string;
     /** Map the action's natural return value to the evidence Decidio records — same option, same
      *  meaning as `protect`'s, so a durable resume reports exactly what the inline path would. */
@@ -182,8 +432,11 @@ export interface ResumeConfig {
     /** The callback URL Decidio should POST the verdict to (webhook transport). Sent
      *  on /agent/authorize so the decision carries it; omit when using the poll worker. */
     resumeUrl?: string;
-    /** Fired after every terminal resolution (executed / rejected / blocked / no_handler),
-     *  via either transport. Use it to log, close a listener, or exit a CLI. */
+    /** Fired after every terminal resolution (executed / indeterminate / rejected / blocked /
+     *  no_handler), via either transport. Use it to log, close a listener, or exit a CLI.
+     *  `indeterminate` is new in 0.2.0 and DOES fire here: a handler that ran and then threw is a
+     *  terminal outcome for automation — nothing will retry it — so a listener that only handled
+     *  the old four would silently miss the one case that needs a human. */
     onResolved?: (o: ResumeOutcome) => void;
     fetchImpl?: typeof fetch;
 }
@@ -194,7 +447,7 @@ export interface ResumeController extends ResumeConfig {
     /** Register a RAW fn under its action name so a (possibly cold) resume can replay
      *  it. `withApproval` auto-registers on the hot path; a cold worker/service should
      *  register at startup so it can resume actions it never originated. */
-    register(action: string, fn: (...args: any[]) => Promise<any>, evidence?: (result: any) => unknown): void;
+    register(action: string, fn: (...args: any[]) => Promise<any>, evidence?: (result: any) => unknown, withContext?: boolean): void;
     /** Park a routed action WITH its integrity binding (prefer this over store.put — the
      *  binding is what lets resolve() refuse a tampered payload). */
     park(p: Omit<PendingAction, "createdAt" | "argsSig">): Promise<void>;
@@ -219,11 +472,27 @@ export interface ResumeController extends ResumeConfig {
     }): {
         stop: () => void;
     };
-    /** Re-send a journalled execution report, IDEMPOTENTLY. Replays the exact request built before
-     *  the first attempt — it can never re-run the business action, because the journal holds no
-     *  handler binding. Returns the evidence outcome; a decision with nothing journalled returns
+    /** Re-send a recorded execution report, IDEMPOTENTLY. Re-signs at send time over the value in
+     *  the store's execution ledger — it can never re-run the business action, because the ledger
+     *  holds no handler binding. Returns the evidence outcome; a decision with nothing recorded returns
      *  `reportRecorded: false` with guidance rather than pretending. */
-    reconfirm(decisionId: string): Promise<EvidenceOutcome>;
+    /** `acceptUnbound` is an OPERATOR override for a record whose integrity binding is missing or
+     *  unverifiable — the case a 0.1.x upgrade legitimately produces. It is a call-site argument on
+     *  purpose: any flag stored in the record itself would be writable by whoever planted the
+     *  record. */
+    reconfirm(decisionId: string, opts?: {
+        acceptUnbound?: boolean;
+    }): Promise<EvidenceOutcome>;
+    /** Settle a decision an operator has checked downstream — the ONLY exit from `indeterminate`
+     *  and from a claim that stalled before invocation, and the only backwards transition in the
+     *  machine. `committed` records and reports the evidence you supply WITHOUT invoking the
+     *  handler; `not_committed` parks the decision so exactly one more ordinary attempt can run.
+     *  Never called automatically: the whole point is that a human looked. */
+    reconcile(decisionId: string, opts: {
+        outcome: SettleOutcome;
+        evidence?: unknown;
+        reason?: string;
+    }): Promise<EvidenceOutcome>;
     /** Every durable item that needs a human's attention, with its state named — including the one
      *  state that CANNOT be resolved automatically: `indeterminate`, where a process died between
      *  claiming an action and journalling its result, so whether the action ran is unknown locally.
@@ -234,10 +503,15 @@ declare function sign(secret: string, body: string): string;
 /** Verify Decidio's `x-decidio-signature` over the raw webhook body (HMAC-SHA256).
  *  Exported so engine adapters (e.g. the Inngest bridge) reuse the exact check. */
 export declare function verifyResumeSignature(secret: string, body: string, header: string | undefined): boolean;
-/** The ONE confirm-body rule, shared by every confirm door (resume, inline withApproval,
- *  adapter gate). Transport success is not confirmation: a 2xx whose body carries no recorded
- *  tier is a FAILED confirm; a SIGNED confirm coming back below application_confirmed is
- *  disclosed, never silent. Returns the recorded tier or throws. */
+/** Throwing wrapper over the ONE confirm-body rule, for a caller building their own confirm door.
+ *  Returns the recorded tier or throws.
+ *
+ *  It now DELEGATES to `readConfirmResponse` rather than re-implementing the check, because the
+ *  two had drifted into opposite answers: this function accepted `confirmation: "anything"` and
+ *  handed it back as a recorded tier, while the parser every real door uses treats an
+ *  unrecognised tier as NOT evidence (closed enum, fail-closed — an answer we do not understand
+ *  is never evidence). Its own comment claimed it was "shared by every confirm door", and no door
+ *  called it: the claim was what kept anyone from noticing the disagreement. */
 export declare function assertConfirmRecorded(body: any, decisionId: string, signed: boolean): string;
 export declare function createDecidioResume(opts: ResumeConfig & {
     store: PendingStore;