@decidio/sdk 0.2.2 → 0.3.3

package/dist/evidence.d.ts

@@ -3,6 +3,15 @@
  *  we do not understand is never treated as evidence. */
 export declare const EVIDENCE_TIERS: readonly ["pending", "execution_unconfirmed", "agent_asserted", "sensor_observed", "application_confirmed", "independently_reconciled"];
 export type EvidenceTier = (typeof EVIDENCE_TIERS)[number];
+/** Whether a recorded tier attests a COMMITTED execution - the same set the live reader uses, so a
+ *  tombstone that kept only the tier can still answer the question honestly (retest V030-07). */
+export declare function tierConfirms(tier: string | undefined | null): boolean;
+/** The tier a `reported` tombstone records. The server caps a confirming tier whose proof failed to
+ *  `execution_unconfirmed` (apps/api agent-confirm.ts, lint-locked CONFIRM-TRUTH), so a body that
+ *  says otherwise is one the current server cannot emit; the tombstone applies the same rule, so
+ *  reconfirm() - which derives from the tier - can never answer "confirmed" where resolve() answered
+ *  "not confirmed" over the same record (invariant-guard, 0.3.3). Every other tier is stored verbatim. */
+export declare function tombstoneTier(ev: EvidenceOutcome): string;
 export interface EvidenceOutcome {
     /** Decidio accepted the report and named the tier it recorded. */
     reportRecorded: boolean;

package/dist/evidence.js

@@ -7,6 +7,10 @@ export const EVIDENCE_TIERS = [
     "independently_reconciled",
 ];
 const CONFIRMING = ["sensor_observed", "application_confirmed", "independently_reconciled"];
+export function tierConfirms(tier) { return typeof tier === "string" && CONFIRMING.includes(tier); }
+export function tombstoneTier(ev) {
+    return ev.executionReportVerified === false && tierConfirms(ev.evidenceTier) ? "execution_unconfirmed" : (ev.evidenceTier ?? "recorded");
+}
 export function describeTierGap(capturedResponse) {
     const r = (capturedResponse ?? {});
     const id = r.id ?? r.recordId ?? r.Id ?? null;
@@ -32,20 +36,22 @@ export function readConfirmResponse(body, opts) {
     if (!EVIDENCE_TIERS.includes(tier)) {
         return { reportRecorded: false, executionConfirmed: false, confirmationRetryable: false, reportJournalled: journalled, diagnostic: `the gate reported an evidence tier this SDK does not recognise (${JSON.stringify(tier)}) — refusing to treat it as evidence. Upgrade @decidio/sdk; your action DID run, and ${retry}` };
     }
-    const executionConfirmed = CONFIRMING.includes(tier);
+    const rpt = body?.executionReport;
+    const hasVerdict = !!rpt && typeof rpt === "object" && typeof rpt.verified === "boolean";
+    const proofExplicitlyFailed = hasVerdict && rpt.verified === false;
+    const executionConfirmed = CONFIRMING.includes(tier) && !proofExplicitlyFailed;
     const outcome = { reportRecorded: true, evidenceTier: tier, executionConfirmed, reportJournalled: journalled };
-    if (!executionConfirmed && opts.signed)
+    if (!executionConfirmed && !proofExplicitlyFailed && opts.signed)
         outcome.diagnostic = describeTierGap(opts.capturedResponse);
-    else if (!executionConfirmed)
+    else if (!executionConfirmed && !proofExplicitlyFailed)
         outcome.diagnostic = "no signing key is configured, so the gate capped this report at an unproven agent assertion. Run `npx @decidio/sdk init` to generate the agent's key and earn a confirming tier.";
-    const rpt = body?.executionReport;
-    if (rpt && typeof rpt === "object" && typeof rpt.verified === "boolean") {
+    if (hasVerdict) {
         outcome.executionReportVerified = rpt.verified;
         if (typeof rpt.reason === "string" && rpt.reason)
             outcome.executionReportReason = rpt.reason;
-        if (!rpt.verified) {
+        if (proofExplicitlyFailed) {
             const why = typeof rpt.reason === "string" && rpt.reason ? ` (${rpt.reason})` : "";
-            outcome.diagnostic = `${outcome.diagnostic ? outcome.diagnostic + " " : ""}The signed execution report did NOT verify${why} — the report was recorded without a proven attestation. Check the agent's key/DID/registration (npx @decidio/sdk doctor).`;
+            outcome.diagnostic = `the signed execution report did NOT verify${why}, so this is NOT a confirmed execution — the gate reported tier "${tier}", and this SDK refuses to read an unproven attestation as confirmation. Your action DID run and the report IS recorded at that tier - there is nothing to re-send, and re-sending would not change the verdict; the record stands as unverified. Check the agent's key/DID/registration (npx @decidio/sdk doctor) so the NEXT execution verifies.`;
         }
     }
     return outcome;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { ResumeController } from "./resume.js";
 import { type EvidenceOutcome } from "./evidence.js";
-export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
+export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 export type { PendingAction, PendingStore, ResumeController, ResumeOutcome } from "./resume.js";
 export { guard, Guard } from "./guard.js";
 export type { GuardFacadeConfig, ProtectOptions } from "./guard.js";
@@ -12,7 +12,10 @@ export { readConfirmResponse, buildConfirmBody, describeTierGap, EVIDENCE_TIERS
 export type { EvidenceOutcome, EvidenceTier } from "./evidence.js";
 export type { RequesterIdentity } from "./signing.js";
 export interface GuardConfig {
-    /** Base URL of the Decidio gate, e.g. "https://api.decidio.io". */
+    /** Base URL of the Decidio gate. The hosted sandbox is "https://decidio-api.onrender.com",
+     *  which is also the default when this is unset; a self-hosted deployment is your own origin.
+     *  (This example named a host the product does not use — it shipped in the .d.ts, so it was the
+     *  first URL a typing-aware editor suggested to anyone configuring the SDK.) */
     apiUrl: string;
     /** The agent identity registered with Decidio (onboarding wizard), e.g. "salesforce/SalesforceBot". */
     agentId: string;

package/dist/index.js

@@ -2,7 +2,7 @@ import { DecidioSuspendedError } from "./resume.js";
 import { signBoundProof, signConfirm, assertSafeTransport, carriesCredential } from "./signing.js";
 import { canonicalize, canonicalizeArgs } from "./canonical.js";
 import { readConfirmResponse, buildConfirmBody } from "./evidence.js";
-export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
+export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 export { guard, Guard } from "./guard.js";
 export { DecidioHttpError, decisionIdProblem } from "./errors.js";
 import { DecidioHttpError, decisionIdProblem } from "./errors.js";
@@ -138,10 +138,10 @@ export function withApproval(fn, describe, config, opts) {
             }
             throw e;
         }
+        ctx = canonicalize(ctx, "describe(...)");
         const requesterIdentity = (config.agentKey && config.agentDid)
             ? signBoundProof(config.agentKey, { agentId: config.agentId, did: config.agentDid, action: ctx.action, amount: ctx.amount, scope: ctx.scope, workspaceId: config.workspaceId })
             : undefined;
-        canonicalize(ctx, "describe(...)");
         if (typeof ctx?.action !== "string" || ctx.action.trim().length === 0) {
             throw new Error(`[decidio] describe(...) must return an \`action\` string naming what is being asked (got ${JSON.stringify(ctx?.action ?? null)}). Nothing was routed or executed.`);
         }

package/dist/inngest.d.ts

@@ -1,6 +1,6 @@
 import type { RequestListener } from "node:http";
 import { verifyResumeSignature } from "./resume.js";
-import type { GuardConfig, ApprovalContext } from "./index.js";
+import type { GuardConfig, ApprovalContext, EvidenceOutcome } from "./index.js";
 /** The Inngest event Decidio's verdict is translated into. The waiting function
  *  correlates on `data.decisionId`. */
 export declare const DECIDIO_RESUME_EVENT = "decidio/decision.resolved";
@@ -24,10 +24,18 @@ export interface InngestClientLike {
         data: Record<string, any>;
     }): Promise<unknown>;
 }
+/** ONE RESULT SHAPE ACROSS EVERY DOOR (F-008), with the one field this door genuinely needs on
+ *  top of it. `status` stays because Inngest's durable path can legitimately end in `rejected` or
+ *  `blocked` without ever calling your action — the other adapters signal that by throwing. What
+ *  changed: the value is `value` (not `result`) so it reads the same as every other door, and
+ *  `confirmation` is CARRIED rather than discarded. It used to be thrown away inside the confirm
+ *  step, which made "it ran and Decidio recorded it" and "it ran and Decidio does not know"
+ *  indistinguishable to the caller. */
 export type GateStepOutcome<R> = {
     status: "executed" | "rejected" | "blocked";
     decisionId: string;
-    result?: R;
+    value?: R;
+    confirmation?: EvidenceOutcome;
 };
 /**
  * Gate an action INSIDE an Inngest function, with durable suspend on routing.

package/dist/inngest.js

@@ -22,8 +22,8 @@ export async function decidioGateStep(args) {
             return { status: "blocked", decisionId: auth.decisionId };
     }
     const result = await step.run("agent-action", args.run);
-    await step.run("decidio-confirm", async () => { await gateConfirm(config, auth.decisionId, result, args.evidence); return true; });
-    return { status: "executed", decisionId: auth.decisionId, result };
+    const confirmation = await step.run("decidio-confirm", async () => gateConfirm(config, auth.decisionId, result, args.evidence));
+    return { status: "executed", decisionId: auth.decisionId, value: result, confirmation };
 }
 export function createInngestResumeBridge(opts) {
     const secret = opts.webhookSecret ?? "";

package/dist/resume.d.ts

@@ -46,13 +46,32 @@ export interface PendingAction {
  *  `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";
+export type ExecutionState = "parked" | "claimed_preinvoke"
+/** A human or policy said NO. Terminal: the handler must never run for this decision. */
+ | "discarded" | "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. */
+/** `discarded` sits ABOVE the pre-invocation states and BELOW the execution ones, and the position
+ *  is load-bearing in both directions:
+ *
+ *  - above `parked`/`claimed_preinvoke`, so a denial beats a payload whose deletion FAILED. That is
+ *    the whole F-001 fix: the old code deleted the payload and wrote no state, the shipped file
+ *    store swallows unlink errors, and the ledger therefore still read `parked` — so a later,
+ *    out-of-order `approved` signal executed an action a human had explicitly refused.
+ *  - below `invoking`…`reported` — but rank is NOT how the two are reconciled, and relying on it
+ *    was wrong in both directions. A stronger marker written beside a tombstone outranked the
+ *    denial AND was then deleted by setState's weaker-marker sweep, so a refused decision read back
+ *    as runnable. `resolve()` therefore prefers the DENIAL whenever its marker is present, at any
+ *    rank. That decides authority, not truth: if an execution marker is there too, something DID
+ *    run, and swallowing that is the opposite failure — so resolve() flags the conflict on the
+ *    record (`executionDespiteDenial`), recover() reports it, and reconfirm() says so instead of
+ *    "this process never executed it". A denial governs the decision; it never edits history. */
 export declare const EXECUTION_STATES: readonly ExecutionState[];
-/** States from which the handler must NEVER be invoked again automatically. */
+/** States from which the handler must NEVER be invoked again automatically. `discarded` is here
+ *  FOREVER — `claim()` gates on this list, so a denied decision can never be claimed again, by this
+ *  process or any future one. */
 export declare const NON_REPLAYABLE: readonly ExecutionState[];
 export interface ExecutionRecord {
     decisionId: string;
@@ -84,6 +103,11 @@ export interface ExecutionRecord {
         kind: "ed25519" | "hmac";
         sig: string;
     };
+    /** WHY this decision is `discarded` — the verdict a human or policy returned, and any reason
+     *  text. Recorded on the tombstone so recovery can say "a human rejected this" rather than
+     *  reporting a bare terminal state an operator would have to go and look up. */
+    verdict?: "rejected" | "blocked";
+    discardReason?: 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
@@ -95,10 +119,26 @@ export interface ExecutionRecord {
     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. */
+    /** `workerStopped` records that a HUMAN asserted the claiming worker was stopped before this
+     *  decision was released — the assertion that made the release legal. It is stamped here because
+     *  the whole point of requiring it is to put a name against that judgement: without it the ledger
+     *  showed a decision released from `invoking` with no trace that anyone had claimed to check. */
     reconciled?: {
         outcome: SettleOutcome;
         reason?: string;
         at: string;
+        workerStopped?: boolean;
+    };
+    /** Set when a DENIED decision also carries an execution record. That pair is the single most
+     *  alarming state the machine can hold — a human refused it and something ran anyway — so it must
+     *  never resolve to silence. The revision chain cannot produce it (no transition publishes over
+     *  a denial); it is DERIVED by the legacy-marker reader, and PERSISTED only when a 0.2/0.3
+     *  directory that held a denial marker beside an execution marker is migrated onto the chain —
+     *  there it is the record of what that layout held. */
+    executionDespiteDenial?: {
+        state: ExecutionState;
+        at: string;
+        hasEvidence: boolean;
     };
     at: string;
 }
@@ -127,8 +167,38 @@ export declare class DecidioAlreadySettledError extends Error {
     decisionId: string;
     constructor(decisionId: string);
 }
+/** A DENIAL IS TERMINAL, and that has to be enforced where the state is WRITTEN — not only where
+ *  it is reconciled. Refusing `settle` from `discarded` closed the operator's door and left three
+ *  others open, each of which walked a refused action all the way to execution:
+ *    - `discarded` sits mid-rank in EXECUTION_STATES, so the advance-only rule happily accepted
+ *      `discarded → invoking → executed_unreported`;
+ *    - `markDiscarded` leaves the record UNOWNED (`attemptId: ""`) when nothing had claimed it, so
+ *      the ownership fence — which skips when there is no owner — did not stop that walk either;
+ *    - reachable through the shipped controller, not just the store API: an `approved` signal
+ *      claims, a `rejected` signal writes the tombstone, and the first call then invokes anyway.
+ *  Typed, for the same reason DecidioAlreadySettledError is: the reporting stage deliberately keeps
+ *  going when the ledger fails, so a generic error here would read as "the disk write failed" and
+ *  send an authority report for an action a human refused. */
+/** `recover()` could not enumerate the ledger. It is a THROW, not an empty list, because those two
+ *  are the same value to a caller and mean opposite things: `[]` is "you owe nothing", and this is
+ *  "I cannot tell you what you owe". The old code logged to stderr and returned `[]`, so a script
+ *  reading `if (!(await recover()).length) allClear()` treated an unreadable store — a permissions
+ *  change, a mounted volume gone, a corrupt directory — as proof that no action was left
+ *  outstanding. A crash is the correct failure here; silence is not. */
+export declare class DecidioRecoveryUnavailableError extends Error {
+    cause: unknown;
+    constructor(cause: unknown);
+}
+export declare class DecidioDeniedError extends Error {
+    decisionId: string;
+    verdict: string;
+    constructor(decisionId: string, verdict: string);
+}
 export declare const SETTLE_OUTCOMES: readonly SettleOutcome[];
-export declare function assertSettlable(id: string, state: ExecutionState, outcome: SettleOutcome, hasObservedEvidence?: boolean): void;
+export declare function assertSettlable(id: string, state: ExecutionState, outcome: SettleOutcome, opts?: {
+    hasObservedEvidence?: boolean;
+    workerStopped?: boolean;
+}): void;
 export interface ClaimResult {
     /** True only when THIS attempt may proceed to invoke. */
     ok: boolean;
@@ -148,8 +218,13 @@ export interface ClaimResult {
 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>;
+    /** CLEANUP ONLY. Removing a row must never be what prevents a second execution.
+     *
+     *  `attemptId` scopes the cleanup to its OWNER. A superseded attempt tidies up on its way out
+     *  (see the stale-attempt branch of the reporting stage), and without this it deleted the payload
+     *  of the attempt that had legitimately taken over — the live worker's own recovery data, removed
+     *  by the dead one. Omit it for genuine housekeeping that is not attributable to an attempt. */
+    delete(decisionId: string, attemptId?: string): Promise<void>;
     /** Parked entries only — anything claimed or beyond is excluded. */
     list(): Promise<PendingAction[]>;
     /** Atomically take ownership for THIS attempt. Must refuse when the decision is already
@@ -164,6 +239,12 @@ export interface PendingStore {
     markIndeterminate(decisionId: string, attemptId: string, error: string): Promise<void>;
     /** Decidio accepted the execution report. */
     markReported(decisionId: string, attemptId: string, confirmation: string): Promise<void>;
+    /** A human or policy DENIED this decision. Writes the terminal tombstone that makes the decision
+     *  permanently unclaimable — and it must be written BEFORE any payload cleanup, because cleanup
+     *  is best-effort and a store that swallows its failure would otherwise leave the row readable as
+     *  `parked`. A conforming store persists this durably; returning without persisting reintroduces
+     *  F-001. Safe to call more than once (a denial is idempotent). */
+    markDiscarded(decisionId: string, verdict: "rejected" | "blocked", reason?: 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. */
@@ -181,6 +262,7 @@ export interface PendingStore {
         evidence?: unknown;
         reason?: string;
         evidenceSig?: ExecutionRecord["evidenceSig"];
+        workerStopped?: boolean;
     }): 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
@@ -200,13 +282,16 @@ export declare class MemoryPendingStore implements PendingStore {
     private advance;
     put(p: PendingAction): Promise<void>;
     get(id: string): Promise<PendingAction | null>;
-    delete(id: string): Promise<void>;
+    /** Cleanup only — the execution record STAYS. Scoped to the owning attempt: see PendingStore. */
+    delete(id: string, attemptId?: string): Promise<void>;
+    private ownsPayload;
     list(): 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>;
+    markDiscarded(id: string, verdict: "rejected" | "blocked", reason?: string): Promise<void>;
     getExecution(id: string): Promise<ExecutionRecord | null>;
     listExecutions(): Promise<ExecutionRecord[]>;
     /** OPERATOR RECONCILIATION — the ONE legal backwards transition, and the only exit from
@@ -220,9 +305,28 @@ export declare class MemoryPendingStore implements PendingStore {
         evidence?: unknown;
         reason?: string;
         evidenceSig?: ExecutionRecord["evidenceSig"];
+        workerStopped?: boolean;
     }): Promise<void>;
     releasePreinvoke(id: string, attemptId: string): Promise<void>;
 }
+/** The ACL principal for THIS process, resolved from the token SID rather than the login name.
+ *
+ *  Shared by every hardening site (F-009): the durable pending directory AND the `.env` the CLI
+ *  writes. `writeSecretFile` had its own weaker copy that granted `userInfo().username` — who
+ *  logged IN, which is not always who is writing. A Windows service, a scheduled task or an
+ *  impersonated thread has a different effective identity, and granting the wrong name while
+ *  `/inheritance:r` strips every other ACE is how a hardening step locks the writer out of its own
+ *  secrets. A SID also needs no localisation or escaping, where a name can carry spaces, a domain
+ *  prefix, or be renamed out from under the ACE. */
+export declare function windowsPrincipal(): string;
+/** Restrict a FILE to its owner on Windows, with the same verify-then-roll-back discipline as
+ *  `hardenDir`. Returns null on success, or the reason it could not be done.
+ *
+ *  The verification is the point, and it is what the CLI's own version lacked: a SUCCESSFUL
+ *  `icacls` that locks this process out of the file it just wrote is more dangerous than a failed
+ *  one, and it printed nothing at all. Here the file is read back, and if that fails the
+ *  inheritance goes back rather than leaving credentials the SDK can no longer read. */
+export declare function hardenFile(file: string): string | null;
 /** 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
@@ -243,51 +347,78 @@ export declare class FilePendingStore implements PendingStore {
     constructor(dir: string);
     private key;
     private path;
-    /** 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 revPath;
+    /** Legacy (0.2/0.3) marker path, read for migration and never written. */
+    private markerPath;
+    private listRevs;
+    private legacyMarkers;
+    /** Write `text` to a fresh temp file beside `target`, fsynced. Returns the temp path. */
+    private writeTemp;
+    /** Durable write for the PAYLOAD file (not the chain): temp → fsync → atomic rename. */
     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;
+    /** The head of the chain, or the migrated reading of a legacy layout that has not been
+     *  upgraded. Corruption is REPORTED, never treated as absent: an unreadable record is the one
+     *  that proves an action already ran. */
+    private readHead;
+    /** TEST SEAM, a no-op in production. Called with the operation name and the state about to be
+     *  published, AFTER validation and BEFORE the publish — the exact window a concurrent writer
+     *  can land in. The deterministic two-process suites subclass the store and block here so the
+     *  race the retest found is reproduced on purpose, every run, rather than by luck. */
+    protected _barrier(_op: string, _id: string, _next: ExecutionState): void;
+    /** ONE TRANSITION = read head → compute successor → publish with link(). `compute` receives the
+     *  current record (null if none) and returns the successor, or null for "nothing to write" (a
+     *  refusal that is a return value, like a lost claim, rather than an error). Every rule runs
+     *  INSIDE `compute`, against the revision that is about to be superseded; if a rival publishes
+     *  first, `compute` runs again against the rival's record. */
+    private transition;
+    /** The 0.2/0.3 reading of a marker layout — strongest marker wins, a denial marker wins at any
+     *  rank, and a denial beside an execution marker is reported as both. Used ONLY to migrate an
+     *  older directory and to report one that could not be migrated; nothing writes markers. */
+    private resolveLegacyMarkers;
+    /** The generic ADVANCE, with every fence evaluated against the head the publish will supersede.
+     *  `pre` is a per-method check (markInvoking's claim requirement) that must ALSO run inside the
+     *  transition — a check that runs before it is a check against a snapshot. */
     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>;
+    delete(id: string, attemptId?: string): Promise<void>;
     list(): 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>;
+    markDiscarded(id: string, verdict: "rejected" | "blocked", reason?: 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. */
+    /** OPERATOR RECONCILIATION — see MemoryPendingStore.settle. The one legal backwards move, and
+     *  now a transition like any other: two conflicting settlements both validate, both try to
+     *  publish the next revision, exactly one wins, and the loser re-validates against the winner's
+     *  record — where `assertSettlable` refuses it (captured evidence protects a `committed`; a
+     *  `parked` record refuses `committed`). Before this, both won and the second erased the first. */
     settle(id: string, outcome: SettleOutcome, opts?: {
         evidence?: unknown;
         reason?: string;
         evidenceSig?: ExecutionRecord["evidenceSig"];
+        workerStopped?: boolean;
     }): 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. */
+    /** ONE-WAY MIGRATION of older layouts, run at construction.
+     *    0.2/0.3 one-marker-per-state  → the head of a fresh revision chain (markers removed)
+     *    0.1.x `<id>.json` with no state → parked
+     *    0.1.x `<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
+     *    0.1.x `reports/<id>.json`      → executed_unreported (the report can be re-sent)
+     *  Nothing ambiguous is made executable by an upgrade, and nothing unreadable is silently
+     *  dropped: a key whose markers cannot be parsed is left exactly as found and reads as corrupt. */
     migrateLegacy(): {
         migrated: number;
         indeterminate: number;
         reports: number;
+        chained: 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
@@ -331,6 +462,11 @@ export type RecoveryState =
  *  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"
+/** DENIED, and an execution marker exists anyway. Nothing here will run it and nothing will
+ *  report it — the decision is closed — but an effect may exist downstream, so this is the one
+ *  recovery row that asks a human to go and look. It cannot be reconciled or retried; a denial is
+ *  terminal. Callers switching exhaustively on this union must handle it. */
+ | "denied_with_evidence"
 /** 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. */
@@ -492,6 +628,7 @@ export interface ResumeController extends ResumeConfig {
         outcome: SettleOutcome;
         evidence?: unknown;
         reason?: string;
+        workerStopped?: boolean;
     }): 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