@decidio/sdk 0.1.11 → 0.2.0

package/dist/resume.js

@@ -1,9 +1,9 @@
-import { createHmac, timingSafeEqual, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify } from "node:crypto";
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync, renameSync } from "node:fs";
+import { createHmac, timingSafeEqual, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify, randomUUID } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync, renameSync, openSync, closeSync, fsyncSync, linkSync } from "node:fs";
 import { join } from "node:path";
 import { userInfo } from "node:os";
 import { execFileSync } from "node:child_process";
-import { signConfirm, canonicalize as jcs, assertSafeTransport } from "./signing.js";
+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";
@@ -42,34 +42,202 @@ function verifyArgs(p, agentKey, webhookSecret) {
         return "mismatch";
     }
 }
+const evidenceBindingBytes = (decisionId, attemptId, evidence) => Buffer.from(jcs({ decisionId, attemptId: attemptId ?? null, evidence: evidence ?? null }), "utf8");
+export function signEvidence(decisionId, attemptId, evidence, agentKey, webhookSecret) {
+    const bytes = evidenceBindingBytes(decisionId, attemptId, evidence);
+    if (agentKey) {
+        try {
+            const key = createPrivateKey({ key: Buffer.from(agentKey, "base64"), format: "der", type: "pkcs8" });
+            return { kind: "ed25519", sig: Buffer.from(edSign(null, bytes, key)).toString("base64url") };
+        }
+        catch { }
+    }
+    if (webhookSecret)
+        return { kind: "hmac", sig: createHmac("sha256", webhookSecret).update(bytes).digest("hex") };
+    return undefined;
+}
+export function verifyEvidence(rec, agentKey, webhookSecret) {
+    if (!rec.evidenceSig)
+        return "unbound";
+    const bytes = evidenceBindingBytes(rec.decisionId, rec.attemptId, rec.evidence ?? null);
+    try {
+        if (rec.evidenceSig.kind === "ed25519") {
+            if (!agentKey)
+                return "unverifiable";
+            const pub = createPublicKey(createPrivateKey({ key: Buffer.from(agentKey, "base64"), format: "der", type: "pkcs8" }));
+            return edVerify(null, bytes, pub, Buffer.from(rec.evidenceSig.sig, "base64url")) ? "ok" : "mismatch";
+        }
+        if (!webhookSecret)
+            return "unverifiable";
+        const expected = createHmac("sha256", webhookSecret).update(bytes).digest("hex");
+        const x = Buffer.from(expected), y = Buffer.from(rec.evidenceSig.sig);
+        return x.length === y.length && timingSafeEqual(x, y) ? "ok" : "mismatch";
+    }
+    catch {
+        return "mismatch";
+    }
+}
+export const EXECUTION_STATES = [
+    "parked", "claimed_preinvoke", "invoking", "executed_unreported", "indeterminate", "reported",
+];
+export const NON_REPLAYABLE = ["invoking", "executed_unreported", "indeterminate", "reported"];
+export class DecidioStaleAttemptError extends Error {
+    decisionId;
+    owner;
+    state;
+    constructor(decisionId, owner, state) {
+        super(`[decidio] ${decisionId}: this attempt no longer owns the decision — attempt ${owner ?? "(unknown)"} holds it in state ${state}. Refusing a state write from a superseded attempt.`);
+        this.decisionId = decisionId;
+        this.owner = owner;
+        this.state = state;
+        this.name = "DecidioStaleAttemptError";
+    }
+}
+export class DecidioAlreadySettledError extends Error {
+    decisionId;
+    constructor(decisionId) {
+        super(`[decidio] ${decisionId}: an operator already settled this decision as committed and its report is recorded — refusing a second execution report. Nothing was re-run; this write is the duplicate, not the execution.`);
+        this.decisionId = decisionId;
+        this.name = "DecidioAlreadySettledError";
+    }
+}
+function assertNotSettled(id, cur, next) {
+    if (cur.reconciled?.outcome === "committed" && (next === "executed_unreported" || next === "indeterminate")) {
+        throw new DecidioAlreadySettledError(id);
+    }
+}
+export const SETTLE_OUTCOMES = ["committed", "not_committed"];
+export function assertSettlable(id, state, outcome, hasObservedEvidence = true) {
+    if (!SETTLE_OUTCOMES.includes(outcome)) {
+        throw new Error(`[decidio] ${id}: outcome must be "committed" or "not_committed", not ${JSON.stringify(outcome)}.`);
+    }
+    if (outcome === "committed") {
+        if (state === "reported")
+            throw new Error(`[decidio] ${id}: already reported — there is nothing left to reconcile.`);
+        if (state === "executed_unreported" && hasObservedEvidence)
+            throw new Error(`[decidio] ${id}: this decision already holds evidence this SDK OBSERVED — an operator assertion must not replace a captured result. If the report simply has not reached Decidio, re-send the real one: reconfirm("${id}").`);
+        if (rank(state) < rank("invoking"))
+            throw new Error(`[decidio] ${id}: refusing to record a COMMITTED outcome from state ${state} — the handler was never invoked, so no downstream write can have happened. If you mean "run it", let it resume normally.`);
+    }
+    else {
+        if (state === "reported")
+            throw new Error(`[decidio] ${id}: already reported — releasing it would re-run an execution Decidio has already recorded.`);
+        if (state === "executed_unreported")
+            throw new Error(`[decidio] ${id}: this decision holds CAPTURED EVIDENCE of an execution — releasing it would re-run a proven write. Re-send the evidence with reconfirm("${id}") instead.`);
+        if (state === "parked")
+            throw new Error(`[decidio] ${id}: already parked — nothing to release.`);
+    }
+}
+const rank = (s) => EXECUTION_STATES.indexOf(s);
 export class MemoryPendingStore {
     m = new Map();
-    claimed = new Set();
-    async put(p) { this.m.set(p.decisionId, p); }
+    x = new Map();
+    rec(id) {
+        return this.x.get(id) ?? { decisionId: id, state: "parked", attemptId: null, at: new Date().toISOString() };
+    }
+    advance(id, attemptId, state, patch = {}) {
+        const cur = this.rec(id);
+        if (cur.attemptId && cur.attemptId !== attemptId && rank(cur.state) >= rank("invoking")) {
+            throw new DecidioStaleAttemptError(id, cur.attemptId, 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.`);
+        }
+        this.x.set(id, { ...cur, ...patch, decisionId: id, attemptId, state, at: new Date().toISOString() });
+    }
+    async put(p) {
+        this.m.set(p.decisionId, p);
+        if (!this.x.has(p.decisionId))
+            this.x.set(p.decisionId, { decisionId: p.decisionId, state: "parked", attemptId: null, action: p.action, at: new Date().toISOString() });
+    }
     async get(id) { return this.m.get(id) ?? null; }
-    async delete(id) { this.m.delete(id); this.claimed.delete(id); }
-    async list() { return [...this.m.values()].filter((p) => !this.claimed.has(p.decisionId)); }
-    async claim(id) { if (this.claimed.has(id) || !this.m.has(id))
-        return false; this.claimed.add(id); return true; }
-    async release(id) { this.claimed.delete(id); }
-    async listClaimed() { return [...this.claimed].map((id) => this.m.get(id)).filter(Boolean); }
+    async delete(id) { this.m.delete(id); }
+    async list() { return [...this.m.values()].filter((p) => this.rec(p.decisionId).state === "parked"); }
+    async claim(id, attemptId) {
+        if (!this.m.has(id))
+            return { ok: false, reason: "no parked entry" };
+        const cur = this.rec(id);
+        if (NON_REPLAYABLE.includes(cur.state))
+            return { ok: false, state: cur.state, reason: `already ${cur.state}` };
+        if (cur.state === "claimed_preinvoke")
+            return { ok: false, state: cur.state, reason: "claimed by another attempt" };
+        this.advance(id, attemptId, "claimed_preinvoke", { action: this.m.get(id)?.action });
+        return { ok: true };
+    }
+    async markInvoking(id, attemptId) { this.advance(id, attemptId, "invoking"); }
+    async recordExecuted(id, attemptId, evidence, evidenceSig, evidenceError) { this.advance(id, attemptId, "executed_unreported", { evidence, hasEvidence: true, evidenceSig, evidenceError }); }
+    async markIndeterminate(id, attemptId, error) { this.advance(id, attemptId, "indeterminate", { error }); }
+    async markReported(id, attemptId, confirmation) { this.advance(id, attemptId, "reported", { confirmation }); }
+    async getExecution(id) { return this.x.get(id) ?? null; }
+    async listExecutions() { return [...this.x.values()]; }
+    async settle(id, outcome, opts = {}) {
+        const cur = this.rec(id);
+        assertSettlable(id, cur.state, outcome, !cur.evidenceError);
+        const at = new Date().toISOString();
+        const reconciled = { outcome, reason: opts.reason, at };
+        this.x.set(id, 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 cur = this.rec(id);
+        if (rank(cur.state) >= rank("invoking"))
+            throw new Error(`[decidio] ${id}: refusing to release a claim after invocation began (state ${cur.state}).`);
+        if (cur.attemptId && cur.attemptId !== attemptId)
+            return;
+        this.x.set(id, { ...cur, state: "parked", attemptId: null, at: new Date().toISOString() });
+    }
 }
 export function hardenDir(dir) {
     if (process.platform !== "win32")
         return;
+    const warn = (why) => console.warn(`[decidio] WARNING: could not restrict ${dir} to owner-only (${why}). It keeps the directory's inherited permissions, so other accounts on this machine may be able to read parked action arguments. Move the pending store to a protected location, or set DECIDIO_PENDING_DIR to one.`);
     try {
-        const user = (() => { try {
-            return userInfo().username;
-        }
-        catch {
-            return process.env.USERNAME ?? process.env.USER ?? "";
-        } })();
-        if (!user)
+        const sid = (() => {
+            const sysRoot = process.env.SystemRoot ?? process.env.windir ?? "C:\\Windows";
+            for (const exe of [join(sysRoot, "System32", "whoami.exe"), "whoami"]) {
+                try {
+                    const out = execFileSync(exe, ["/user", "/fo", "csv", "/nh"], { encoding: "utf8" });
+                    const m = out.match(/S-1-[0-9-]+/);
+                    if (m)
+                        return m[0];
+                }
+                catch { }
+            }
+            return null;
+        })();
+        const principal = sid ? `*${sid}` : (() => {
+            try {
+                return userInfo().username;
+            }
+            catch {
+                return process.env.USERNAME ?? process.env.USER ?? "";
+            }
+        })();
+        if (!principal)
             throw new Error("could not determine the current user");
-        execFileSync("icacls", [dir, "/inheritance:r", "/grant:r", `${user}:(OI)(CI)F`], { stdio: "ignore" });
+        execFileSync("icacls", [dir, "/inheritance:r", "/grant:r", `${principal}:(OI)(CI)F`, "/grant:r", "*S-1-5-18:(OI)(CI)F"], { stdio: "ignore" });
+        const probe = join(dir, `.decidio-acl-probe-${process.pid}`);
+        try {
+            writeFileSync(probe, "probe", { mode: 0o600 });
+            readFileSync(probe, "utf8");
+            rmSync(probe, { force: true });
+        }
+        catch (verifyError) {
+            try {
+                execFileSync("icacls", [dir, "/inheritance:e"], { stdio: "ignore" });
+            }
+            catch { }
+            try {
+                rmSync(probe, { force: true });
+            }
+            catch { }
+            warn(`the restriction applied but this process could no longer write there (${verifyError?.message ?? verifyError}), so it was rolled back`);
+        }
     }
     catch (e) {
-        console.warn(`[decidio] WARNING: could not restrict ${dir} to owner-only (${e?.message ?? e}). It keeps the directory's inherited permissions, so other accounts on this machine may be able to read parked action arguments. Move the pending store to a protected location, or set DECIDIO_PENDING_DIR to one.`);
+        warn(String(e?.message ?? e));
     }
 }
 export class FilePendingStore {
@@ -78,62 +246,303 @@ export class FilePendingStore {
         this.dir = dir;
         mkdirSync(dir, { recursive: true });
         hardenDir(dir);
+        try {
+            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.`);
+        }
     }
     key(id) { return id.replace(/[^\w.-]/g, "_"); }
     path(id) { return join(this.dir, `${this.key(id)}.json`); }
-    claimedPath(id) { return join(this.dir, `${this.key(id)}.claimed`); }
-    async put(p) { writeFileSync(this.path(p.decisionId), JSON.stringify(p, null, 2), { mode: 0o600 }); }
+    statePath(id, s) { return join(this.dir, `${this.key(id)}.${s}`); }
+    writeAtomic(file, text) {
+        const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+        const fd = openSync(tmp, "w", 0o600);
+        try {
+            writeFileSync(fd, text);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmp, file);
+    }
+    resolve(id) {
+        const corrupt = [];
+        let best = null;
+        for (const s of EXECUTION_STATES) {
+            const f = this.statePath(id, s);
+            if (!existsSync(f))
+                continue;
+            try {
+                const r = JSON.parse(readFileSync(f, "utf8"));
+                if (!best || rank(s) >= rank(best.state))
+                    best = { ...r, state: s };
+            }
+            catch (e) {
+                corrupt.push(`${f}: ${e.message}`);
+            }
+        }
+        return { rec: best, 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 && rank(cur.state) >= rank("invoking")) {
+            throw new DecidioStaleAttemptError(id, cur.attemptId, 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 { }
+        }
+    }
+    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));
+        }
+    }
     async get(id) {
-        for (const f of [this.path(id), this.claimedPath(id)])
-            if (existsSync(f))
-                return JSON.parse(readFileSync(f, "utf8"));
-        return null;
-    }
-    async delete(id) { for (const f of [this.path(id), this.claimedPath(id)])
-        if (existsSync(f))
-            rmSync(f); }
+        const f = this.path(id);
+        return existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : null;
+    }
+    async delete(id) { try {
+        if (existsSync(this.path(id)))
+            rmSync(this.path(id));
+    }
+    catch { } }
     async list() {
         if (!existsSync(this.dir))
             return [];
         const out = [];
         for (const f of readdirSync(this.dir).filter((f) => f.endsWith(".json"))) {
+            let p;
             try {
-                out.push(JSON.parse(readFileSync(join(this.dir, f), "utf8")));
+                p = JSON.parse(readFileSync(join(this.dir, f), "utf8"));
             }
             catch (e) {
                 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);
+            if (!rec || rec.state === "parked")
+                out.push(p);
         }
         return out;
     }
-    async claim(id) {
+    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({ 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 {
-            renameSync(this.path(id), this.claimedPath(id));
-            return true;
+            linkSync(tmp, target);
         }
         catch {
-            return false;
+            try {
+                rmSync(tmp);
+            }
+            catch { }
+            return { ok: false, state: "claimed_preinvoke", reason: "lost the claim race" };
         }
-    }
-    async release(id) {
         try {
-            renameSync(this.claimedPath(id), this.path(id));
+            rmSync(tmp);
+        }
+        catch { }
+        try {
+            const p = this.statePath(id, "parked");
+            if (existsSync(p))
+                rmSync(p);
         }
         catch { }
+        return { ok: true };
     }
-    async listClaimed() {
+    async markInvoking(id, attemptId) { this.setState(id, attemptId, "invoking"); }
+    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 getExecution(id) {
+        const { rec, corrupt } = this.resolve(id);
+        if (corrupt.length)
+            throw new DecidioStateCorruptError(id, corrupt);
+        return rec;
+    }
+    async listExecutions() {
         if (!existsSync(this.dir))
             return [];
+        const ids = new Set();
+        for (const name of readdirSync(this.dir)) {
+            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));
+        }
         const out = [];
+        for (const key of ids) {
+            const { rec, corrupt } = this.resolve(key);
+            if (corrupt.length) {
+                out.push({ decisionId: key, state: "indeterminate", attemptId: null, error: `state files unreadable — ${corrupt.join("; ")}`, at: new Date().toISOString() });
+                continue;
+            }
+            if (rec)
+                out.push(rec);
+        }
+        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, !cur.evidenceError);
+        const at = new Date().toISOString();
+        const next = outcome === "committed"
+            ? { ...cur, state: "executed_unreported", evidence: opts.evidence ?? null, hasEvidence: true, evidenceSig: opts.evidenceSig, evidenceError: undefined, reconciled: { outcome, reason: opts.reason, at }, at }
+            : { ...cur, state: "parked", attemptId: null, error: undefined, reconciled: { outcome, reason: opts.reason, at }, 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 { }
+        }
+    }
+    async releasePreinvoke(id, attemptId) {
+        const { rec } = this.resolve(id);
+        const state = rec?.state ?? "parked";
+        if (rank(state) >= rank("invoking"))
+            throw new Error(`[decidio] ${id}: refusing to release a claim after invocation began (state ${state}).`);
+        if (rec?.attemptId && rec.attemptId !== attemptId)
+            return;
+        this.writeAtomic(this.statePath(id, "parked"), JSON.stringify({ 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 { }
+    }
+    migrateLegacy() {
+        if (!existsSync(this.dir))
+            return { migrated: 0, indeterminate: 0, reports: 0 };
+        let migrated = 0, indeterminate = 0;
         for (const name of readdirSync(this.dir)) {
-            if (!name.endsWith(".claimed"))
+            if (name.endsWith(".claimed")) {
+                const key = name.slice(0, -".claimed".length);
+                try {
+                    const p = JSON.parse(readFileSync(join(this.dir, name), "utf8"));
+                    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));
+                    indeterminate++;
+                }
+                catch {
+                    console.error(`[decidio] could not migrate legacy claimed entry ${key} — inspect it by hand.`);
+                }
+                continue;
+            }
+            if (!name.endsWith(".json"))
                 continue;
             try {
-                out.push(JSON.parse(readFileSync(join(this.dir, name), "utf8")));
+                const p = JSON.parse(readFileSync(join(this.dir, name), "utf8"));
+                if (!p?.decisionId)
+                    continue;
+                if (this.resolve(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));
+                migrated++;
             }
             catch { }
         }
-        return out;
+        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 };
+    }
+    migrateLegacyReports() {
+        const reportsDir = join(this.dir, "reports");
+        if (!existsSync(reportsDir))
+            return 0;
+        let moved = 0;
+        for (const name of readdirSync(reportsDir)) {
+            if (!name.endsWith(".json"))
+                continue;
+            const file = join(reportsDir, name);
+            try {
+                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;
+                }
+                this.writeAtomic(this.statePath(e.decisionId, "executed_unreported"), JSON.stringify({
+                    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`);
+                moved++;
+            }
+            catch {
+                console.error(`[decidio] could not migrate the 0.1.x execution report ${file} — it records an action that RAN. Inspect it by hand before deleting it.`);
+            }
+        }
+        if (moved)
+            console.error(`[decidio] recovered ${moved} execution report${moved === 1 ? "" : "s"} written by 0.1.x into the execution ledger — re-send them with guard.resume.recover() / reconfirm(). The original files are kept alongside as .migrated.`);
+        return moved;
+    }
+}
+export class DecidioStateCorruptError extends Error {
+    decisionId;
+    details;
+    constructor(decisionId, details) {
+        super(`[decidio] ${decisionId}: durable execution state is unreadable (${details.join("; ")}). Refusing to guess whether this action ran — inspect these files; reconcile() once you know.`);
+        this.decisionId = decisionId;
+        this.details = details;
+        this.name = "DecidioStateCorruptError";
     }
 }
 export class DecidioSuspendedError extends Error {
@@ -158,13 +567,14 @@ export function verifyResumeSignature(secret, body, header) {
     return a.length === b.length && timingSafeEqual(a, b);
 }
 export function assertConfirmRecorded(body, decisionId, signed) {
-    if (!body || body.ok !== true || typeof body.confirmation !== "string") {
-        throw new Error(`confirm answered 2xx but reported no evidence tier — treating the confirmation as NOT recorded`);
+    const ev = readConfirmResponse(body, { signed, journalled: false });
+    if (!ev.reportRecorded || !ev.evidenceTier) {
+        throw new Error(`[decidio] ${decisionId}: ${ev.diagnostic ?? "confirm answered 2xx but reported no recorded evidence tier — treating the confirmation as NOT recorded"}`);
     }
-    if (signed && body.confirmation !== "application_confirmed") {
-        console.warn(`[decidio] execution evidence for ${decisionId} was recorded as "${body.confirmation}", not application_confirmed, despite a signed report — the server did not accept the identity proof (key/DID/registration mismatch?). Run \`npx @decidio/sdk doctor\` and re-init if this persists.`);
+    if (signed && ev.evidenceTier !== "application_confirmed") {
+        console.warn(`[decidio] execution evidence for ${decisionId} was recorded as "${ev.evidenceTier}", not application_confirmed, despite a signed report — the server did not accept the identity proof (key/DID/registration mismatch?). Run \`npx @decidio/sdk doctor\` and re-init if this persists.`);
     }
-    return body.confirmation;
+    return ev.evidenceTier;
 }
 function buildResumeConfirmRequest(cfg, decisionId, canonicalResult) {
     const requesterIdentity = signConfirm(decisionId, cfg);
@@ -172,9 +582,9 @@ function buildResumeConfirmRequest(cfg, decisionId, canonicalResult) {
         console.warn(`[decidio] execution evidence for ${decisionId} will be recorded as an unproven agent assertion — no signing key configured. Set DECIDIO_AGENT_KEY/DID to earn a confirming tier.`);
     return buildConfirmBody({ agentId: cfg.agentId ?? "agent", agentKey: cfg.agentKey, agentDid: cfg.agentDid, workspaceId: cfg.workspaceId }, decisionId, canonicalResult, requesterIdentity);
 }
-async function postConfirm(cfg, decisionId, body) {
+async function postConfirm(cfg, decisionId, body, journalled = true) {
     const f = cfg.fetchImpl ?? fetch;
-    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
+    assertSafeTransport(cfg.apiUrl, carriesCredential(cfg));
     const r = await f(cfg.apiUrl.replace(/\/$/, "") + "/agent/confirm", {
         method: "POST",
         headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
@@ -190,11 +600,11 @@ async function postConfirm(cfg, decisionId, body) {
         throw new DecidioHttpError(r.status, "/agent/confirm", parsed);
     }
     const parsed = await r.json().catch(() => null);
-    return readConfirmResponse(parsed, { signed: !!body.requesterIdentity, capturedResponse: body.capturedResponse, journalled: true });
+    return readConfirmResponse(parsed, { signed: !!body.requesterIdentity, capturedResponse: body.capturedResponse, journalled });
 }
 async function statusOf(cfg, decisionId) {
     const f = cfg.fetchImpl ?? fetch;
-    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
+    assertSafeTransport(cfg.apiUrl, carriesCredential(cfg));
     const r = await f(cfg.apiUrl.replace(/\/$/, "") + "/agent/status/" + encodeURIComponent(decisionId), {
         headers: { ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
     });
@@ -202,62 +612,56 @@ async function statusOf(cfg, decisionId) {
         throw new DecidioHttpError(r.status, `/agent/status/${decisionId}`);
     return r.json();
 }
-class ReportJournal {
-    dir;
-    constructor(dir) {
-        this.dir = dir;
-        try {
-            mkdirSync(dir, { recursive: true });
-            hardenDir(dir);
-        }
-        catch { }
-    }
-    p(id) { return join(this.dir, `${id.replace(/[^\w.-]/g, "_")}.json`); }
-    write(e) { try {
-        writeFileSync(this.p(e.decisionId), JSON.stringify(e, null, 2), { mode: 0o600 });
-    }
-    catch { } }
-    read(id) { try {
-        return existsSync(this.p(id)) ? JSON.parse(readFileSync(this.p(id), "utf8")) : null;
-    }
-    catch {
-        return null;
-    } }
-    clear(id) { try {
-        if (existsSync(this.p(id)))
-            rmSync(this.p(id));
-    }
-    catch { } }
-    list() {
-        try {
-            if (!existsSync(this.dir))
-                return [];
-            return readdirSync(this.dir).filter((f) => f.endsWith(".json")).map((f) => { try {
-                return JSON.parse(readFileSync(join(this.dir, f), "utf8"));
-            }
-            catch {
-                return null;
-            } }).filter(Boolean);
-        }
-        catch {
-            return [];
-        }
-    }
+const V2_STORE_METHODS = [
+    "put", "get", "delete", "list",
+    "claim", "markInvoking", "recordExecuted", "markIndeterminate", "markReported",
+    "getExecution", "listExecutions", "releasePreinvoke", "settle",
+];
+function assertStoreV2(store) {
+    const missing = V2_STORE_METHODS.filter((m) => typeof store[m] !== "function");
+    if (!missing.length)
+        return;
+    throw new Error(`[decidio] this PendingStore is missing ${missing.length} required method${missing.length === 1 ? "" : "s"}: ${missing.join(", ")}.\n` +
+        `  0.2.0 makes the durable execution state machine MANDATORY (parked → claimed_preinvoke → invoking → executed_unreported | indeterminate → reported).\n` +
+        `  The 0.1.x contract left claim() optional and fell back to a process-local guard, which cannot survive a restart — so it never carried the single-execution guarantee it appeared to. A store that cannot record that invocation BEGAN cannot prevent a committed action from running twice.\n` +
+        `  Fix: implement the missing methods (see the PendingStore docs), or use the shipped FilePendingStore / MemoryPendingStore. Nothing was started.`);
+}
+let reportDirWarned = false;
+function webhookBody(o) {
+    return {
+        ok: true,
+        outcome: {
+            status: o.status, decisionId: o.decisionId,
+            ...(o.reportRecorded !== undefined ? { reportRecorded: o.reportRecorded } : {}),
+            ...(o.executionConfirmed !== undefined ? { executionConfirmed: o.executionConfirmed } : {}),
+            ...(o.evidenceTier ? { evidenceTier: o.evidenceTier } : {}),
+            ...(o.executionReportVerified !== undefined ? { executionReportVerified: o.executionReportVerified } : {}),
+            ...(o.executionReportReason ? { executionReportReason: o.executionReportReason } : {}),
+            ...(o.confirmationRetryable !== undefined ? { confirmationRetryable: o.confirmationRetryable } : {}),
+            ...(o.reportJournalled !== undefined ? { reportJournalled: o.reportJournalled } : {}),
+            ...(o.evidenceError ? { evidenceError: o.evidenceError } : {}),
+            ...(o.diagnostic ? { diagnostic: o.diagnostic } : {}),
+        },
+    };
 }
 export function createDecidioResume(opts) {
+    assertStoreV2(opts.store);
     const registry = new Map();
-    const inFlight = new Set();
     const secret = opts.webhookSecret ?? opts.apiToken ?? "";
+    if (opts.reportDir && !reportDirWarned) {
+        reportDirWarned = true;
+        console.warn(`[decidio] reportDir is ignored since 0.2.0 — execution evidence now lives in the PendingStore's own execution ledger, beside the state that makes a decision non-replayable. Reports written by 0.1.x under <pendingDir>/reports are migrated into that ledger on first use of a FilePendingStore, so nothing is lost; remove the option when convenient.`);
+    }
     if (opts.allowUnsigned)
         console.warn("[decidio] WARNING: allowUnsigned is ON — this controller will accept UNSIGNED resume webhooks. Anyone who can reach the endpoint can signal work (parked-payload integrity still gates execution). Use this only behind a trusted network boundary, never on an internet-reachable endpoint.");
-    const journal = new ReportJournal(opts.reportDir ?? join(process.env.DECIDIO_PENDING_DIR ?? ".decidio-pending", "reports"));
-    async function reportAfterExecution(pending, decisionId, result) {
+    async function reportAfterExecution(pending, decisionId, result, attemptId) {
         const base = { status: "executed", decisionId, action: pending.action, result };
         let reported;
         let haveReported = false;
         let buildProblem;
+        const evidenceMapper = registry.get(pending.action)?.evidence ?? ctrl.evidence;
         try {
-            reported = toCanonical((ctrl.evidence ? ctrl.evidence(result) : result) ?? null, "evidence(result)");
+            reported = toCanonical((evidenceMapper ? evidenceMapper(result) : result) ?? null, "evidence(result)");
             haveReported = true;
         }
         catch (e) {
@@ -265,8 +669,32 @@ export function createDecidioResume(opts) {
             reported = null;
             haveReported = true;
         }
-        if (haveReported)
-            journal.write({ decisionId, action: pending.action, reported, at: new Date().toISOString() });
+        let journalled = false;
+        if (haveReported) {
+            try {
+                await ctrl.store.recordExecuted(decisionId, attemptId, reported, signEvidence(decisionId, attemptId, reported, ctrl.agentKey, ctrl.webhookSecret), buildProblem);
+                journalled = true;
+            }
+            catch (e) {
+                if (e instanceof DecidioStaleAttemptError) {
+                    console.warn(`[decidio] ${decisionId}: this action finished, but the decision is now owned by a newer attempt — it was released for retry while this one was still running. This attempt's report is NOT being sent; the owning attempt reports. Your action DID run: if that means it ran twice, the release was premature.`);
+                    try {
+                        await ctrl.store.delete(decisionId);
+                    }
+                    catch { }
+                    return { ...base, reportRecorded: false, executionConfirmed: false, confirmationRetryable: false, reportJournalled: false, diagnostic: `${decisionId} was released to a newer attempt while this one was running; this attempt's report was not sent. If your action is not idempotent, note that it has now run more than once.` };
+                }
+                if (e instanceof DecidioAlreadySettledError) {
+                    console.warn(`[decidio] ${decisionId}: this action finished, but an operator had already reconciled the decision as committed and Decidio has that report. This attempt's own report is NOT being sent — one decision, one report. If your result differs from what was reconciled, correct it in Decidio; do NOT re-run the action.`);
+                    try {
+                        await ctrl.store.delete(decisionId);
+                    }
+                    catch { }
+                    return { ...base, reportRecorded: true, executionConfirmed: false, reportJournalled: true, diagnostic: `an operator settled ${decisionId} as committed while this attempt was running; their report stands and this one was not sent.` };
+                }
+                console.error(`[decidio] ${decisionId}: the action RAN but its execution report could NOT be recorded (${e?.message ?? e}). If the report also fails to send, this execution is NOT locally recoverable — record the outcome from your own system.`);
+            }
+        }
         let confirmRequest;
         try {
             confirmRequest = buildResumeConfirmRequest(ctrl, decisionId, reported);
@@ -274,30 +702,45 @@ export function createDecidioResume(opts) {
         catch {
             confirmRequest = undefined;
         }
+        const deletePending = async () => {
+            try {
+                await ctrl.store.delete(decisionId);
+            }
+            catch (e) {
+                console.warn(`[decidio] ${decisionId}: the parked payload could not be removed (${e?.message ?? e}). This is cleanup only — the execution ledger already records this decision as executed, so no process can run it again; remove the row at your convenience.`);
+            }
+        };
         if (!confirmRequest) {
-            await ctrl.store.delete(decisionId).catch(() => { });
-            const diagnostic = `"${pending.action}" EXECUTED, but no execution report could be built (${buildProblem ?? "unknown"}). Nothing will re-run it; record the outcome from your own system.`;
+            await deletePending();
+            const diagnostic = `"${pending.action}" EXECUTED, but no execution report could be built (${buildProblem ?? "unknown"}). Nothing will re-run it. ` + (journalled
+                ? `The reported value IS recorded, so fix the agent's signing config (DECIDIO_AGENT_KEY/DID) and re-send it with reconfirm("${decisionId}").`
+                : `The reported value could not be recorded either, so nothing here can re-send it — record the outcome from your own system.`);
             console.warn(`[decidio] ${decisionId}: ${diagnostic}`);
-            return { ...base, reportRecorded: false, executionConfirmed: false, diagnostic };
+            return { ...base, reportRecorded: false, executionConfirmed: false, confirmationRetryable: false, reportJournalled: journalled, ...(buildProblem ? { evidenceError: buildProblem } : {}), diagnostic };
         }
-        await ctrl.store.delete(decisionId).catch(() => { });
+        await deletePending();
         let ev;
         try {
-            ev = await postConfirm(ctrl, decisionId, confirmRequest);
+            ev = await postConfirm(ctrl, decisionId, confirmRequest, journalled);
         }
         catch (e) {
-            ev = { reportRecorded: false, executionConfirmed: false, diagnostic: `the execution report did not reach Decidio (${e?.message ?? e}). Your action DID run and the report is journalled - re-send it with reconfirm("${decisionId}").` };
+            ev = {
+                reportRecorded: false, executionConfirmed: false,
+                diagnostic: journalled
+                    ? `the execution report did not reach Decidio (${e?.message ?? e}). Your action DID run and the report is journalled - re-send it with reconfirm("${decisionId}").`
+                    : `the execution report did not reach Decidio (${e?.message ?? e}) AND could not be journalled locally, so nothing here can re-send it. Your action DID run - record the outcome from your own system.`,
+            };
         }
         if (ev.reportRecorded)
-            journal.clear(decisionId);
+            await ctrl.store.markReported(decisionId, attemptId, ev.evidenceTier ?? "recorded").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;
         if (!ev.reportRecorded)
             console.warn(`[decidio] ${decisionId}: ${diagnostic}`);
-        else if (!ev.executionConfirmed)
+        else if (!ev.executionConfirmed || ev.executionReportVerified === false)
             console.warn(`[decidio] execution evidence for ${decisionId} recorded as ${ev.evidenceTier} - ${diagnostic}`);
-        return { ...base, reportRecorded: ev.reportRecorded, executionConfirmed: ev.executionConfirmed, ...(ev.evidenceTier ? { evidenceTier: ev.evidenceTier } : {}), ...(diagnostic ? { diagnostic } : {}) };
+        return { ...base, reportRecorded: ev.reportRecorded, executionConfirmed: ev.executionConfirmed, ...(ev.evidenceTier ? { evidenceTier: ev.evidenceTier } : {}), ...(ev.executionReportVerified !== undefined ? { executionReportVerified: ev.executionReportVerified } : {}), ...(ev.executionReportReason ? { executionReportReason: ev.executionReportReason } : {}), ...(ev.confirmationRetryable !== undefined ? { confirmationRetryable: ev.confirmationRetryable } : {}), reportJournalled: journalled, ...(buildProblem ? { evidenceError: buildProblem } : {}), ...(diagnostic ? { diagnostic } : {}) };
     }
     const refusalWarned = new Set();
     const refuseOnce = (decisionId, msg) => {
@@ -314,11 +757,13 @@ export function createDecidioResume(opts) {
         workspaceId: opts.workspaceId ?? process.env.DECIDIO_WORKSPACE_ID,
         webhookSecret: secret,
         store: opts.store,
-        register(action, fn) {
+        register(action, fn, evidence, withContext) {
             const prev = registry.get(action);
-            if (prev && prev !== fn)
+            if (prev && prev.fn !== fn)
                 console.warn(`[decidio] action "${action}" is being registered again with a DIFFERENT function — the latest one wins, and a resumed decision would run IT. Give each protected function its own action name.`);
-            registry.set(action, fn);
+            if (prev && prev.evidence && evidence && prev.evidence !== evidence)
+                console.warn(`[decidio] action "${action}" is being registered again with a DIFFERENT evidence mapper — the latest one wins, and a resumed decision's record would carry ITS output. Give each protected function its own action name.`);
+            registry.set(action, { fn, evidence: evidence ?? prev?.evidence, withContext: withContext ?? prev?.withContext });
         },
         async park(p) {
             try {
@@ -368,7 +813,7 @@ export function createDecidioResume(opts) {
             }
             if (integrity === "unbound")
                 console.warn(`[decidio] executing ${decisionId} from an UNBOUND parked entry (this agent has no key material to bind or verify payloads) — its arguments cannot be integrity-checked. Run \`npx @decidio/sdk init\` to enable binding.`);
-            const fn = registry.get(pending.action);
+            const fn = registry.get(pending.action)?.fn;
             if (!fn) {
                 console.error(`[decidio] cannot resume ${decisionId}: no function is registered for action "${pending.action}" in THIS process.`);
                 console.error(`  A worker only re-executes actions registered where it runs. At startup, either declare the action on the wrapper:`);
@@ -378,21 +823,37 @@ export function createDecidioResume(opts) {
                 console.error(`  then start the worker. The approved action stays parked until then — nothing is lost.`);
                 return finish({ status: "no_handler", decisionId, action: pending.action, reason: `no fn registered for action "${pending.action}" in this process — declare { action } on protect(), or call guard.register("${pending.action}", fn) at startup` });
             }
-            const claimed = ctrl.store.claim ? await ctrl.store.claim(decisionId) : (!inFlight.has(decisionId) && (inFlight.add(decisionId), true));
-            if (!claimed)
+            const attemptId = randomUUID();
+            const claim = await ctrl.store.claim(decisionId, attemptId);
+            if (!claim.ok) {
+                if (claim.state && NON_REPLAYABLE.includes(claim.state)) {
+                    refuseOnce(decisionId, `[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}", …).`);
+                    return finish({ status: claim.state === "indeterminate" ? "indeterminate" : "unknown", decisionId, action: pending.action, reason: claim.reason });
+                }
                 return { status: "unknown", decisionId };
+            }
             try {
-                const result = await fn(...pending.args);
-                return finish(await reportAfterExecution(pending, decisionId, result));
+                await ctrl.store.markInvoking(decisionId, attemptId);
             }
             catch (e) {
-                if (ctrl.store.release)
-                    await ctrl.store.release(decisionId).catch(() => { });
-                throw e;
+                await ctrl.store.releasePreinvoke(decisionId, attemptId).catch(() => { });
+                console.error(`[decidio] ${decisionId}: could not record the invocation boundary (${e?.message ?? e}) — refusing to run the action rather than run it unrecorded.`);
+                return finish({ status: "no_handler", decisionId, action: pending.action, reason: "could not durably record the invocation boundary" });
             }
-            finally {
-                inFlight.delete(decisionId);
+            let result;
+            try {
+                const entry = registry.get(pending.action);
+                result = entry?.withContext
+                    ? await fn({ decisionId, attemptId, idempotencyKey: decisionId }, ...pending.args)
+                    : await fn(...pending.args);
+            }
+            catch (e) {
+                const why = String(e?.message ?? e);
+                await ctrl.store.markIndeterminate(decisionId, attemptId, why).catch((se) => console.error(`[decidio] ${decisionId}: could not record INDETERMINATE (${se?.message ?? se}) — treat this decision as possibly executed.`));
+                console.error(`[decidio] ${decisionId}: "${pending.action}" was INVOKED and then threw (${why}). Whether the downstream effect committed is not knowable from here, so it will NOT be retried automatically. Check the downstream system, then: guard.resume.reconcile("${decisionId}", { outcome: "committed", evidence: … }) or { outcome: "not_committed", reason: … }.`);
+                return finish({ status: "indeterminate", decisionId, action: pending.action, reason: why });
             }
+            return finish(await reportAfterExecution(pending, decisionId, result, attemptId));
         },
         webhookHandler() {
             return (req, res) => {
@@ -419,7 +880,7 @@ export function createDecidioResume(opts) {
                         const outcome = await ctrl.resolve({ decisionId: String(body.decisionId), verdict, reason: body.reason });
                         res.statusCode = 200;
                         res.setHeader("content-type", "application/json");
-                        res.end(JSON.stringify({ ok: true, outcome: { status: outcome.status, decisionId: outcome.decisionId } }));
+                        res.end(JSON.stringify(webhookBody(outcome)));
                     }
                     catch (e) {
                         res.statusCode = 500;
@@ -443,52 +904,151 @@ 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 });
-                    return new Response(JSON.stringify({ ok: true, outcome: { status: outcome.status, decisionId: outcome.decisionId } }), { status: 200, headers: { "content-type": "application/json" } });
+                    return new Response(JSON.stringify(webhookBody(outcome)), { status: 200, headers: { "content-type": "application/json" } });
                 }
                 catch (e) {
                     return new Response(JSON.stringify({ error: e?.message ?? "resume failed" }), { status: 500 });
                 }
             };
         },
-        async reconfirm(decisionId) {
-            const entry = journal.read(decisionId);
+        async reconcile(decisionId, opts) {
+            let entry;
+            try {
+                entry = await ctrl.store.getExecution(decisionId);
+            }
+            catch (e) {
+                return { reportRecorded: false, executionConfirmed: false, diagnostic: `the durable state for ${decisionId} could not be read (${e?.message ?? e}). Refusing to settle a decision whose state is unknown — inspect the store first.` };
+            }
             if (!entry) {
+                return { reportRecorded: false, executionConfirmed: false, diagnostic: `nothing is recorded for ${decisionId} in this store, so there is nothing to reconcile. Check the decision id, or the store this worker is configured with.` };
+            }
+            let settleEvidence;
+            try {
+                settleEvidence = opts.outcome === "committed" ? toCanonical(opts.evidence ?? null, "reconcile(evidence)") : null;
+            }
+            catch (e) {
+                return { reportRecorded: false, executionConfirmed: false, diagnostic: `the evidence you passed to reconcile("${decisionId}") is not reportable as-is (${e?.message ?? e}). Nothing was settled. Pass plain JSON — the same rule your action's return value follows.` };
+            }
+            const settleSig = opts.outcome === "committed"
+                ? signEvidence(decisionId, entry.attemptId ?? null, settleEvidence, ctrl.agentKey, ctrl.webhookSecret)
+                : undefined;
+            try {
+                await ctrl.store.settle(decisionId, opts.outcome, { evidence: settleEvidence, reason: opts.reason, evidenceSig: settleSig });
+            }
+            catch (e) {
+                return { reportRecorded: false, executionConfirmed: false, diagnostic: `${e?.message ?? e}` };
+            }
+            if (opts.outcome !== "committed") {
+                console.warn(`[decidio] ${decisionId}: released for one more attempt on your assertion that nothing committed${opts.reason ? ` (${opts.reason})` : ""}. The next resume signal will run it.`);
+                return { reportRecorded: false, executionConfirmed: false, diagnostic: `${decisionId} is parked again and may run once more. Nothing was reported, because on your account nothing executed.` };
+            }
+            let request;
+            try {
+                request = buildResumeConfirmRequest(ctrl, decisionId, settleEvidence);
+            }
+            catch (e) {
+                return { reportRecorded: false, executionConfirmed: false, diagnostic: `the reconciled report for ${decisionId} could not be signed (${e?.message ?? e}). The evidence IS recorded locally — fix the agent's signing config (DECIDIO_AGENT_KEY/DID) and re-send it with reconfirm("${decisionId}").` };
+            }
+            let ev;
+            try {
+                ev = await postConfirm(ctrl, decisionId, request);
+            }
+            catch (e) {
+                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(() => { });
+            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) {
+            let entry;
+            try {
+                entry = await ctrl.store.getExecution(decisionId);
+            }
+            catch (e) {
+                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.` };
+            }
+            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.` };
+            }
+            if (!entry || !entry.hasEvidence) {
                 return {
                     reportRecorded: false, executionConfirmed: false,
-                    diagnostic: `nothing is journalled for ${decisionId}: either its report was already recorded (nothing to do) or this process never executed it. Check the record in Decidio — do NOT re-run the action to find out.`,
+                    diagnostic: `nothing is recorded for ${decisionId}: either its report was already recorded (nothing to do) or this process never executed it. Check the record in Decidio — do NOT re-run the action to find out.`,
                 };
             }
+            const evStrict = !!ctrl.agentKey;
+            const evStatus = verifyEvidence(entry, ctrl.agentKey, ctrl.webhookSecret);
+            if (evStatus === "mismatch") {
+                return { reportRecorded: false, executionConfirmed: false, diagnostic: `the recorded evidence for ${decisionId} does not match its integrity binding — it was altered after this agent wrote it. REFUSING to attest it. Inspect the pending store; if you know the true outcome, settle it with reconcile("${decisionId}", …).` };
+            }
+            if (evStatus !== "ok" && evStrict && !opts?.acceptUnbound) {
+                const why = entry.migratedFrom
+                    ? `it was migrated from ${entry.migratedFrom}, which predates evidence binding — that is expected, and it is why this call has an override`
+                    : `this agent signs its evidence, so a record without a usable binding did not come from this agent`;
+                return { reportRecorded: false, executionConfirmed: false, diagnostic: `the recorded evidence for ${decisionId} carries ${evStatus === "unbound" ? "NO integrity binding" : "a binding this agent's key cannot verify"} (${why}). REFUSING to attest it by default. If you have checked what this row claims and want it sent anyway: reconfirm("${decisionId}", { acceptUnbound: true }). If you do not trust it, settle the decision instead: reconcile("${decisionId}", …).` };
+            }
+            if (evStatus !== "ok" && evStrict)
+                console.warn(`[decidio] ${decisionId}: attesting evidence with ${evStatus === "unbound" ? "NO integrity binding" : "an unverifiable binding"} because acceptUnbound was passed${entry.migratedFrom ? ` (row migrated from ${entry.migratedFrom})` : ""}. You are vouching for this row; the agent's signature will say it came from here.`);
+            if (evStatus !== "ok")
+                console.warn(`[decidio] ${decisionId}: re-sending an execution report whose evidence is ${evStatus === "unbound" ? "UNBOUND (written without agent key material, so it cannot be integrity-checked)" : "UNVERIFIABLE with this agent's current key material"}${entry.migratedFrom ? ` — it was migrated from ${entry.migratedFrom}, which predates evidence binding` : ""}. Run \`npx @decidio/sdk init\` to enable binding.`);
             let request;
             try {
-                request = buildResumeConfirmRequest(ctrl, decisionId, entry.reported);
+                request = buildResumeConfirmRequest(ctrl, decisionId, entry.evidence);
             }
             catch (e) {
                 return { reportRecorded: false, executionConfirmed: false, diagnostic: `the journalled report for ${decisionId} could not be re-signed (${e?.message ?? e}). The entry is kept; fix the agent's signing config (DECIDIO_AGENT_KEY/DID) and retry.` };
             }
-            const ev = await postConfirm(ctrl, decisionId, request);
+            let ev;
+            try {
+                ev = await postConfirm(ctrl, decisionId, request);
+            }
+            catch (e) {
+                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)
-                journal.clear(decisionId);
+                await ctrl.store.markReported(decisionId, entry.attemptId ?? "reconfirm", ev.evidenceTier ?? "recorded").catch(() => { });
             return ev;
         },
         async recover() {
             const items = [];
-            for (const e of journal.list()) {
-                items.push({
-                    decisionId: e.decisionId, action: e.action, state: "executed_unreported",
-                    guidance: `"${e.action}" executed at ${e.at} and its execution report has not been recorded. Re-send it safely: guard.resume.reconfirm("${e.decisionId}") — this replays the saved report and cannot re-run the action.`,
-                });
-            }
-            const claimed = ctrl.store.listClaimed ? await ctrl.store.listClaimed().catch(() => []) : [];
-            for (const p of claimed) {
-                if (journal.read(p.decisionId))
-                    continue;
-                items.push({
-                    decisionId: p.decisionId, action: p.action, state: "indeterminate",
-                    guidance: `"${p.action}" was CLAIMED for execution but no result was ever recorded: a process died mid-flight, so it is unknown locally whether the action ran. Reconcile in the downstream system (or with an idempotency key) before deciding. The SDK will NOT retry it automatically, and neither should a script.`,
-                });
-            }
-            for (const p of await ctrl.store.list().catch(() => [])) {
-                items.push({ decisionId: p.decisionId, action: p.action, state: "parked", guidance: `"${p.action}" is parked awaiting a human decision. Nothing has executed.` });
+            const execs = await ctrl.store.listExecutions().catch((e) => {
+                console.error(`[decidio] recover(): the execution ledger could not be read (${e?.message ?? e}). Nothing is reported rather than reporting a falsely empty recovery list.`);
+                return null;
+            });
+            if (execs === null)
+                return items;
+            for (const r of execs) {
+                const a = r.action ?? "(unknown action)";
+                switch (r.state) {
+                    case "executed_unreported":
+                        items.push({ decisionId: r.decisionId, action: r.action, state: "executed_unreported",
+                            guidance: `"${a}" executed at ${r.at} and its execution report has not been recorded. Re-send it safely: guard.resume.reconfirm("${r.decisionId}") — this replays the saved report and cannot re-run the action.` });
+                        break;
+                    case "indeterminate":
+                        items.push({ decisionId: r.decisionId, action: r.action, state: "indeterminate",
+                            guidance: `"${a}" was INVOKED and its outcome is unknown${r.error ? ` (${r.error})` : ""}. It will NOT be retried automatically. Check the downstream system, then settle it: guard.resume.reconcile("${r.decisionId}", { outcome: "committed", evidence: … }) or { outcome: "not_committed", reason: … }.` });
+                        break;
+                    case "invoking":
+                        items.push({ decisionId: r.decisionId, action: r.action, state: "indeterminate",
+                            guidance: `"${a}" was invoked at ${r.at} and this process died before recording the outcome, so whether it ran is unknown locally. It will NOT be retried automatically — reconcile it as above.` });
+                        break;
+                    case "claimed_preinvoke":
+                        items.push({ decisionId: r.decisionId, action: r.action, state: "claimed_stalled",
+                            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.` });
+                        break;
+                    case "reported":
+                        break;
+                }
             }
             return items;
         },