@decidio/sdk 0.3.0 → 0.3.3

package/README.md

@@ -148,8 +148,12 @@ evidence is yours, not ours. To also prove *who* issued it, pin your workspace's
 record verify panel — or simply read it off the `receipt` command's output, which prints your
 workspace's issuer DID from the authenticated response so you never have to hunt for it).
 
-**What VALID means — and what it does not.** A pinned `VALID` proves the receipt's bytes were
-sealed by your workspace's issuer and are unaltered since. It does **not** prove the approved
+**What VALID means — and what it does not.** A pinned `VALID` proves the receipt's **claims** were
+sealed by your workspace's issuer and that none of them has changed since. Not its *bytes*: the
+signature covers the record's canonical form (JCS), so reformatting the file — reindenting it,
+minifying it, reordering keys — still verifies, and should, because none of that alters a claim.
+If you need byte-for-byte custody, hash the file and keep that hash yourself; this proves the
+content, which is what an auditor is asking about. It does **not** prove the approved
 action ran. Execution is confirmed *after* the seal, and a sealed record is immutable, so the
 receipt's own `authority.result` and `confirmation.status` are a snapshot taken at seal time — a
 receipt for an approved-but-never-executed action verifies `VALID`, correctly. The verifier now
@@ -445,6 +449,88 @@ for engines you don't. Each adapter's shipped `.d.ts` header documents its wirin
 @decidio/sdk quickstart` is the fastest runnable end-to-end.
 
 
+
+
+## The durable store is a revision chain (0.3.2)
+
+`FilePendingStore` keeps each decision's execution record as an **append-only revision chain** —
+`<id>.rev.1`, `<id>.rev.2`, … — and the head is the highest number. Every state change reads the
+head, validates against exactly that record, writes the successor to a temp file, and publishes it
+with `link()` to the next revision number. `link()` fails if that name already exists, so **exactly
+one writer wins each revision**, with no lock, no timeout and no daemon — on any volume that
+supports hard links (NTFS, ext4, APFS, XFS; not FAT/exFAT, and not every network or FUSE mount —
+on those every write fails closed rather than silently degrading). A loser re-reads the new head
+and validates again — against what actually happened, not a snapshot. **No revision file is ever
+deleted:** a name that could be reused is a race that could be lost, so the chain is genuinely
+append-only and a decision's whole history stays readable in place.
+
+This replaced the 0.2/0.3 one-marker-per-state layout after an external retest showed why it had to:
+that layout made a transition in three separate steps (read the markers, write the new one, sweep
+the weaker ones), so a process holding `claimed_preinvoke` could validate its snapshot, lose to a
+second process that durably wrote *and returned* a denial, then write `invoking` anyway — and its
+sweep deleted the tombstone. The SDK reported a denial as final and ran the denied action. Every
+*sequential* schedule was safe; the window was inside one transition. The chain has no such window:
+nothing ever deletes the head, and the rule that refuses a denied decision now runs against the
+denial that just landed.
+
+**Upgrading.** A directory in the older layout is migrated once, at the first construction of a
+0.3.2 store: each decision's markers become the head of a fresh chain and the markers are removed.
+Corrupt markers are left exactly as found and the decision reads as unreadable until a person
+inspects it. **Stop every older worker that shares the directory BEFORE the first 0.3.2 process
+constructs its store, then upgrade them together.** The one-time migration reads the markers it
+finds and removes exactly those; an older SDK still writing leaves a marker beside a chain, and
+that decision is then *unreadable* by design — neither reading can be trusted over the other, so
+the store refuses to pick one.
+
+**Custom stores.** The `PendingStore` contract has said since 0.2.0 that every method must be atomic
+against concurrent callers. The shipped file store did not honor that until now; a custom store must.
+The deterministic two-process schedules that proved the defect live in
+`packages/conformance/acceptance.mjs` (criteria 7a, 7b and 7c): a denial landing while an invoker
+is paused between validating and publishing; two conflicting settlements from one head; and a denier
+paused while the approver publishes four revisions past it. A store that cannot pass them is not
+atomic, whatever its methods say.
+
+## Reading a receipt
+
+The cryptography is only half the evidence. These are the fields that an outside reader has
+actually misread on a first run, and what each one means.
+
+**`ratified: yes` next to `deciders: 0` is not a contradiction.** `deciders` is the list of people
+nominated **in advance** to decide. When an agent's request is *routed* rather than pre-assigned,
+that list is empty — nobody was nominated, because the request had not happened yet. The person who
+actually decided is the **ratifier** (`ratifiedBy`). So a receipt for a human-approved action reads
+`deciders: 0, ratified: yes`, and the human is recorded, in the field named for the role they
+played. The verifier prints this explanation whenever the pair appears.
+
+**`appliedLimits` is what the request was MEASURED AGAINST, not a rule that fired.** It holds up to
+three entries, and only those that have a value: `requested_amount` (the amount actually asked for),
+`auto_approve_threshold` and `hard_cap` (the ceilings on the agent's own token). So a decision routed
+to a human because *no rule matched* can still list an `auto_approve_threshold` — that is the bar the
+request was compared to and did not clear, not a limit that was applied to it. Read
+`requested_amount` as the ask, the other two as ceilings.
+
+**`firedRules` is what the policy engine actually matched — for any verdict.** It is not an
+auto-approve indicator: a **blocked** request carries the deny-by-default backstop rule here, so
+non-empty does not mean "approved" and empty does not mean "blocked". The field that states the
+disposition is `authority.result`; `firedRules` tells you which named, versioned rules produced it.
+
+**`payloadSchemaUri` is a `urn:`, not a URL.** It is content-addressed —
+`urn:decidio:sealed-payload:1:sha256:<hash>` — so it *identifies* the exact schema the record was
+sealed under and pins it against substitution. It does not locate a document, and nothing will
+resolve it. (Shipping the schema alongside the verifier so you can check the hash yourself is on
+the roadmap; today the URN is an identifier only, and this note exists so it does not look broken.)
+
+**`prevHash` proves a pointer, not an ancestry.** A non-null `prevHash` shows this record was
+sealed after a specific predecessor, but a single-file verification cannot check that predecessor
+exists or is what it claims. Verify a chain (`verify a.json b.json c.json`) when the sequence
+matters.
+
+**Pinning is trust-on-first-use.** The first time you fetch a receipt, the record *and* the issuer
+DID arrive in the same authenticated response — so that first check trusts the connection, not the
+key. What pinning buys is everything afterwards: record the DID once, out of band if you can, and
+every later verification is checked against a key you chose rather than one you were handed. The
+verifier says so on every unpinned run.
+
 ## Upgrading from 0.2.x to 0.3.0
 
 0.3.0 is a breaking release. Every item below changes behaviour a 0.2.x caller may depend on, so

package/dist/adapters/_gate.js

@@ -14,7 +14,7 @@ export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
     return a;
 }
 export async function gateAuthorize(config, ctx) {
-    canonicalize(ctx, "describe(...)");
+    ctx = canonicalize(ctx, "describe(...)");
     assertSafeTransport(config.apiUrl, carriesCredential(config));
     const f = config.fetchImpl ?? fetch;
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;

package/dist/cli.js

@@ -119,6 +119,18 @@ function writeSecretFile(path, body) {
         console.warn(`⚠ could not restrict ${path} to owner-only on this Windows volume (${why}) — it keeps the directory's inherited permissions. For production, move these values to a secret manager.`);
     }
 }
+async function revokeFreshMint(jti, bearer, writeError, target) {
+    err(`✘ could not write ${target} (${writeError?.message ?? writeError}). The token minted a moment ago (jti ${jti}) is LIVE until revoked - revoking it now.`);
+    const rv = await api(`/api/workspace/agent-token/${encodeURIComponent(jti)}`, { method: "DELETE" }, bearer);
+    if (rv.status >= 200 && rv.status < 300) {
+        err(`  ✔ the token minted a moment ago (jti ${jti}) was REVOKED again, so nothing live was left behind. Fix the cause above and re-run - it will mint a fresh one.`);
+        return true;
+    }
+    err(`  ⚠ the token minted a moment ago (jti ${jti}) is LIVE and could NOT be revoked (${rv.status}). Revoke it by hand, or re-run init - the server keeps one active token per agent, so a fresh mint supersedes it:`);
+    err(`    npx @decidio/sdk tokens revoke ${jti}`);
+    err(`    npx @decidio/sdk tokens list --mine`);
+    return false;
+}
 function upsertEnv(updates) {
     const remaining = { ...updates };
     const updatedKeys = new Set();
@@ -341,8 +353,19 @@ async function cmdInit(agentId, opts = {}) {
         envOut.DECIDIO_WORKSPACE_ID = workspaceId;
     if (tokenJti)
         envOut.DECIDIO_TOKEN_JTI = tokenJti;
-    prepareEnvForWrite();
-    upsertEnv(envOut);
+    try {
+        prepareEnvForWrite();
+        upsertEnv(envOut);
+    }
+    catch (e) {
+        if (agentToken && tokenJti)
+            await revokeFreshMint(tokenJti, mintBearer, e, ENV_PATH);
+        else if (agentToken)
+            err(`✘ could not write ${ENV_PATH} (${e?.message ?? e}). The token minted a moment ago is LIVE and the server returned no revocation id - find and revoke it: npx @decidio/sdk tokens list --mine`);
+        else
+            err(`✘ could not write ${ENV_PATH} (${e?.message ?? e}). No token was minted this run.`);
+        return 1;
+    }
     for (const [k, v] of Object.entries(envOut))
         process.env[k] = v;
     log(`✔ wrote ${ENV_PATH} (owner-only where the OS supports it) — every decidio command reads it from this directory (your script loads it with node --env-file=.env)`);
@@ -597,10 +620,13 @@ async function cmdReceipt(id, jsonMode = false) {
     }
     log(`  Verify it offline — no Decidio account or network needed (the verifier is built in):`);
     if (issuer) {
+        log(`  Record your workspace's issuer DID — copy this line, and pin it forever:`);
+        log(``);
+        log(`${issuer}`);
+        log(``);
+        log(`  Then verify, pinned to it (the same DID, inline — copy from the line above, not this one,`);
+        log(`  which your terminal may wrap):`);
         log(`    npx @decidio/sdk verify --issuer ${issuer} ${name}`);
-        log(`  That pins the check to your workspace's issuer DID (read from the authenticated`);
-        log(`  response above — record it once, then pin it forever):`);
-        log(`    ${issuer}`);
         log(`  Without --issuer the verifier proves the receipt is internally consistent, but NOT who`);
         log(`  issued it; it says so in its output.`);
     }
@@ -621,6 +647,10 @@ function cmdVerify(argsIn) {
                 err("✘ --issuer needs a did:key value (a bare or EMPTY --issuer must not silently verify unpinned).");
                 return 2;
             }
+            if (expectedIssuer !== undefined && expectedIssuer !== v) {
+                err(`✘ --issuer given twice with different values (${expectedIssuer} then ${v}) — refusing to choose which one you meant to pin to.`);
+                return 2;
+            }
             expectedIssuer = v;
             i++;
         }
@@ -630,6 +660,10 @@ function cmdVerify(argsIn) {
                 err("✘ --issuer needs a did:key value.");
                 return 2;
             }
+            if (expectedIssuer !== undefined && expectedIssuer !== v) {
+                err(`✘ --issuer given twice with different values (${expectedIssuer} then ${v}) — refusing to choose which one you meant to pin to.`);
+                return 2;
+            }
             expectedIssuer = v;
         }
         else if (!a.startsWith("-")) {
@@ -711,14 +745,14 @@ async function cmdQuickstart(opts = {}) {
             const prev = readFileSync(envFile, "utf8");
             const prevId = prev.match(/^DECIDIO_AGENT_ID=(.+)$/m)?.[1];
             const prevJti = prev.match(/^DECIDIO_TOKEN_JTI=(.+)$/m)?.[1];
+            const carried = new Set((prev.match(/^DECIDIO_ORPHANED_TOKEN_JTI=(.+)$/m)?.[1] ?? "").split(",").map((s) => s.trim()).filter(Boolean));
             if (prevId && prevId !== agentId) {
                 if (prevJti) {
                     const rv = await api(`/api/workspace/agent-token/${encodeURIComponent(prevJti)}`, { method: "DELETE" }, session);
                     if (rv.status >= 200 && rv.status < 300)
                         log(`  ✔ the previous tour agent (${prevId}) had its token REVOKED before this tour replaced it — no live credential is left behind`);
                     else {
-                        const carried = [...(prev.match(/^DECIDIO_ORPHANED_TOKEN_JTI=(.+)$/m)?.[1] ?? "").split(",").filter(Boolean), prevJti];
-                        envOut.DECIDIO_ORPHANED_TOKEN_JTI = [...new Set(carried)].join(",");
+                        carried.add(prevJti);
                         log(`  ⚠ could not revoke the previous tour's token (jti ${prevJti}, ${rv.status}) — it is still LIVE. Its id is kept in ${envFile} as DECIDIO_ORPHANED_TOKEN_JTI, and \`quickstart cleanup\` will retry it; or revoke it by hand: npx @decidio/sdk tokens revoke ${prevJti}`);
                     }
                 }
@@ -726,12 +760,34 @@ async function cmdQuickstart(opts = {}) {
                     log(`  ⚠ the previous tour file carried no revocation id, so its token (if any) must be revoked from your Decidio app.`);
                 }
             }
+            if (carried.size) {
+                envOut.DECIDIO_ORPHANED_TOKEN_JTI = [...carried].join(",");
+                log(`  • ${carried.size} orphaned token id(s) from earlier replacements carried forward — \`quickstart cleanup\` will retry them.`);
+            }
+        }
+        try {
+            writeSecretFile(envFile, Object.entries(envOut).map(([k, v]) => `${k}=${v}`).join("\n") + "\n");
+        }
+        catch (e) {
+            if (mint.body?.jti)
+                await revokeFreshMint(mint.body.jti, session, e, envFile);
+            else
+                err(`✘ could not write ${envFile} (${e?.message ?? e}). The tour token minted a moment ago is LIVE and the server returned no revocation id - find and revoke it: npx @decidio/sdk tokens list --mine`);
+            return 1;
         }
-        writeSecretFile(envFile, Object.entries(envOut).map(([k, v]) => `${k}=${v}`).join("\n") + "\n");
         log(`  ✔ this directory already has an agent in .env — tour credentials went to ${envFile} (your agent is untouched)`);
     }
     else {
-        upsertEnv(envOut);
+        try {
+            upsertEnv(envOut);
+        }
+        catch (e) {
+            if (mint.body?.jti)
+                await revokeFreshMint(mint.body.jti, session, e, envFile);
+            else
+                err(`✘ could not write ${envFile} (${e?.message ?? e}). The tour token minted a moment ago is LIVE and the server returned no revocation id - find and revoke it: npx @decidio/sdk tokens list --mine`);
+            return 1;
+        }
     }
     const failTour = async (code) => {
         log("");

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;
@@ -47,7 +51,7 @@ export function readConfirmResponse(body, opts) {
             outcome.executionReportReason = rpt.reason;
         if (proofExplicitlyFailed) {
             const why = typeof rpt.reason === "string" && rpt.reason ? ` (${rpt.reason})` : "";
-            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; check the agent's key/DID/registration (npx @decidio/sdk doctor), then ${retry}`;
+            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

@@ -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

@@ -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/resume.d.ts

@@ -129,11 +129,12 @@ export interface ExecutionRecord {
         at: string;
         workerStopped?: boolean;
     };
-    /** DERIVED AT READ TIME, never persisted: set when a DENIED decision also carries an execution
-     *  marker. 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. Only the file store can hold
-     *  it (the memory store keeps one record per decision); a crash between writing a marker and
-     *  sweeping the weaker ones, or a 0.1.x report migrated beside a tombstone, both produce it. */
+    /** 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;
@@ -346,19 +347,37 @@ 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>;
@@ -374,10 +393,11 @@ export declare class FilePendingStore implements PendingStore {
     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;
@@ -385,14 +405,20 @@ export declare class FilePendingStore implements PendingStore {
         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

package/dist/resume.js

@@ -5,8 +5,8 @@ import { userInfo } from "node:os";
 import { execFileSync } from "node:child_process";
 import { signConfirm, canonicalize as jcs, assertSafeTransport, carriesCredential } from "./signing.js";
 import { canonicalize as toCanonical, DecidioUnsafeArgumentsError } from "./canonical.js";
-import { readConfirmResponse, buildConfirmBody } from "./evidence.js";
-import { DecidioHttpError } from "./errors.js";
+import { readConfirmResponse, buildConfirmBody, tierConfirms, tombstoneTier } from "./evidence.js";
+import { DecidioHttpError, decisionIdProblem } from "./errors.js";
 const argsBindingBytes = (p) => Buffer.from(jcs({ decisionId: p.decisionId, action: p.action, amount: p.amount, ...(p.scope !== undefined ? { scope: p.scope } : {}), args: p.args }), "utf8");
 function signArgs(p, agentKey, webhookSecret) {
     const bytes = argsBindingBytes(p);
@@ -321,14 +321,40 @@ export class FilePendingStore {
             this.migrateLegacy();
         }
         catch (e) {
-            console.error(`[decidio] could not upgrade the 0.1.x pending layout in ${dir} (${e?.message ?? e}). Entries written by 0.1.x may not appear in recover() — inspect the directory before assuming it is empty.`);
+            console.error(`[decidio] could not upgrade the older pending layout in ${dir} (${e?.message ?? e}). Entries written by an older SDK may not appear in recover() — inspect the directory before assuming it is empty.`);
         }
     }
     key(id) { return id.replace(/[^\w.-]/g, "_"); }
     path(id) { return join(this.dir, `${this.key(id)}.json`); }
-    statePath(id, s) { return join(this.dir, `${this.key(id)}.${s}`); }
-    writeAtomic(file, text) {
-        const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    revPath(key, n) { return join(this.dir, `${key}.rev.${n}`); }
+    markerPath(key, s) { return join(this.dir, `${key}.${s}`); }
+    listRevs(key, names) {
+        const prefix = `${key}.rev.`;
+        const out = [];
+        if (!names) {
+            try {
+                names = readdirSync(this.dir);
+            }
+            catch {
+                return out;
+            }
+        }
+        for (const name of names) {
+            if (!name.startsWith(prefix))
+                continue;
+            const tail = name.slice(prefix.length);
+            if (tail.length && /^\d+$/.test(tail))
+                out.push(Number(tail));
+        }
+        return out;
+    }
+    legacyMarkers(key, names) {
+        if (names)
+            return EXECUTION_STATES.filter((s) => names.includes(`${key}.${s}`));
+        return EXECUTION_STATES.filter((s) => existsSync(this.markerPath(key, s)));
+    }
+    writeTemp(target, text) {
+        const tmp = `${target}.${process.pid}.${randomUUID()}.tmp`;
         const fd = openSync(tmp, "w", 0o600);
         try {
             writeFileSync(fd, text);
@@ -337,14 +363,83 @@ export class FilePendingStore {
         finally {
             closeSync(fd);
         }
+        return tmp;
+    }
+    writeAtomic(file, text) {
+        const tmp = this.writeTemp(file, text);
         renameSync(tmp, file);
     }
-    resolve(id) {
+    readHead(id, names) {
+        const key = this.key(id);
+        for (let tries = 0; tries < 4; tries++) {
+            const revs = this.listRevs(key, names);
+            const markers = this.legacyMarkers(key, names);
+            names = undefined;
+            if (revs.length === 0) {
+                if (markers.length === 0)
+                    return { rec: null, rev: 0, corrupt: [] };
+                const legacy = this.resolveLegacyMarkers(key);
+                return { rec: legacy.rec, rev: 0, corrupt: legacy.corrupt };
+            }
+            if (markers.length) {
+                return { rec: null, rev: Math.max(...revs), corrupt: markers.map((s) => `${this.markerPath(key, s)}: a legacy state marker beside the revision chain — written by an older SDK after this directory was upgraded, or left by an interrupted upgrade; the two cannot be reconciled automatically`) };
+            }
+            const top = Math.max(...revs);
+            const f = this.revPath(key, top);
+            try {
+                const r = JSON.parse(readFileSync(f, "utf8"));
+                if (!r || typeof r !== "object" || !EXECUTION_STATES.includes(r.state)) {
+                    return { rec: null, rev: top, corrupt: [`${f}: the record carries no recognised state (${JSON.stringify(r?.state ?? null)})`] };
+                }
+                return { rec: r, rev: top, corrupt: [] };
+            }
+            catch (e) {
+                if (e?.code === "ENOENT")
+                    continue;
+                return { rec: null, rev: top, corrupt: [`${f}: ${e?.message ?? e}`] };
+            }
+        }
+        return { rec: null, rev: 0, corrupt: [`${key}: the revision chain changed under every read attempt`] };
+    }
+    _barrier(_op, _id, _next) { }
+    transition(id, op, compute) {
+        const key = this.key(id);
+        for (let attempt = 0; attempt < 16; attempt++) {
+            const { rec, rev, corrupt } = this.readHead(id);
+            if (corrupt.length)
+                throw new DecidioStateCorruptError(id, corrupt);
+            const next = compute(rec, rev);
+            if (next === null)
+                return null;
+            this._barrier(op, id, next.state);
+            const target = this.revPath(key, rev + 1);
+            const tmp = this.writeTemp(target, JSON.stringify(next, null, 2));
+            try {
+                linkSync(tmp, target);
+            }
+            catch (e) {
+                try {
+                    rmSync(tmp);
+                }
+                catch { }
+                if (e?.code === "EEXIST")
+                    continue;
+                throw e;
+            }
+            try {
+                rmSync(tmp);
+            }
+            catch { }
+            return next;
+        }
+        throw new Error(`[decidio] ${id}: could not publish a state transition after 16 attempts — another writer kept winning the next revision. Retry, or look for a process writing this decision in a loop.`);
+    }
+    resolveLegacyMarkers(key) {
         const corrupt = [];
         let best = null;
         let denial = null;
         for (const s of EXECUTION_STATES) {
-            const f = this.statePath(id, s);
+            const f = this.markerPath(key, s);
             if (!existsSync(f))
                 continue;
             try {
@@ -363,39 +458,23 @@ export class FilePendingStore {
         const ran = best && rank(best.state) >= rank("invoking") ? best : null;
         return { rec: ran ? { ...denial, executionDespiteDenial: { state: ran.state, at: ran.at, hasEvidence: !!ran.hasEvidence } } : denial, corrupt };
     }
-    setState(id, attemptId, state, patch = {}) {
-        const { rec, corrupt } = this.resolve(id);
-        if (corrupt.length)
-            throw new DecidioStateCorruptError(id, corrupt);
-        const cur = rec ?? { decisionId: id, state: "parked", attemptId: null, at: new Date().toISOString() };
-        if (cur.attemptId && cur.attemptId !== attemptId) {
-            throw new DecidioStaleAttemptError(id, cur.attemptId, cur.state);
-        }
-        assertNotDenied(id, cur, state);
-        assertNotSettled(id, cur, state);
-        if (rank(state) < rank(cur.state)) {
-            throw new Error(`[decidio] ${id}: refusing to move ${cur.state} → ${state}; execution state only ever advances.`);
-        }
-        const next = { ...cur, ...patch, decisionId: id, attemptId, state, at: new Date().toISOString() };
-        this.writeAtomic(this.statePath(id, state), JSON.stringify(next, null, 2));
-        for (const s of EXECUTION_STATES) {
-            if (s === state)
-                continue;
-            if (rank(s) >= rank(state))
-                continue;
-            const f = this.statePath(id, s);
-            try {
-                if (existsSync(f))
-                    rmSync(f);
-            }
-            catch { }
-        }
+    setState(id, attemptId, state, patch = {}, pre) {
+        this.transition(id, "advance", (rec) => {
+            const cur = rec ?? { decisionId: id, state: "parked", attemptId: null, at: new Date().toISOString() };
+            pre?.(cur);
+            if (cur.attemptId && cur.attemptId !== attemptId)
+                throw new DecidioStaleAttemptError(id, cur.attemptId, cur.state);
+            assertNotDenied(id, cur, state);
+            assertNotSettled(id, cur, state);
+            if (rank(state) < rank(cur.state))
+                throw new Error(`[decidio] ${id}: refusing to move ${cur.state} → ${state}; execution state only ever advances.`);
+            return { ...cur, ...patch, decisionId: id, attemptId, state, at: new Date().toISOString() };
+        });
     }
     async put(p) {
         this.writeAtomic(this.path(p.decisionId), JSON.stringify(p, null, 2));
-        if (!this.resolve(p.decisionId).rec) {
-            this.writeAtomic(this.statePath(p.decisionId, "parked"), JSON.stringify({ decisionId: p.decisionId, state: "parked", attemptId: null, action: p.action, at: new Date().toISOString() }, null, 2));
-        }
+        this.transition(p.decisionId, "put", (cur) => cur ? null
+            : { decisionId: p.decisionId, state: "parked", attemptId: null, action: p.action, at: new Date().toISOString() });
     }
     async get(id) {
         const f = this.path(id);
@@ -403,7 +482,7 @@ export class FilePendingStore {
     }
     async delete(id, attemptId) {
         if (attemptId) {
-            const owner = this.resolve(id).rec?.attemptId;
+            const owner = this.readHead(id).rec?.attemptId;
             if (owner && owner !== attemptId)
                 return;
         }
@@ -417,7 +496,8 @@ export class FilePendingStore {
         if (!existsSync(this.dir))
             return [];
         const out = [];
-        for (const f of readdirSync(this.dir).filter((f) => f.endsWith(".json"))) {
+        const names = readdirSync(this.dir);
+        for (const f of names.filter((f) => f.endsWith(".json"))) {
             let p;
             try {
                 p = JSON.parse(readFileSync(join(this.dir, f), "utf8"));
@@ -426,7 +506,7 @@ export class FilePendingStore {
                 console.error(`[decidio] skipping unreadable parked entry ${f} (${e.message}) — the other parked actions still resume; inspect or delete this file.`);
                 continue;
             }
-            const { rec } = this.resolve(p.decisionId);
+            const { rec } = this.readHead(p.decisionId, names);
             if (!rec || rec.state === "parked")
                 out.push(p);
         }
@@ -435,62 +515,41 @@ export class FilePendingStore {
     async claim(id, attemptId) {
         if (!existsSync(this.path(id)))
             return { ok: false, reason: "no parked entry" };
-        const { rec, corrupt } = this.resolve(id);
-        if (corrupt.length)
-            throw new DecidioStateCorruptError(id, corrupt);
-        const state = rec?.state ?? "parked";
-        if (NON_REPLAYABLE.includes(state))
-            return { ok: false, state, reason: `already ${state}` };
-        if (state === "claimed_preinvoke")
-            return { ok: false, state, reason: "claimed by another attempt" };
-        const target = this.statePath(id, "claimed_preinvoke");
-        const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
-        const payload = JSON.stringify({ ...(rec ?? {}), decisionId: id, state: "claimed_preinvoke", attemptId, action: rec?.action, at: new Date().toISOString() }, null, 2);
-        const fd = openSync(tmp, "w", 0o600);
-        try {
-            writeFileSync(fd, payload);
-            fsyncSync(fd);
-        }
-        finally {
-            closeSync(fd);
-        }
-        try {
-            linkSync(tmp, target);
-        }
-        catch {
-            try {
-                rmSync(tmp);
+        let refusal = null;
+        this.transition(id, "claim", (cur) => {
+            const state = cur?.state ?? "parked";
+            if (NON_REPLAYABLE.includes(state)) {
+                refusal = { ok: false, state, reason: `already ${state}` };
+                return null;
             }
-            catch { }
-            return { ok: false, state: "claimed_preinvoke", reason: "lost the claim race" };
-        }
-        try {
-            rmSync(tmp);
-        }
-        catch { }
-        try {
-            const p = this.statePath(id, "parked");
-            if (existsSync(p))
-                rmSync(p);
-        }
-        catch { }
-        return { ok: true };
+            if (state === "claimed_preinvoke") {
+                refusal = { ok: false, state, reason: "claimed by another attempt" };
+                return null;
+            }
+            return { ...(cur ?? {}), decisionId: id, state: "claimed_preinvoke", attemptId, action: cur?.action, at: new Date().toISOString() };
+        });
+        return refusal ?? { ok: true };
     }
     async markInvoking(id, attemptId) {
-        const { rec, corrupt } = this.resolve(id);
-        if (corrupt.length)
-            throw new DecidioStateCorruptError(id, corrupt);
-        const cur = rec ?? { decisionId: id, state: "parked", attemptId: null, at: new Date().toISOString() };
-        assertNotDenied(id, cur, "invoking");
-        assertClaimedBy(id, cur, attemptId);
-        this.setState(id, attemptId, "invoking");
+        this.setState(id, attemptId, "invoking", {}, (cur) => {
+            assertNotDenied(id, cur, "invoking");
+            assertClaimedBy(id, cur, attemptId);
+        });
     }
     async recordExecuted(id, attemptId, evidence, evidenceSig, evidenceError) { this.setState(id, attemptId, "executed_unreported", { evidence, hasEvidence: true, evidenceSig, evidenceError }); }
     async markIndeterminate(id, attemptId, error) { this.setState(id, attemptId, "indeterminate", { error }); }
     async markReported(id, attemptId, confirmation) { this.setState(id, attemptId, "reported", { confirmation }); }
-    async markDiscarded(id, verdict, reason) { this.setState(id, this.resolve(id).rec?.attemptId ?? "", "discarded", { verdict, ...(reason ? { discardReason: reason } : {}) }); }
+    async markDiscarded(id, verdict, reason) {
+        this.transition(id, "discard", (rec) => {
+            const cur = rec ?? { decisionId: id, state: "parked", attemptId: null, at: new Date().toISOString() };
+            assertNotSettled(id, cur, "discarded");
+            if (rank("discarded") < rank(cur.state))
+                throw new Error(`[decidio] ${id}: refusing to move ${cur.state} → discarded; execution state only ever advances.`);
+            return { ...cur, decisionId: id, attemptId: cur.attemptId ?? "", state: "discarded", verdict, ...(reason ? { discardReason: reason } : {}), at: new Date().toISOString() };
+        });
+    }
     async getExecution(id) {
-        const { rec, corrupt } = this.resolve(id);
+        const { rec, corrupt } = this.readHead(id);
         if (corrupt.length)
             throw new DecidioStateCorruptError(id, corrupt);
         return rec;
@@ -498,21 +557,26 @@ export class FilePendingStore {
     async listExecutions() {
         if (!existsSync(this.dir))
             return [];
-        const ids = new Set();
-        for (const name of readdirSync(this.dir)) {
+        const keys = new Set();
+        const names = readdirSync(this.dir);
+        for (const name of names) {
+            const m = /^(.*)\.rev\.\d+$/.exec(name);
+            if (m) {
+                keys.add(m[1]);
+                continue;
+            }
             const dot = name.lastIndexOf(".");
             if (dot < 0)
                 continue;
             const suffix = name.slice(dot + 1);
-            if (!EXECUTION_STATES.includes(suffix))
-                continue;
-            ids.add(name.slice(0, dot));
+            if (EXECUTION_STATES.includes(suffix))
+                keys.add(name.slice(0, dot));
         }
         const out = [];
-        for (const key of ids) {
-            const { rec, corrupt } = this.resolve(key);
+        for (const key of keys) {
+            const { rec, corrupt } = this.readHead(key, names);
             if (corrupt.length) {
-                out.push({ decisionId: key, state: "indeterminate", attemptId: null, error: `state files unreadable — ${corrupt.join("; ")}`, at: new Date().toISOString() });
+                out.push({ decisionId: rec?.decisionId ?? key, state: "indeterminate", attemptId: null, error: `state files unreadable — ${corrupt.join("; ")}`, at: new Date().toISOString() });
                 continue;
             }
             if (rec)
@@ -521,60 +585,92 @@ export class FilePendingStore {
         return out;
     }
     async settle(id, outcome, opts = {}) {
-        const { rec, corrupt } = this.resolve(id);
-        if (corrupt.length)
-            throw new DecidioStateCorruptError(id, corrupt);
-        const cur = rec ?? { decisionId: id, state: "parked", attemptId: null, at: new Date().toISOString() };
-        assertSettlable(id, cur.state, outcome, { hasObservedEvidence: !cur.evidenceError, workerStopped: opts.workerStopped });
-        const at = new Date().toISOString();
-        const reconciled = { outcome, reason: opts.reason, at, ...(opts.workerStopped ? { workerStopped: true } : {}) };
-        const next = outcome === "committed"
-            ? { ...cur, state: "executed_unreported", evidence: opts.evidence ?? null, hasEvidence: true, evidenceSig: opts.evidenceSig, evidenceError: undefined, reconciled, at }
-            : { ...cur, state: "parked", attemptId: null, error: undefined, reconciled, at };
-        this.writeAtomic(this.statePath(id, next.state), JSON.stringify(next, null, 2));
-        for (const st of EXECUTION_STATES) {
-            if (st === next.state)
-                continue;
-            try {
-                const f = this.statePath(id, st);
-                if (existsSync(f))
-                    rmSync(f);
-            }
-            catch { }
-        }
+        this.transition(id, "settle", (rec) => {
+            const cur = rec ?? { decisionId: id, state: "parked", attemptId: null, at: new Date().toISOString() };
+            assertSettlable(id, cur.state, outcome, { hasObservedEvidence: !cur.evidenceError, workerStopped: opts.workerStopped });
+            const at = new Date().toISOString();
+            const reconciled = { outcome, reason: opts.reason, at, ...(opts.workerStopped ? { workerStopped: true } : {}) };
+            return outcome === "committed"
+                ? { ...cur, state: "executed_unreported", evidence: opts.evidence ?? null, hasEvidence: true, evidenceSig: opts.evidenceSig, evidenceError: undefined, reconciled, at }
+                : { ...cur, state: "parked", attemptId: null, error: undefined, reconciled, at };
+        });
     }
     async releasePreinvoke(id, attemptId) {
-        const { rec } = this.resolve(id);
-        const state = rec?.state ?? "parked";
-        if (NON_REPLAYABLE.includes(state))
-            throw new Error(`[decidio] ${id}: refusing to release this decision — its durable state is ${state}, which is terminal or past the invocation boundary. releasePreinvoke only ever releases a claim nothing has acted on.`);
-        if (rec?.attemptId && rec.attemptId !== attemptId)
-            return;
-        this.writeAtomic(this.statePath(id, "parked"), JSON.stringify({ ...(rec ?? {}), decisionId: id, state: "parked", attemptId: null, action: rec?.action, at: new Date().toISOString() }, null, 2));
-        try {
-            const c = this.statePath(id, "claimed_preinvoke");
-            if (existsSync(c))
-                rmSync(c);
-        }
-        catch { }
+        this.transition(id, "release", (rec) => {
+            const state = rec?.state ?? "parked";
+            if (NON_REPLAYABLE.includes(state))
+                throw new Error(`[decidio] ${id}: refusing to release this decision — its durable state is ${state}, which is terminal or past the invocation boundary. releasePreinvoke only ever releases a claim nothing has acted on.`);
+            if (rec?.attemptId && rec.attemptId !== attemptId)
+                return null;
+            if (state === "parked")
+                return null;
+            return { ...(rec ?? {}), decisionId: id, state: "parked", attemptId: null, action: rec?.action, at: new Date().toISOString() };
+        });
     }
     migrateLegacy() {
         if (!existsSync(this.dir))
-            return { migrated: 0, indeterminate: 0, reports: 0 };
-        let migrated = 0, indeterminate = 0;
+            return { migrated: 0, indeterminate: 0, reports: 0, chained: 0 };
+        let migrated = 0, indeterminate = 0, chained = 0;
+        const markerKeys = new Set();
+        for (const name of readdirSync(this.dir)) {
+            const dot = name.lastIndexOf(".");
+            if (dot < 0)
+                continue;
+            if (EXECUTION_STATES.includes(name.slice(dot + 1)))
+                markerKeys.add(name.slice(0, dot));
+        }
+        for (const key of markerKeys) {
+            if (this.listRevs(key).length)
+                continue;
+            const present = this.legacyMarkers(key);
+            const { rec, corrupt } = this.resolveLegacyMarkers(key);
+            if (corrupt.length || !rec) {
+                console.error(`[decidio] ${key}: the older state marker(s) for this decision could not be read (${corrupt.join("; ") || "no readable marker"}) — left in place; the decision reads as unreadable until a person inspects it.`);
+                continue;
+            }
+            const target = this.revPath(key, 1);
+            const tmp = this.writeTemp(target, JSON.stringify(rec, null, 2));
+            try {
+                linkSync(tmp, target);
+                chained++;
+            }
+            catch (e) {
+                if (e?.code !== "EEXIST") {
+                    try {
+                        rmSync(tmp);
+                    }
+                    catch { }
+                    throw e;
+                }
+            }
+            try {
+                rmSync(tmp);
+            }
+            catch { }
+            for (const s of present) {
+                try {
+                    rmSync(this.markerPath(key, s));
+                }
+                catch { }
+            }
+        }
+        if (chained)
+            console.error(`[decidio] upgraded ${chained} decision${chained === 1 ? "" : "s"} from the one-marker-per-state layout to the revision chain. Do not run an older SDK against this directory again: it would write markers this layout refuses to read.`);
         for (const name of readdirSync(this.dir)) {
             if (name.endsWith(".claimed")) {
                 const key = name.slice(0, -".claimed".length);
                 try {
                     const p = JSON.parse(readFileSync(join(this.dir, name), "utf8"));
-                    const existing = this.resolve(p.decisionId).rec;
-                    if (existing && NON_REPLAYABLE.includes(existing.state)) {
+                    const published = this.transition(p.decisionId, "migrate", (cur) => cur && NON_REPLAYABLE.includes(cur.state) ? null : ({
+                        ...(cur ?? {}), decisionId: p.decisionId, state: "indeterminate", attemptId: null, action: p.action,
+                        error: "upgraded from 0.1.x while claimed — whether it ran is not knowable; reconcile it", at: new Date().toISOString(),
+                    }));
+                    if (published === null) {
                         renameSync(join(this.dir, name), join(this.dir, `${name}.migrated`));
                         continue;
                     }
-                    this.writeAtomic(this.statePath(p.decisionId, "indeterminate"), JSON.stringify({ decisionId: p.decisionId, state: "indeterminate", attemptId: null, action: p.action, error: "upgraded from 0.1.x while claimed — whether it ran is not knowable; reconcile it", at: new Date().toISOString() }, null, 2));
                     this.writeAtomic(this.path(p.decisionId), JSON.stringify(p, null, 2));
-                    rmSync(join(this.dir, name));
+                    renameSync(join(this.dir, name), join(this.dir, `${name}.migrated`));
                     indeterminate++;
                 }
                 catch {
@@ -588,9 +684,10 @@ export class FilePendingStore {
                 const p = JSON.parse(readFileSync(join(this.dir, name), "utf8"));
                 if (!p?.decisionId)
                     continue;
-                if (this.resolve(p.decisionId).rec)
+                if (this.readHead(p.decisionId).rec)
                     continue;
-                this.writeAtomic(this.statePath(p.decisionId, "parked"), JSON.stringify({ decisionId: p.decisionId, state: "parked", attemptId: null, action: p.action, at: new Date().toISOString() }, null, 2));
+                this.transition(p.decisionId, "migrate", (cur) => cur ? null
+                    : { decisionId: p.decisionId, state: "parked", attemptId: null, action: p.action, at: new Date().toISOString() });
                 migrated++;
             }
             catch { }
@@ -598,7 +695,7 @@ export class FilePendingStore {
         if (indeterminate)
             console.error(`[decidio] upgraded ${indeterminate} in-flight 0.1.x entr${indeterminate === 1 ? "y" : "ies"} to INDETERMINATE — they will not auto-run; review them with guard.resume.recover().`);
         const reports = this.migrateLegacyReports();
-        return { migrated, indeterminate, reports };
+        return { migrated, indeterminate, reports, chained };
     }
     migrateLegacyReports() {
         const reportsDir = join(this.dir, "reports");
@@ -613,22 +710,18 @@ export class FilePendingStore {
                 const e = JSON.parse(readFileSync(file, "utf8"));
                 if (!e?.decisionId)
                     continue;
-                const existing = this.resolve(e.decisionId).rec;
-                if (existing && rank(existing.state) >= rank("executed_unreported")) {
-                    renameSync(file, `${file}.migrated`);
-                    continue;
-                }
-                if (existing?.state === "discarded") {
-                    renameSync(file, `${file}.migrated`);
-                    console.error(`[decidio] ${e.decisionId}: a 0.1.x execution report was found for a decision that was DENIED (${existing.verdict ?? "rejected"}). It has NOT been added to the ledger — a denial is terminal and this report will not be sent. The file is kept as ${file}.migrated: if that action really ran, check the downstream system and correct it there.`);
-                    continue;
-                }
-                this.writeAtomic(this.statePath(e.decisionId, "executed_unreported"), JSON.stringify({
-                    decisionId: e.decisionId, state: "executed_unreported", attemptId: null, action: e.action,
+                const published = this.transition(e.decisionId, "migrate", (cur) => cur && (cur.state === "discarded" || rank(cur.state) >= rank("executed_unreported")) ? null : ({
+                    ...(cur ?? {}), decisionId: e.decisionId, state: "executed_unreported", attemptId: null, action: e.action,
                     evidence: e.reported, hasEvidence: true, migratedFrom: "0.1.x report journal",
                     at: e.at ?? new Date().toISOString(),
-                }, null, 2));
+                }));
                 renameSync(file, `${file}.migrated`);
+                if (published === null) {
+                    const head = this.readHead(e.decisionId).rec;
+                    if (head?.state === "discarded")
+                        console.error(`[decidio] ${e.decisionId}: a 0.1.x execution report was found for a decision that was DENIED (${head.verdict ?? "rejected"}). It has NOT been added to the ledger — a denial is terminal and this report will not be sent. The file is kept as ${file}.migrated: if that action really ran, check the downstream system and correct it there.`);
+                    continue;
+                }
                 moved++;
             }
             catch {
@@ -738,6 +831,7 @@ function webhookBody(o) {
         ok: true,
         outcome: {
             status: o.status, decisionId: o.decisionId,
+            ...(o.reason ? { reason: o.reason } : {}),
             ...(o.reportRecorded !== undefined ? { reportRecorded: o.reportRecorded } : {}),
             ...(o.executionConfirmed !== undefined ? { executionConfirmed: o.executionConfirmed } : {}),
             ...(o.evidenceTier ? { evidenceTier: o.evidenceTier } : {}),
@@ -842,7 +936,7 @@ export function createDecidioResume(opts) {
             };
         }
         if (ev.reportRecorded)
-            await ctrl.store.markReported(decisionId, attemptId, ev.evidenceTier ?? "recorded").catch(() => { });
+            await ctrl.store.markReported(decisionId, attemptId, tombstoneTier(ev)).catch(() => { });
         const diagnostic = buildProblem
             ? `${ev.diagnostic ? ev.diagnostic + " " : ""}Also: the action's return value was not reportable (${buildProblem}), so an empty response was reported - map it with the \`evidence\` option to earn a confirming tier.`
             : ev.diagnostic;
@@ -876,6 +970,9 @@ export function createDecidioResume(opts) {
             registry.set(action, { fn, evidence: evidence ?? prev?.evidence, withContext: withContext ?? prev?.withContext });
         },
         async park(p) {
+            const idProblem = decisionIdProblem(p.decisionId);
+            if (idProblem)
+                throw new DecidioUnsafeArgumentsError(`[decidio] refusing to park ${JSON.stringify(p.decisionId ?? null)}: it is not a decision id this SDK will act on (${idProblem}). Nothing was parked and nothing will execute - a decision id comes from the gate's answer, verbatim.`, typeof p.decisionId === "string" ? p.decisionId : "");
             try {
                 toCanonical(p.args, "args");
             }
@@ -890,6 +987,9 @@ export function createDecidioResume(opts) {
         async resolve({ decisionId, verdict, reason }) {
             const finish = (o) => { if (o.status !== "unknown")
                 opts.onResolved?.(o); return o; };
+            const idProblem = decisionIdProblem(decisionId);
+            if (idProblem)
+                return { status: "unknown", decisionId: String(decisionId ?? ""), reason: `not a decision id this SDK will act on (${idProblem})` };
             const pending = await ctrl.store.get(decisionId);
             if (!pending)
                 return { status: "unknown", decisionId };
@@ -986,7 +1086,7 @@ export function createDecidioResume(opts) {
                         }
                         const body = JSON.parse(raw || "{}");
                         const verdict = body.verdict;
-                        const outcome = await ctrl.resolve({ decisionId: String(body.decisionId), verdict, reason: body.reason });
+                        const outcome = await ctrl.resolve({ decisionId: body.decisionId, verdict, reason: body.reason });
                         res.statusCode = 200;
                         res.setHeader("content-type", "application/json");
                         res.end(JSON.stringify(webhookBody(outcome)));
@@ -1012,7 +1112,7 @@ export function createDecidioResume(opts) {
                 }
                 try {
                     const body = JSON.parse(raw || "{}");
-                    const outcome = await ctrl.resolve({ decisionId: String(body.decisionId), verdict: body.verdict, reason: body.reason });
+                    const outcome = await ctrl.resolve({ decisionId: body.decisionId, verdict: body.verdict, reason: body.reason });
                     return new Response(JSON.stringify(webhookBody(outcome)), { status: 200, headers: { "content-type": "application/json" } });
                 }
                 catch (e) {
@@ -1021,6 +1121,9 @@ export function createDecidioResume(opts) {
             };
         },
         async reconcile(decisionId, opts) {
+            const idProblem = decisionIdProblem(decisionId);
+            if (idProblem)
+                return { reportRecorded: false, executionConfirmed: false, diagnostic: `${JSON.stringify(decisionId ?? null)} is not a decision id this SDK will act on (${idProblem}). Nothing was settled.` };
             let entry;
             try {
                 entry = await ctrl.store.getExecution(decisionId);
@@ -1066,13 +1169,16 @@ export function createDecidioResume(opts) {
                 return { reportRecorded: false, executionConfirmed: false, diagnostic: `the reconciled report for ${decisionId} did not reach Decidio (${e?.message ?? e}). The evidence IS recorded locally — call reconfirm("${decisionId}") when the service is healthy. Do NOT re-run the action.` };
             }
             if (ev.reportRecorded)
-                await ctrl.store.markReported(decisionId, entry.attemptId ?? "reconcile", ev.evidenceTier ?? "recorded").catch(() => { });
+                await ctrl.store.markReported(decisionId, entry.attemptId ?? "reconcile", tombstoneTier(ev)).catch(() => { });
             return {
                 ...ev,
                 diagnostic: `${ev.diagnostic ? `${ev.diagnostic} ` : ""}This report was RECONCILED BY AN OPERATOR${opts.reason ? ` (${opts.reason})` : ""}, not observed by the SDK: its tier reflects the evidence you supplied, not a return value this process saw.`,
             };
         },
         async reconfirm(decisionId, opts) {
+            const idProblem = decisionIdProblem(decisionId);
+            if (idProblem)
+                return { reportRecorded: false, executionConfirmed: false, diagnostic: `${JSON.stringify(decisionId ?? null)} is not a decision id this SDK will act on (${idProblem}). Nothing was sent.` };
             let entry;
             try {
                 entry = await ctrl.store.getExecution(decisionId);
@@ -1081,7 +1187,8 @@ export function createDecidioResume(opts) {
                 return { reportRecorded: false, executionConfirmed: false, diagnostic: `the durable state for ${decisionId} could not be read (${e?.message ?? e}). Refusing to guess whether it executed — inspect the store; do NOT re-run the action to find out.` };
             }
             if (entry?.state === "reported") {
-                return { reportRecorded: true, executionConfirmed: false, evidenceTier: entry.confirmation, diagnostic: `${decisionId} was already reported (${entry.confirmation ?? "recorded"}) — nothing to re-send.` };
+                const confirmed = tierConfirms(entry.confirmation);
+                return { reportRecorded: true, executionConfirmed: confirmed, evidenceTier: entry.confirmation, diagnostic: `${decisionId} was already reported (${entry.confirmation ?? "recorded"}${confirmed ? ", a confirming tier" : ", not a confirming tier"}) — nothing to re-send.` };
             }
             if (entry?.state === "indeterminate") {
                 return { reportRecorded: false, executionConfirmed: false, diagnostic: `${decisionId} is INDETERMINATE: it was invoked and its outcome is unknown, so there is no captured result to re-send. Settle it with reconcile("${decisionId}", …) once you have checked the downstream system.` };
@@ -1130,7 +1237,7 @@ export function createDecidioResume(opts) {
                 return { reportRecorded: false, executionConfirmed: false, diagnostic: `the execution report for ${decisionId} still did not reach Decidio (${e?.message ?? e}). The recorded evidence is KEPT — call reconfirm("${decisionId}") again when the service is healthy. Your action already ran; do NOT re-run it.` };
             }
             if (ev.reportRecorded)
-                await ctrl.store.markReported(decisionId, entry.attemptId ?? "reconfirm", ev.evidenceTier ?? "recorded").catch(() => { });
+                await ctrl.store.markReported(decisionId, entry.attemptId ?? "reconfirm", tombstoneTier(ev)).catch(() => { });
             return ev;
         },
         async recover() {

package/dist/signing.js

@@ -124,6 +124,17 @@ export function assertSafeTransport(url, hasCredential) {
     if (u.username || u.password) {
         throw new Error(`[decidio] the gate URL carries credentials in the URL itself (${u.protocol}//user:***@${u.host}). Decidio authenticates with a bearer token; remove the user:password from the URL. Nothing was sent.`);
     }
+    if (u.hostname === "") {
+        throw new Error(`[decidio] the gate URL ${JSON.stringify(url)} has no host — there is nowhere for the request to go. Decidio needs a full https URL (or http://localhost for local dev). Nothing was sent.`);
+    }
+    {
+        const spelled = url.replace(/[\t\r\n]/g, "").replace(/^[\s\u0000-\u001f\u0085\ufeff]+/, "").toLowerCase();
+        const origin = `${u.protocol}//${u.host}`.toLowerCase();
+        const next = spelled.charAt(origin.length);
+        if (!spelled.startsWith(origin) || (next !== "" && next !== "/" && next !== "?" && next !== "#" && next !== ":")) {
+            throw new Error(`[decidio] the gate URL ${JSON.stringify(url)} is not written in canonical form — this parser reads it as ${origin}, but the raw spelling is what a transport receives, and a parser that normalizes differently can read it as another host entirely. Write it as ${origin}. Nothing was sent.`);
+        }
+    }
     if (u.protocol !== "http:")
         return;
     const host = u.hostname.toLowerCase();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "One-line approval gate for AI-agent actions. Wrap a risky tool call with guard.protect(); Decidio's policy engine decides proceed | route | block, a human approves routed actions, and every outcome is sealed as a verifiable Authority Receipt.",
   "license": "Apache-2.0",
   "type": "module",
@@ -79,10 +79,10 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
-    "prepublishOnly": "npm run typecheck && npm run build"
+    "prepublishOnly": "npm run typecheck && npm run build && node ../publish-boundary/check.mjs --only @decidio/sdk"
   },
   "dependencies": {
-    "@decidio/verify": "0.3.0"
+    "@decidio/verify": "0.3.3"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {