@decidio/sdk 0.1.10 → 0.1.12

package/dist/guard.js

@@ -1,12 +1,15 @@
 import { withApproval } from "./index.js";
 import { createDecidioResume, FilePendingStore } from "./resume.js";
+import { join } from "node:path";
 export class Guard {
     config;
-    resume;
+    _resume;
     constructor(config, resume) {
         this.config = config;
-        this.resume = resume;
+        this._resume = resume;
     }
+    get resume() { return this.ensureResume(); }
+    set resume(r) { this._resume = r; }
     static fromEnv() {
         return new Guard({
             apiUrl: process.env.DECIDIO_API_URL ?? "",
@@ -22,7 +25,7 @@ export class Guard {
             appUrl: process.env.DECIDIO_APP_URL,
         });
     }
-    register(action, fn) { this.ensureResume().register(action, fn); }
+    register(action, fn, evidence) { this.ensureResume().register(action, fn, evidence); }
     resumeHandler() { return this.ensureResume().webhookHandler(); }
     resumeFetchHandler() { return this.ensureResume().fetchHandler(); }
     worker(opts) {
@@ -30,16 +33,17 @@ export class Guard {
     }
     ensureResume() {
         this.assertConfigured();
-        if (!this.resume) {
+        if (!this._resume) {
             const c = this.config;
-            this.resume = createDecidioResume({
+            this._resume = createDecidioResume({
                 apiUrl: c.apiUrl, apiToken: c.apiToken, webhookSecret: c.webhookSecret,
                 resumeUrl: c.resumeUrl, store: new FilePendingStore(c.pendingDir ?? ".decidio-pending"),
+                reportDir: join(c.pendingDir ?? ".decidio-pending", "reports"),
                 agentId: c.agentId, agentKey: c.agentKey, agentDid: c.agentDid, workspaceId: c.workspaceId,
                 fetchImpl: c.fetchImpl,
             });
         }
-        return this.resume;
+        return this._resume;
     }
     assertConfigured() {
         if (!this.config.apiUrl)
@@ -61,14 +65,17 @@ export class Guard {
             pollTimeoutMs: opts?.pollTimeoutMs, pollIntervalMs: opts?.pollIntervalMs,
         };
         if ((opts?.mode ?? "durable") === "blocking") {
-            console.warn("[decidio] WARNING: blocking wait — only safe for short, watched approvals. " +
-                "Omit mode:\"blocking\" for durable async resume on real (minutes-to-days) approvals.");
-            return withApproval(fn, describe, base);
+            const ceilingMs = opts?.pollTimeoutMs ?? base.pollTimeoutMs ?? 600_000;
+            console.warn(`[decidio] WARNING: blocking wait — this call gives up after ${Math.round(ceilingMs / 1000)}s ` +
+                `(pollTimeoutMs), and when it does, the decision stays OPEN in Decidio while this process stops waiting: ` +
+                `a later approval cannot resume it. Only safe for short, watched approvals — omit mode:"blocking" for ` +
+                `durable async resume on real (minutes-to-days) approvals.`);
+            return withApproval(fn, describe, base, opts?.evidence ? { evidence: opts.evidence } : undefined);
         }
         const resume = this.ensureResume();
         if (opts?.action)
-            resume.register(opts.action, fn);
-        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume });
+            resume.register(opts.action, fn, opts?.evidence);
+        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume }, opts?.evidence ? { evidence: opts.evidence } : undefined);
     }
 }
 export const guard = Guard.fromEnv();

package/dist/index.d.ts

@@ -3,7 +3,12 @@ export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDeci
 export type { PendingAction, PendingStore, ResumeController, ResumeOutcome } from "./resume.js";
 export { guard, Guard } from "./guard.js";
 export type { GuardFacadeConfig, ProtectOptions } from "./guard.js";
-export { generateKeypair, signBoundProof, signConfirm, canonicalize, assertJsonSafe, assertSafeTransport, DecidioUnsafeArgumentsError } from "./signing.js";
+export { DecidioHttpError } from "./errors.js";
+export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential } from "./signing.js";
+export { canonicalize, canonicalizeArgs, canonicalJson, DecidioUnsafeArgumentsError } from "./canonical.js";
+export type { JsonValue, JsonPrimitive } from "./canonical.js";
+export { readConfirmResponse, buildConfirmBody, describeTierGap, EVIDENCE_TIERS } from "./evidence.js";
+export type { EvidenceOutcome, EvidenceTier } from "./evidence.js";
 export type { RequesterIdentity } from "./signing.js";
 export interface GuardConfig {
     /** Base URL of the Decidio gate, e.g. "https://api.decidio.io". */
@@ -102,4 +107,10 @@ export declare class DecidioNetworkError extends Error {
 /** `<appUrl>/d/<decisionId>` — the deep link that opens this decision directly, on the web app or
  *  the phone build. Null when DECIDIO_APP_URL is not configured, never a half-built URL. */
 export declare function decisionUrl(appUrl: string | undefined, decisionId: string): string | null;
-export declare function withApproval<A extends any[], R>(fn: (...args: A) => Promise<R>, describe: (...args: A) => ApprovalContext, config: GuardConfig): (...args: A) => Promise<R>;
+export declare function withApproval<A extends any[], R>(fn: (...args: A) => Promise<R>, describe: (...args: A) => ApprovalContext, config: GuardConfig, opts?: {
+    /** Map YOUR function's natural return value to the evidence Decidio records. The gate awards
+     *  its strongest wrapper tier (application_confirmed) only for a committed record id plus a
+     *  success indication — this lets a real API keep its own shape instead of being forced into
+     *  magic field names: `evidence: (r) => ({ recordId: r.transactionId, success: r.status === "committed" })`. */
+    evidence?: (result: R) => unknown;
+}): (...args: A) => Promise<R>;

package/dist/index.js

@@ -1,8 +1,14 @@
-import { DecidioSuspendedError, assertConfirmRecorded } from "./resume.js";
-import { signBoundProof, signConfirm, assertJsonSafe, assertSafeTransport, DecidioUnsafeArgumentsError } from "./signing.js";
+import { DecidioSuspendedError } from "./resume.js";
+import { signBoundProof, signConfirm, assertSafeTransport, carriesCredential } from "./signing.js";
+import { canonicalize, canonicalizeArgs } from "./canonical.js";
+import { readConfirmResponse, buildConfirmBody } from "./evidence.js";
 export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 export { guard, Guard } from "./guard.js";
-export { generateKeypair, signBoundProof, signConfirm, canonicalize, assertJsonSafe, assertSafeTransport, DecidioUnsafeArgumentsError } from "./signing.js";
+export { DecidioHttpError } from "./errors.js";
+import { DecidioHttpError } from "./errors.js";
+export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential } from "./signing.js";
+export { canonicalize, canonicalizeArgs, canonicalJson, DecidioUnsafeArgumentsError } from "./canonical.js";
+export { readConfirmResponse, buildConfirmBody, describeTierGap, EVIDENCE_TIERS } from "./evidence.js";
 export class DecidioBlockedError extends Error {
     reason;
     decisionId;
@@ -74,7 +80,7 @@ async function reach(f, url, op, init) {
 }
 async function post(cfg, path, body) {
     const f = cfg.fetchImpl ?? fetch;
-    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
+    assertSafeTransport(cfg.apiUrl, carriesCredential(cfg));
     const res = await reach(f, cfg.apiUrl.replace(/\/$/, "") + path, `POST ${path}`, {
         method: "POST",
         headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
@@ -84,18 +90,25 @@ async function post(cfg, path, body) {
         const b = await res.json().catch(() => null);
         throw new DecidioRateLimitError(b?.limit, b?.remaining, b?.resetAt, b?.message);
     }
-    if (!res.ok)
-        throw new Error(`decidio ${path} ${res.status}: ${await res.text().catch(() => "")}`);
+    if (!res.ok) {
+        const raw = await res.text().catch(() => "");
+        let parsed = raw;
+        try {
+            parsed = raw ? JSON.parse(raw) : undefined;
+        }
+        catch { }
+        throw new DecidioHttpError(res.status, path, parsed);
+    }
     return res.json();
 }
 async function get(cfg, path) {
     const f = cfg.fetchImpl ?? fetch;
-    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
+    assertSafeTransport(cfg.apiUrl, carriesCredential(cfg));
     const res = await reach(f, cfg.apiUrl.replace(/\/$/, "") + path, `GET ${path}`, {
         headers: { ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
     });
     if (!res.ok)
-        throw new Error(`decidio ${path} ${res.status}`);
+        throw new DecidioHttpError(res.status, path);
     return res.json();
 }
 export function decisionUrl(appUrl, decisionId) {
@@ -103,27 +116,32 @@ export function decisionUrl(appUrl, decisionId) {
         return null;
     return `${appUrl.replace(/\/$/, "")}/d/${encodeURIComponent(decisionId)}`;
 }
-export function withApproval(fn, describe, config) {
+export function withApproval(fn, describe, config, opts) {
     const pollInterval = config.pollIntervalMs ?? 2_000;
     const pollTimeout = config.pollTimeoutMs ?? 600_000;
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;
-    return async (...args) => {
+    return async (...rawArgs) => {
+        const args = canonicalizeArgs(rawArgs);
+        let ctx;
         try {
-            assertJsonSafe(args, "args");
+            ctx = describe(...args);
         }
         catch (e) {
-            throw new DecidioUnsafeArgumentsError(`${e?.message ?? e} The decision was NOT routed; nothing reached Decidio.`);
+            if (e instanceof TypeError && /read only|not extensible|object is not extensible|frozen/i.test(e.message ?? "")) {
+                throw new TypeError(`[decidio] your describe() callback tried to MODIFY the call arguments (${e.message}). ` +
+                    `Those arguments are the approved value: they are what a human sees, what the signature covers, ` +
+                    `what is parked for a durable resume, and what your function ultimately runs on — so changing them ` +
+                    `here would mean the action that executes is not the action that was approved. Read from the ` +
+                    `arguments and RETURN the context instead: (inv) => ({ action: "pay", amount: inv.amount }). ` +
+                    `If you need a modified value at execution time, compute it inside your function. ` +
+                    `Nothing was routed or executed.`);
+            }
+            throw e;
         }
-        const ctx = describe(...args);
         const requesterIdentity = (config.agentKey && config.agentDid)
             ? signBoundProof(config.agentKey, { agentId: config.agentId, did: config.agentDid, action: ctx.action, amount: ctx.amount, scope: ctx.scope, workspaceId: config.workspaceId })
             : undefined;
-        try {
-            assertJsonSafe(ctx, "describe(...)");
-        }
-        catch (e) {
-            throw new DecidioUnsafeArgumentsError(`${e?.message ?? e} The decision was NOT routed; nothing reached Decidio.`);
-        }
+        canonicalize(ctx, "describe(...)");
         const auth = await post(config, "/agent/authorize", {
             requester: config.agentId, action: ctx.action, amount: ctx.amount,
             scope: ctx.scope, sourceSystem: config.sourceSystem,
@@ -133,6 +151,8 @@ export function withApproval(fn, describe, config) {
         });
         if (auth.decision !== "proceed" && auth.decision !== "route" && auth.decision !== "block")
             throw new DecidioBlockedError(`unrecognized gate verdict: ${String(auth.decision)}`, auth.decisionId);
+        if (typeof auth.decisionId !== "string" || !auth.decisionId)
+            throw new DecidioBlockedError(`the gate answered "${auth.decision}" with no usable decisionId (${JSON.stringify(auth.decisionId ?? null)}) — refusing to execute. Every authorized action must be addressable: without an id it cannot be polled, resumed, confirmed or audited.`, auth.decisionId);
         if (auth.decision === "block")
             throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
         if (auth.decision === "route") {
@@ -145,7 +165,7 @@ export function withApproval(fn, describe, config) {
                 config.resume.agentId ??= config.agentId;
                 config.resume.agentKey ??= config.agentKey;
                 config.resume.agentDid ??= config.agentDid;
-                config.resume.register(ctx.action, fn);
+                config.resume.register(ctx.action, fn, opts?.evidence);
                 await config.resume.park({
                     decisionId: auth.decisionId, receiptId: auth.receiptId,
                     action: ctx.action, amount: ctx.amount, scope: ctx.scope, args,
@@ -169,17 +189,26 @@ export function withApproval(fn, describe, config) {
             }
         }
         const result = await fn(...args);
+        let reported = null;
+        let evidenceProblem;
+        try {
+            const evidenceOf = (opts?.evidence ?? ((r) => r));
+            reported = canonicalize(evidenceOf(result) ?? null, "evidence(result)");
+        }
+        catch (e) {
+            evidenceProblem = String(e?.message ?? e);
+            console.warn(`[decidio] ${auth.decisionId}: the action SUCCEEDED but its result could not be reported as evidence (${evidenceProblem}). Reporting an empty captured response so the execution is still recorded — map the return value with the \`evidence\` option (e.g. evidence: (r) => ({ recordId: String(r.id), success: true })) to earn a confirming tier. The action was NOT re-run.`);
+        }
         try {
             const confirmIdentity = signConfirm(auth.decisionId, config);
-            const confirmBody = await post(config, "/agent/confirm", {
-                decisionId: auth.decisionId,
-                capturedResponse: result ?? null,
-                source: "wrapper",
-                ...(confirmIdentity ? { requesterIdentity: confirmIdentity } : {}),
-            });
-            assertConfirmRecorded(confirmBody, auth.decisionId, !!confirmIdentity);
-            if (!confirmIdentity)
-                console.warn(`[decidio] execution evidence for ${auth.decisionId} recorded as agent_asserted — no signing key configured, so the report can't be proven to come from this agent. Set DECIDIO_AGENT_KEY/DID (npx @decidio/sdk init writes them) to earn application_confirmed.`);
+            const confirmBody = await post(config, "/agent/confirm", buildConfirmBody(config, auth.decisionId, reported, confirmIdentity));
+            const ev = readConfirmResponse(confirmBody, { signed: !!confirmIdentity, capturedResponse: reported });
+            if (!ev.reportRecorded)
+                console.warn(`[decidio] ${auth.decisionId}: ${ev.diagnostic}`);
+            else if (!ev.executionConfirmed || ev.executionReportVerified === false)
+                console.warn(`[decidio] execution evidence for ${auth.decisionId} recorded as ${ev.evidenceTier} — ${ev.diagnostic}`);
+            if (evidenceProblem)
+                console.warn(`[decidio] ${auth.decisionId}: the execution IS recorded, but with an empty captured response — see the evidence note above.`);
         }
         catch (e) {
             console.warn(`[decidio] confirmation post failed (action succeeded): ${e.message}`);

package/dist/inngest.js

@@ -1,28 +1,10 @@
 import { verifyResumeSignature } from "./resume.js";
-import { signBoundProof, signConfirm } from "./signing.js";
+import { gateAuthorize, gateConfirm, assertAuthorizeVerdict, verdictFrom, checkEngineVersion } from "./adapters/_gate.js";
 export const DECIDIO_RESUME_EVENT = "decidio/decision.resolved";
 export async function decidioGateStep(args) {
     const { step, config, ctx } = args;
-    const base = config.apiUrl.replace(/\/$/, "");
-    const f = config.fetchImpl ?? fetch;
-    const authHeaders = { "content-type": "application/json", ...(config.apiToken ? { authorization: `Bearer ${config.apiToken}` } : {}) };
-    const auth = await step.run("decidio-authorize", async () => {
-        const requesterIdentity = (config.agentKey && config.agentDid)
-            ? signBoundProof(config.agentKey, { agentId: config.agentId, did: config.agentDid, action: ctx.action, amount: ctx.amount, scope: ctx.scope, workspaceId: config.workspaceId })
-            : undefined;
-        const res = await f(base + "/agent/authorize", {
-            method: "POST", headers: authHeaders,
-            body: JSON.stringify({
-                requester: config.agentId, action: ctx.action, amount: ctx.amount, scope: ctx.scope,
-                sourceSystem: config.sourceSystem,
-                ...(requesterIdentity ? { requesterIdentity } : {}),
-                ...(config.resumeUrl ? { resumeUrl: config.resumeUrl } : {}),
-            }),
-        });
-        if (!res.ok)
-            throw new Error(`decidio authorize ${res.status}`);
-        return res.json();
-    });
+    const auth = await step.run("decidio-authorize", async () => gateAuthorize(config, ctx));
+    assertAuthorizeVerdict(auth, auth?.decisionId);
     if (auth.decision === "block")
         return { status: "blocked", decisionId: auth.decisionId };
     if (auth.decision === "route") {
@@ -33,21 +15,14 @@ export async function decidioGateStep(args) {
         });
         if (!ev)
             throw new Error(`decidio approval timed out (${auth.decisionId})`);
-        const verdict = ev.data?.verdict;
+        const verdict = verdictFrom(ev.data);
         if (verdict === "rejected")
             return { status: "rejected", decisionId: auth.decisionId };
         if (verdict !== "approved" && verdict !== "auto_approved")
             return { status: "blocked", decisionId: auth.decisionId };
     }
     const result = await step.run("agent-action", args.run);
-    await step.run("decidio-confirm", async () => {
-        const requesterIdentity = signConfirm(auth.decisionId, config);
-        await f(base + "/agent/confirm", {
-            method: "POST", headers: authHeaders,
-            body: JSON.stringify({ decisionId: auth.decisionId, capturedResponse: result ?? null, source: "wrapper", ...(requesterIdentity ? { requesterIdentity } : {}) }),
-        });
-        return true;
-    });
+    await step.run("decidio-confirm", async () => { await gateConfirm(config, auth.decisionId, result); return true; });
     return { status: "executed", decisionId: auth.decisionId, result };
 }
 export function createInngestResumeBridge(opts) {
@@ -86,3 +61,4 @@ export function createInngestResumeBridge(opts) {
     };
 }
 export { verifyResumeSignature };
+checkEngineVersion("inngest");

package/dist/resume.d.ts

@@ -1,4 +1,5 @@
 import type { RequestListener } from "node:http";
+import { type EvidenceOutcome, type EvidenceTier } from "./evidence.js";
 /** A routed action parked on the agent side, awaiting human approval. The `args`
  *  are the original call arguments, replayed verbatim when the action resumes. */
 export interface PendingAction {
@@ -41,6 +42,9 @@ export interface PendingStore {
     claim?(decisionId: string): Promise<boolean>;
     /** Undo a claim so a failed execution is retryable. */
     release?(decisionId: string): Promise<void>;
+    /** Entries currently CLAIMED (excluded from list()). Needed for honest recovery reporting —
+     *  a claimed entry with no journalled result is the indeterminate case. */
+    listClaimed?(): Promise<PendingAction[]>;
 }
 export declare class MemoryPendingStore implements PendingStore {
     private m;
@@ -51,7 +55,13 @@ export declare class MemoryPendingStore implements PendingStore {
     list(): Promise<PendingAction[]>;
     claim(id: string): Promise<boolean>;
     release(id: string): Promise<void>;
+    listClaimed(): Promise<PendingAction[]>;
 }
+/** Restrict a directory to its owner. On Windows POSIX modes are a no-op, so strip inheritance
+ *  and grant only the effective user. A FAILURE IS SAID, never swallowed: these files hold the
+ *  arguments of actions awaiting approval, and "silently kept the directory's inherited
+ *  permissions" is exactly the outcome an operator must not discover from an auditor. */
+export declare function hardenDir(dir: string): void;
 /** File-backed store so a COLD process (the original requester long gone) can still
  *  resume — the proof that nothing is "kept alive". One JSON file per decision. A claim
  *  renames `<id>.json` → `<id>.claimed` atomically (same-volume rename), so two processes
@@ -69,6 +79,9 @@ export declare class FilePendingStore implements PendingStore {
     list(): Promise<PendingAction[]>;
     claim(id: string): Promise<boolean>;
     release(id: string): Promise<void>;
+    /** Claimed entries (`.claimed` files) — invisible to list() by design, but a stranded one is
+     *  exactly what recovery must surface. */
+    listClaimed(): Promise<PendingAction[]>;
 }
 /** Thrown by a `withApproval`-wrapped call when the action is routed and configured
  *  for async resume: the action is now SUSPENDED (parked in the store), not failed.
@@ -80,18 +93,60 @@ export declare class DecidioSuspendedError extends Error {
     constructor(decisionId: string, action: string);
 }
 export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown";
+/** A durable note that an action ALREADY RAN and what must still be reported. It lives OUTSIDE
+ *  the pending store on purpose: a journal entry carries no handler binding, so replaying it can
+ *  only ever re-send a report — it can never re-run the business action. That is what makes
+ *  recovery safe on stores with and without claim(). */
+export interface ExecutionJournalEntry {
+    decisionId: string;
+    action: string;
+    /** The canonical value that was reported — the durable FACT, journalled before the first
+     *  attempt. Deliberately NOT the signed request: both proofs on a confirm are short-lived (the
+     *  identity proof lives 120s, the execution report 5 minutes), so a replayed envelope is
+     *  refused by the server for any outage longer than that — which is every outage worth
+     *  recovering from. `reconfirm` re-signs at SEND time over these same bytes, so the report
+     *  stays replay-safe (it still cannot re-run anything: no handler is journalled) while staying
+     *  usable a week later. */
+    reported: unknown;
+    at: string;
+}
+/** The states a durable action can actually be in — every one of them nameable, including the
+ *  one nobody likes. */
+export type RecoveryState = 
+/** Parked, waiting on a human. Nothing has executed. */
+"parked"
+/** Claimed for execution and NOT journalled: the process died somewhere between claiming and
+ *  recording the result. The action MAY OR MAY NOT have run — this cannot be resolved locally
+ *  and must never be retried automatically. */
+ | "indeterminate"
+/** Executed, result captured, report not yet accepted by Decidio. Safe to `reconfirm`. */
+ | "executed_unreported";
+export interface RecoveryItem {
+    decisionId: string;
+    action?: string;
+    state: RecoveryState;
+    /** What a human should do about it, in words. */
+    guidance: string;
+}
 export interface ResumeOutcome {
     status: ResumeStatus;
     decisionId: string;
     action?: string;
     result?: unknown;
     reason?: string;
-    /** executed only: did the execution-evidence report reach Decidio AND come back with a recorded
-     *  tier? `status: "executed"` describes the LOCAL run; this describes the record — a lost
-     *  confirmation must never read as recorded evidence. */
-    confirmed?: boolean;
-    /** executed only: the evidence tier the server says it recorded (e.g. application_confirmed). */
-    evidenceTier?: string;
+    /** executed only: Decidio ACCEPTED the execution report and named the tier it recorded.
+     *  `status: "executed"` describes the LOCAL run; this describes the record. */
+    reportRecorded?: boolean;
+    /** executed only: the recorded tier attests a COMMITTED execution. Deliberately a different
+     *  question — and a different name — from `reportRecorded`. */
+    executionConfirmed?: boolean;
+    /** executed only: the evidence tier Decidio recorded, verbatim. */
+    evidenceTier?: EvidenceTier;
+    /** executed only, when the gate reported on the SIGNED execution report: whether the
+     *  attestation proof VERIFIED (C3, 0.1.12). */
+    executionReportVerified?: boolean;
+    /** executed only: why the evidence landed where it did, when that is worth explaining. */
+    diagnostic?: string;
 }
 /** Minimal config the controller needs to confirm outcomes + poll status. Shared
  *  with GuardConfig (apiUrl/apiToken). */
@@ -110,6 +165,12 @@ export interface ResumeConfig {
     /** Shared secret Decidio signs the resume webhook with (HMAC-SHA256). Defaults to
      *  the API token if unset. Verified before any re-execution. */
     webhookSecret?: string;
+    /** Where the execution journal lives (default `<pending dir>/reports`). Separate from the
+     *  pending store by design: journal entries can only re-send a report, never re-run an action. */
+    reportDir?: string;
+    /** Map the action's natural return value to the evidence Decidio records — same option, same
+     *  meaning as `protect`'s, so a durable resume reports exactly what the inline path would. */
+    evidence?: (result: any) => unknown;
     /** Escape hatch to accept UNSIGNED resume webhooks (no secret). Off by default:
      *  with no secret and this unset, the webhook handler rejects every call (fail
      *  closed) so a misconfigured agent can't be driven by forged callbacks. Setting it
@@ -133,7 +194,7 @@ export interface ResumeController extends ResumeConfig {
     /** Register a RAW fn under its action name so a (possibly cold) resume can replay
      *  it. `withApproval` auto-registers on the hot path; a cold worker/service should
      *  register at startup so it can resume actions it never originated. */
-    register(action: string, fn: (...args: any[]) => Promise<any>): void;
+    register(action: string, fn: (...args: any[]) => Promise<any>, evidence?: (result: any) => unknown): void;
     /** Park a routed action WITH its integrity binding (prefer this over store.put — the
      *  binding is what lets resolve() refuse a tampered payload). */
     park(p: Omit<PendingAction, "createdAt" | "argsSig">): Promise<void>;
@@ -158,6 +219,16 @@ export interface ResumeController extends ResumeConfig {
     }): {
         stop: () => void;
     };
+    /** Re-send a journalled execution report, IDEMPOTENTLY. Replays the exact request built before
+     *  the first attempt — it can never re-run the business action, because the journal holds no
+     *  handler binding. Returns the evidence outcome; a decision with nothing journalled returns
+     *  `reportRecorded: false` with guidance rather than pretending. */
+    reconfirm(decisionId: string): Promise<EvidenceOutcome>;
+    /** Every durable item that needs a human's attention, with its state named — including the one
+     *  state that CANNOT be resolved automatically: `indeterminate`, where a process died between
+     *  claiming an action and journalling its result, so whether the action ran is unknown locally.
+     *  This never executes or retries anything; it reports. */
+    recover(): Promise<RecoveryItem[]>;
 }
 declare function sign(secret: string, body: string): string;
 /** Verify Decidio's `x-decidio-signature` over the raw webhook body (HMAC-SHA256).
@@ -168,16 +239,6 @@ export declare function verifyResumeSignature(secret: string, body: string, head
  *  tier is a FAILED confirm; a SIGNED confirm coming back below application_confirmed is
  *  disclosed, never silent. Returns the recorded tier or throws. */
 export declare function assertConfirmRecorded(body: any, decisionId: string, signed: boolean): string;
-/**
- * Build the resume controller. Spread it into your GuardConfig as `resume`, then
- * either mount `webhookHandler()` (production) or run `worker()` (CLI/laptop).
- *
- *   const resume = createDecidioResume({ apiUrl, apiToken, store: new FilePendingStore(".decidio-pending"), resumeUrl });
- *   const guard  = { apiUrl, agentId, apiToken, resume };
- *   const createOpportunity = withApproval(createOpportunityRaw, describe, guard);
- *   // production:  http.createServer(resume.webhookHandler()).listen(4100)
- *   // or CLI:      resume.worker()
- */
 export declare function createDecidioResume(opts: ResumeConfig & {
     store: PendingStore;
 }): ResumeController;