@decidio/sdk 0.3.0 → 0.3.5

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 };
@@ -937,7 +1037,7 @@ export function createDecidioResume(opts) {
                     refuseOnce(decisionId, claim.state === "discarded"
                         ? `[decidio] REFUSING to execute ${decisionId}: it was DENIED (${(await ctrl.store.getExecution(decisionId))?.verdict ?? "rejected"}) and that answer is final. Nothing ran. A denial cannot be reconciled or retried — if this action should now proceed, it needs a NEW request and a new approval.`
                         : `[decidio] REFUSING to execute ${decisionId}: its durable state is ${claim.state} — invocation already began, so re-running it could duplicate a committed effect. Inspect it with guard.resume.recover(); settle it with guard.resume.reconcile("${decisionId}", …).`, claim.state === "discarded" ? " (This prints once. The decision is closed — no action is needed.)" : undefined);
-                    return finish({ status: claim.state === "indeterminate" ? "indeterminate" : "unknown", decisionId, action: pending.action, reason: claim.reason });
+                    return finish({ status: claim.state === "indeterminate" ? "indeterminate" : "already_resolved", decisionId, action: pending.action, reason: claim.state === "discarded" ? `this decision was already DENIED (${(await ctrl.store.getExecution(decisionId))?.verdict ?? "rejected"}); that answer is final and this signal lost the race to it` : `this decision already ran (durable state ${claim.state}); this signal lost the race to it` });
                 }
                 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() {
@@ -1162,7 +1269,12 @@ export function createDecidioResume(opts) {
                             guidance: `"${a}" was claimed at ${r.at} by attempt ${r.attemptId ?? "(unknown)"} which never reached the invocation boundary — the handler provably did not run, and nothing will retry it on its own. Release it: guard.resume.reconcile("${r.decisionId}", { outcome: "not_committed", reason: "claimed but never invoked" }).` });
                         break;
                     case "parked":
-                        items.push({ decisionId: r.decisionId, action: r.action, state: "parked", guidance: `"${a}" is parked awaiting a human decision. Nothing has executed.` });
+                        if (!(await ctrl.store.get(r.decisionId))) {
+                            items.push({ decisionId: r.decisionId, action: r.action, state: "orphaned_state", guidance: `"${a}" is recorded as parked but its payload is gone, so nothing can execute it — an orphaned row (usually a legacy denial whose state was never written), not work awaiting a human. Nothing will run. It needs no action; remove its revision files if you want the listing clean.` });
+                        }
+                        else {
+                            items.push({ decisionId: r.decisionId, action: r.action, state: "parked", guidance: `"${a}" is parked awaiting a human decision. Nothing has executed.` });
+                        }
                         break;
                     case "discarded":
                         if (r.executionDespiteDenial) {