@decidio/sdk 0.1.10 → 0.1.11

package/dist/cli.js

@@ -7,7 +7,7 @@ import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline";
 import { createRequire } from "node:module";
 import { generateKeypair } from "./signing.js";
-import { withApproval, DecidioRateLimitError } from "./index.js";
+import { withApproval, DecidioRateLimitError, didFromPrivateKey } from "./index.js";
 import { verifyReceipt, runVerify } from "@decidio/verify";
 const VERSION = (() => {
     try {
@@ -18,6 +18,7 @@ const VERSION = (() => {
     }
 })();
 let envWarned = false;
+let envUnreadable = false;
 function readEnvFile() {
     const out = {};
     try {
@@ -29,9 +30,10 @@ function readEnvFile() {
             }
     }
     catch (e) {
+        envUnreadable = true;
         if (!envWarned) {
             envWarned = true;
-            console.error(`⚠ could not read .env (${e?.code ?? e?.message ?? e}) — continuing without it. Fix its permissions if you meant it to load.`);
+            console.error(`⚠ could not read .env (${e?.code ?? e?.message ?? e}).`);
         }
     }
     return out;
@@ -58,6 +60,11 @@ async function api(path, init = {}, bearer) {
         err(`· decidio → ${API}${process.env.DECIDIO_API_URL ? "" : "  (default: the hosted sandbox — set DECIDIO_API_URL to point elsewhere)"}`);
     }
     const auth = bearer ?? TOKEN();
+    if (auth && envUnreadable && !process.env.DECIDIO_API_URL) {
+        err(`✘ .env exists here but could not be read, so the target Decidio is unknown — refusing to send credentials to a guessed host (${API}).`);
+        err(`  Fix the file's permissions, or set DECIDIO_API_URL explicitly for this command. Nothing was sent.`);
+        process.exit(1);
+    }
     if (auth && /^http:[/][/]/i.test(API) && !/^http:[/][/](localhost|127.0.0.1|.::1.)([:/]|$)/i.test(API)) {
         err(`✘ refusing to send credentials over plaintext http to ${API} — use https, or localhost for local dev. Nothing was sent.`);
         process.exit(1);
@@ -137,6 +144,28 @@ function upsertEnv(updates) {
         lines.push(`${k}=${v}`);
     writeSecretFile(ENV_PATH, lines.join("\n") + "\n");
 }
+function isTrackedByGit(path) {
+    try {
+        execFileSync("git", ["ls-files", "--error-unmatch", path], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function assertNotTracked(path) {
+    if (!isTrackedByGit(path))
+        return true;
+    err(`✘ ${path} is ALREADY TRACKED by git — refusing to write the agent's private key into it.`);
+    err(`  A .gitignore entry does not untrack a file: the next \`git add -A\` would commit`);
+    err(`  DECIDIO_AGENT_KEY and DECIDIO_API_TOKEN into permanent history. Nothing was written.`);
+    err(`  Fix it, then re-run:`);
+    err(`    git rm --cached ${path}        # stop tracking it (keeps your local copy)`);
+    err(`    git commit -m "stop tracking ${path}"`);
+    err(`  If it has ALREADY been committed with secrets in it, rotate them — history rewriting`);
+    err(`  alone does not un-leak a key that was pushed.`);
+    return false;
+}
 function ensureGitignore() {
     const entries = [".env", ".env.quickstart", ".env.*.bak", ".decidio-pending/"];
     const existing = existsSync(".gitignore") ? readFileSync(".gitignore", "utf8") : "";
@@ -144,7 +173,7 @@ function ensureGitignore() {
     if (!missing.length)
         return;
     appendFileSync(".gitignore", (existing && !existing.endsWith("\n") ? "\n" : "") + missing.join("\n") + "\n");
-    log(`✔ added ${missing.join(" + ")} to .gitignore (your agent key and parked actions stay out of git)`);
+    log(`✔ added ${missing.join(" + ")} to .gitignore (new secret files here will not be committed)`);
 }
 function ask(question, mute = false) {
     return new Promise((resolve) => {
@@ -204,6 +233,8 @@ async function acquireSession(purpose) {
     return null;
 }
 async function cmdInit(agentId, opts = {}) {
+    if (!assertNotTracked(ENV_PATH))
+        return 1;
     err(`Registering agent "${agentId}" with Decidio at ${API}…`);
     const existingEnv = readEnvFile();
     const existingKey = existingEnv.DECIDIO_AGENT_KEY;
@@ -342,8 +373,20 @@ async function cmdDoctor() {
     log(secret ? "✔ webhook secret: set — operator-only transport (inactive against the hosted sandbox; the poll worker guard.worker() is the self-serve resume path)"
         : "• webhook secret: not set — only needed for the operator resume-webhook transport; the poll worker guard.worker() is the self-serve resume path (init generates one)");
     const signing = (process.env.DECIDIO_AGENT_KEY || env.DECIDIO_AGENT_KEY) && (process.env.DECIDIO_AGENT_DID || env.DECIDIO_AGENT_DID);
-    if (signing)
-        log("✔ signing key: set — the agent can prove its identity, making it ELIGIBLE for policy auto-approve. Whether a rule matches is your workspace policy's decision; with no matching rule every request routes to a human (deny-by-default).");
+    if (signing) {
+        const storedDid = (process.env.DECIDIO_AGENT_DID || env.DECIDIO_AGENT_DID);
+        let derived;
+        try {
+            derived = didFromPrivateKey((process.env.DECIDIO_AGENT_KEY || env.DECIDIO_AGENT_KEY));
+        }
+        catch { }
+        if (!derived)
+            line(false, "signing key: PRESENT BUT UNREADABLE — DECIDIO_AGENT_KEY is not a valid Ed25519 private key. Re-run `npx @decidio/sdk init` (its public half is what Decidio registered).");
+        else if (derived !== storedDid)
+            line(false, `signing key: DOES NOT MATCH this agent's DID — the key here derives ${derived}, but .env registers ${storedDid}. Signed requests will not be recognised as this agent (auto-approve and application_confirmed evidence will both fail). Restore the original key, or re-run \`npx @decidio/sdk init\` to register a fresh one.`);
+        else
+            log("✔ signing key: set and MATCHES the registered DID — the agent can prove its identity, making it ELIGIBLE for policy auto-approve. Whether a rule matches is your workspace policy's decision; with no matching rule every request routes to a human (deny-by-default).");
+    }
     else
         warn("signing key: MISSING (DECIDIO_AGENT_KEY/DID) — the agent can't prove identity, so EVERY request routes to a human. Run `npx @decidio/sdk init` to generate one.");
     const h = await api("/api/health", {}, "");
@@ -366,7 +409,7 @@ async function cmdDoctor() {
                 else if (days <= 14)
                     warn(`agent token: expires in ${left} — mint a fresh one before it does: npx @decidio/sdk init ${env.DECIDIO_AGENT_ID ?? "<agent>"}`);
                 else
-                    log(`✔ agent token: valid for another ${days} days`);
+                    log(`✔ agent token: unexpired for another ${days} days (validity is decided by the server — see the token-scope check below)`);
             }
         }
         catch { }
@@ -396,6 +439,11 @@ async function cmdApprovals(sub, id, reason, flags = {}) {
         sub = undefined;
     if ((sub === "approve" || sub === "reject") && !id) {
         err(`usage: npx @decidio/sdk approvals ${sub} <decisionId> [reason]`);
+        err(`       npx @decidio/sdk approvals ${sub} <decisionId> --reason "text with -dashes"`);
+        return 2;
+    }
+    if ((sub === "approve" || sub === "reject") && (flags.json || flags.mine)) {
+        err(`✘ ${flags.json ? "--json" : "--mine"} applies to \`approvals\` (the list), not to ${sub} — refusing to ignore a flag you meant to matter.`);
         return 2;
     }
     if (mineOnly && !process.env.DECIDIO_AGENT_ID) {
@@ -422,8 +470,18 @@ async function cmdApprovals(sub, id, reason, flags = {}) {
                 return 1;
             }
             log(`✔ ${sub === "approve" ? "approved" : "rejected"} ${id}${r.body?.resumeSignal ? ` — agent signalled (${r.body.resumeSignal.ok ? "ok" : r.body.resumeSignal.error})` : ""}`);
-            if (sub === "approve")
-                log(`  The agent's function runs next — a blocking call resumes now; a durable one when its worker or resume route picks this up.`);
+            if (reason) {
+                log(`  reason sent verbatim: ${JSON.stringify(reason)}`);
+                log(`  (it seals immutably; personal or sensitive values are tokenized at rest, so the`);
+                log(`   stored text can differ — see exactly what was kept: npx @decidio/sdk receipt ${id})`);
+            }
+            if (sub === "approve") {
+                log(`  What happens next depends on how the agent is waiting:`);
+                log(`    • durable (the production mode): its worker or resume route picks this up and executes.`);
+                log(`    • blocking, still running: it resumes now.`);
+                log(`    • blocking, already timed out or exited: NOTHING executes — that process is gone, and this`);
+                log(`      approval resolved the RECORD only. Re-run the action to request again.`);
+            }
             else
                 log(`  The agent's action will NOT run; the rejection seals as a verifiable record.`);
             log(`  Download the receipt: npx @decidio/sdk receipt ${id}`);
@@ -517,11 +575,13 @@ async function cmdReceipt(id, jsonMode = false) {
     if (conf?.status)
         log(`  Sealed credential: the authority decision (its confirmation field reads "pending" forever — immutable). Current record evidence tier: ${conf.status}${conf.confirmed ? " (confirmed)" : ""}.`);
     log(`  Verify it offline — no Decidio account or network needed (the verifier is built in):`);
-    log(`    npx @decidio/sdk verify ${name}`);
     if (issuer) {
-        log(`  Your workspace's issuer DID (from the authenticated response — record it once, then pin it forever):`);
-        log(`    ${issuer}`);
         log(`    npx @decidio/sdk verify --issuer ${issuer} ${name}`);
+        log(`  That pins the check to your workspace's issuer DID (read from the authenticated`);
+        log(`  response above — record it once, then pin it forever):`);
+        log(`    ${issuer}`);
+        log(`  Without --issuer the verifier proves the receipt is internally consistent, but NOT who`);
+        log(`  issued it; it says so in its output.`);
     }
     else {
         log(`  To also prove WHO issued it, pin your workspace's issuer DID (shown in your app's record verify panel):`);
@@ -536,8 +596,8 @@ function cmdVerify(argsIn) {
         const a = argsIn[i];
         if (a === "--issuer") {
             const v = argsIn[i + 1];
-            if (v === undefined || v.startsWith("-")) {
-                err("✘ --issuer needs a did:key value.");
+            if (v === undefined || v === "" || v.startsWith("-")) {
+                err("✘ --issuer needs a did:key value (a bare or EMPTY --issuer must not silently verify unpinned).");
                 return 2;
             }
             expectedIssuer = v;
@@ -609,6 +669,8 @@ async function cmdQuickstart(opts = {}) {
     let envFile = ENV_PATH;
     if (readEnvFile().DECIDIO_AGENT_KEY) {
         envFile = ".env.quickstart";
+        if (!assertNotTracked(envFile))
+            return 1;
         ensureGitignore();
         if (existsSync(envFile)) {
             const prev = readFileSync(envFile, "utf8");
@@ -623,6 +685,8 @@ async function cmdQuickstart(opts = {}) {
         log(`  ✔ this directory already has an agent in .env — tour credentials went to ${envFile} (your agent is untouched)`);
     }
     else {
+        if (!assertNotTracked(ENV_PATH))
+            return 1;
         ensureGitignore();
         upsertEnv(envOut);
     }
@@ -762,8 +826,12 @@ async function quickstartCleanup(session, envFile) {
             log(`  • token was already revoked (jti ${env.DECIDIO_TOKEN_JTI}) — nothing to do.`);
         else if (rev.status >= 200 && rev.status < 300)
             log(`  ✔ token revoked (jti ${env.DECIDIO_TOKEN_JTI})`);
-        else
-            log(`  ⚠ token revoke returned ${rev.status} — it still expires on its own within 7 days. List tokens: npx @decidio/sdk tokens list`);
+        else {
+            err(`✘ token revoke returned ${rev.status} — the tour's token is STILL LIVE (it would expire on its own within 7 days).`);
+            err(`  Nothing was deleted: ${envFile} still holds the jti so you can retry. Run \`npx @decidio/sdk quickstart cleanup\` again, or revoke it directly:`);
+            err(`    npx @decidio/sdk tokens revoke ${env.DECIDIO_TOKEN_JTI}`);
+            return 1;
+        }
     }
     else {
         log(`  ⚠ no DECIDIO_TOKEN_JTI in ${envFile} (older tour) — revoke by hand: npx @decidio/sdk tokens list, then tokens revoke <jti>. It expires on its own within 7 days.`);
@@ -916,6 +984,10 @@ const USAGE = `decidio — the Decidio SDK command line
   npx @decidio/sdk approvals [--json] [--mine]   list pending agent approvals
   npx @decidio/sdk approvals approve <id> [reason]
   npx @decidio/sdk approvals reject <id> [reason]
+                                       the reason is FREE TEXT and is sealed verbatim. If it
+                                       starts with a dash, put it after -- or use --reason:
+                                         ... approve <id> -- "-50% cut, per the board"
+                                         ... approve <id> --reason "-50% cut, per the board"
   npx @decidio/sdk receipt <id>        download a sealed decision's Authority Receipt (.json)
   npx @decidio/sdk verify [--issuer <did>] <receipt.json> [more...]   verify receipts OFFLINE
   npx @decidio/sdk dev [--target URL] [--port N]   local relay for the resume webhook
@@ -949,7 +1021,7 @@ async function main(argv) {
         quickstart: { flags: ["--auto-approve-demo", "--keep-agent"] },
         init: { flags: ["--unique", "--force"], valued: ["--expires-days"] },
         doctor: { flags: [] },
-        approvals: { flags: ["--json", "--mine"] },
+        approvals: { flags: ["--json", "--mine"], valued: ["--reason"] },
         receipt: { flags: ["--json"] },
         verify: { flags: [], valued: ["--issuer"] },
         tokens: { flags: ["--mine"] },
@@ -961,6 +1033,10 @@ async function main(argv) {
         const positionals = [];
         for (let i = 0; i < argsIn.length; i++) {
             const a = argsIn[i];
+            if (a === "--") {
+                positionals.push(...argsIn.slice(i + 1));
+                break;
+            }
             if (!a.startsWith("--")) {
                 positionals.push(a);
                 continue;
@@ -1028,8 +1104,28 @@ async function main(argv) {
         }
         case "doctor": return cmdDoctor();
         case "approvals": {
-            const positional = argsIn.filter((x) => !x.startsWith("-"));
-            return cmdApprovals(positional[0], positional[1], positional.slice(2).join(" ") || undefined, { json: argsIn.includes("--json"), mine: argsIn.includes("--mine") });
+            const dashdash = argsIn.indexOf("--");
+            const head = dashdash >= 0 ? argsIn.slice(0, dashdash) : argsIn;
+            const literal = dashdash >= 0 ? argsIn.slice(dashdash + 1) : [];
+            const rIdx = head.indexOf("--reason");
+            const flagless = head.filter((x, i) => !x.startsWith("-") && !(rIdx >= 0 && i === rIdx + 1));
+            const sub = flagless[0];
+            const id = flagless[1];
+            let reason;
+            if (rIdx >= 0)
+                reason = head[rIdx + 1];
+            else if (literal.length)
+                reason = literal.join(" ");
+            else if (sub && id) {
+                const after = head.indexOf(id) + 1;
+                const rest = head.slice(after).filter((x) => x !== "--json" && x !== "--mine");
+                reason = rest.length ? rest.join(" ") : undefined;
+            }
+            if (rIdx >= 0 && (reason === undefined || reason.startsWith("-"))) {
+                err(`✘ --reason needs the text to record (quote it if it contains spaces): npx @decidio/sdk approvals ${sub ?? "approve"} <id> --reason "over budget -50% cut required"`);
+                return 2;
+            }
+            return cmdApprovals(sub, id, reason, { json: head.includes("--json"), mine: head.includes("--mine") });
         }
         case "receipt": return cmdReceipt(argsIn.find((x) => !x.startsWith("-")), argsIn.includes("--json"));
         case "verify": return cmdVerify(argsIn);

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+/** A gate response this SDK could not accept, carrying what a caller needs to BRANCH on rather
+ *  than a stringified body they would have to parse. `status` is the HTTP status; `retryable`
+ *  distinguishes a terminal refusal (401/403 — a credential problem no retry fixes) from a
+ *  transient one (5xx, 429). Every long-running agent hits the terminal case eventually: an
+ *  agent token expires, or `init` is re-run and revokes it. */
+export declare class DecidioHttpError extends Error {
+    status: number;
+    endpoint: string;
+    body?: unknown | undefined;
+    readonly retryable: boolean;
+    constructor(status: number, endpoint: string, body?: unknown | undefined);
+}

package/dist/errors.js

@@ -0,0 +1,18 @@
+export class DecidioHttpError extends Error {
+    status;
+    endpoint;
+    body;
+    retryable;
+    constructor(status, endpoint, body) {
+        const terminal = status === 401 || status === 403;
+        super(`[decidio] ${endpoint} refused this call (HTTP ${status})` +
+            (terminal
+                ? ` — the credential was rejected. The agent token may have expired or been revoked (re-running \`init\` for the same agent revokes the previous one). Mint a fresh one: npx @decidio/sdk init <agent-name>, then restart this process. Nothing was routed or executed.`
+                : ` — this looks transient; retrying is safe (a retry creates a NEW request and can never double-execute). Nothing was routed or executed.`));
+        this.status = status;
+        this.endpoint = endpoint;
+        this.body = body;
+        this.name = "DecidioHttpError";
+        this.retryable = !terminal;
+    }
+}

package/dist/evidence.d.ts

@@ -0,0 +1,41 @@
+/** Every tier the gate can record, weakest to strongest. Mirrors the server's enum exactly; an
+ *  answer outside this list means this SDK version does not understand the record, and an answer
+ *  we do not understand is never treated as evidence. */
+export declare const EVIDENCE_TIERS: readonly ["pending", "execution_unconfirmed", "agent_asserted", "sensor_observed", "application_confirmed", "independently_reconciled"];
+export type EvidenceTier = (typeof EVIDENCE_TIERS)[number];
+export interface EvidenceOutcome {
+    /** Decidio accepted the report and named the tier it recorded. */
+    reportRecorded: boolean;
+    /** The tier Decidio recorded, verbatim. */
+    evidenceTier?: EvidenceTier;
+    /** The recorded tier attests a committed execution. */
+    executionConfirmed: boolean;
+    /** Present when the outcome is worth explaining (why a signed report did not confirm, or why
+     *  a report was not recorded at all) — always actionable, never a shrug. */
+    diagnostic?: string;
+}
+/** The SERVER's rule for `application_confirmed`, restated here exactly as implemented so this
+ *  explanation can never drift from it: the captured response must carry a RECORD ID
+ *  (`id` / `recordId` / `Id`), and must not explicitly deny success (`success: false` /
+ *  `ok: false`). An id with no success field is treated as a commit; a response with neither is
+ *  honestly `execution_unconfirmed`. */
+export declare function describeTierGap(capturedResponse: unknown): string;
+/** Read the gate's confirm response and say precisely what happened. Fail-closed: an unknown or
+ *  missing tier is NOT a recorded report. */
+export declare function readConfirmResponse(body: unknown, opts: {
+    signed: boolean;
+    capturedResponse?: unknown;
+    journalled?: boolean;
+}): EvidenceOutcome;
+import { type RequesterIdentity } from "./signing.js";
+/** Minimal identity a confirm body needs. */
+export interface ReportIdentity {
+    agentId: string;
+    agentKey?: string;
+    agentDid?: string;
+    workspaceId?: string;
+}
+/** The ONE confirm request shape, shared by every door (inline, durable resume, adapters).
+ *  Carries the identity proof (who is reporting) AND — when a key is configured — a signed,
+ *  decision-bound ExecutionReport over the canonical response digest (what was reported). */
+export declare function buildConfirmBody(cfg: ReportIdentity, decisionId: string, canonicalResult: unknown, requesterIdentity?: RequesterIdentity, source?: string): Record<string, unknown>;

package/dist/evidence.js

@@ -0,0 +1,57 @@
+export const EVIDENCE_TIERS = [
+    "pending",
+    "execution_unconfirmed",
+    "agent_asserted",
+    "sensor_observed",
+    "application_confirmed",
+    "independently_reconciled",
+];
+const CONFIRMING = ["sensor_observed", "application_confirmed", "independently_reconciled"];
+export function describeTierGap(capturedResponse) {
+    const r = (capturedResponse ?? {});
+    const id = r.id ?? r.recordId ?? r.Id ?? null;
+    const denied = r.success === false || r.ok === false;
+    if (denied) {
+        return "your protected function reported success: false (or ok: false), so Decidio recorded the execution as UNCONFIRMED — that is the response saying the downstream write did not commit. If it did commit, return a truthy success flag.";
+    }
+    if (id == null) {
+        return "your protected function's return value carried no record id (`id`, `recordId` or `Id`), so Decidio has no evidence that the downstream write committed and honestly recorded the execution as UNCONFIRMED. Return the source system's identifiers (e.g. `{ id, success }` or `{ recordId, ok }`), or map them with the `evidence` option, to earn application_confirmed.";
+    }
+    return "the report was accepted but the gate recorded a weaker tier — check that this agent's registration and signing key still match (`npx @decidio/sdk doctor`).";
+}
+export function readConfirmResponse(body, opts) {
+    const retry = opts.journalled
+        ? "re-send the report with `guard.resume.reconfirm(decisionId)` once connectivity or the service is healthy."
+        : "this path journalled no report, so there is nothing to re-send from here — record the outcome from your own system, or run the action through `guard.protect`'s durable mode, where reports ARE journalled and `reconfirm` can replay them.";
+    const b = body;
+    if (!b || b.ok !== true || typeof b.confirmation !== "string") {
+        return { reportRecorded: false, executionConfirmed: false, diagnostic: `the gate answered 2xx but named no evidence tier — the execution report is NOT recorded. Your action DID run; ${retry}` };
+    }
+    const tier = b.confirmation;
+    if (!EVIDENCE_TIERS.includes(tier)) {
+        return { reportRecorded: false, executionConfirmed: false, diagnostic: `the gate reported an evidence tier this SDK does not recognise (${JSON.stringify(tier)}) — refusing to treat it as evidence. Upgrade @decidio/sdk; your action DID run, and ${retry}` };
+    }
+    const executionConfirmed = CONFIRMING.includes(tier);
+    const outcome = { reportRecorded: true, evidenceTier: tier, executionConfirmed };
+    if (!executionConfirmed && opts.signed)
+        outcome.diagnostic = describeTierGap(opts.capturedResponse);
+    else if (!executionConfirmed)
+        outcome.diagnostic = "no signing key is configured, so the gate capped this report at an unproven agent assertion. Run `npx @decidio/sdk init` to generate the agent's key and earn a confirming tier.";
+    return outcome;
+}
+import { signExecutionReport, resultDigest } from "./signing.js";
+export function buildConfirmBody(cfg, decisionId, canonicalResult, requesterIdentity, source = "wrapper") {
+    const executionReport = (cfg.agentKey && cfg.agentDid)
+        ? signExecutionReport(cfg.agentKey, {
+            decisionId, agentId: cfg.agentId, did: cfg.agentDid, workspaceId: cfg.workspaceId,
+            source, resultDigest: resultDigest(canonicalResult ?? null),
+        })
+        : undefined;
+    return {
+        decisionId,
+        capturedResponse: canonicalResult ?? null,
+        source,
+        ...(requesterIdentity ? { requesterIdentity } : {}),
+        ...(executionReport ? { executionReport } : {}),
+    };
+}

package/dist/guard.d.ts

@@ -21,7 +21,12 @@ export interface GuardFacadeConfig {
 }
 export interface ProtectOptions {
     /** null/"generic" → the core gate; engine adapters (langgraph/openai/temporal/inngest)
-     *  live in @decidio/sdk subpaths and take the engine handle. */
+     *  live in @decidio/sdk subpaths and take the engine handle.
+     *
+     *  BETA: the engine adapters share the core's gate semantics (verdict allow-list, canonical
+     *  arguments, transport rule and evidence handling are one implementation, conformance-tested
+     *  across every door), but their ENGINE integration is verified against structural mocks, not
+     *  live engines. Use the core path for production until that changes. */
     adapter?: "generic" | "langgraph" | "openai" | "temporal" | "inngest";
     /** "durable" (default) suspends for async approval; "blocking" polls (short approvals only). */
     mode?: "durable" | "blocking";
@@ -37,11 +42,25 @@ export interface ProtectOptions {
     pollTimeoutMs?: number;
     /** Blocking-mode poll interval in ms (default 3000). */
     pollIntervalMs?: number;
+    /** 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, so instead of forcing your API into magic field names:
+     *  `evidence: (r) => ({ recordId: r.transactionId, success: r.status === "committed" })`. */
+    evidence?: (result: any) => unknown;
 }
 export declare class Guard {
     config: GuardFacadeConfig;
-    resume?: ResumeController;
+    private _resume?;
     constructor(config: GuardFacadeConfig, resume?: ResumeController);
+    /** The recovery surface — `guard.resume.recover()` / `.reconfirm(id)`. BUILT ON FIRST ACCESS,
+     *  because the process that needs to recover is usually a COLD one that never made the original
+     *  call, so nothing has lazily constructed the controller yet. As a plain field this read was
+     *  `undefined` there and the documented recovery loop crashed on the exact path it exists for.
+     *  Unconfigured still fails loud (naming DECIDIO_API_URL), never silently. */
+    get resume(): ResumeController;
+    /** Kept writable: hosts that construct their own controller (custom store, injected fetch)
+     *  assign it here, and `new Guard(cfg, controller)` must stay equivalent to that assignment. */
+    set resume(r: ResumeController);
     static fromEnv(): Guard;
     /** Register a raw fn under its action name so a COLD process (one that never made the original
      *  call) can resume it. Call this at startup beside `guard.worker()` — or pass

package/dist/guard.js

@@ -2,11 +2,13 @@ import { withApproval } from "./index.js";
 import { createDecidioResume, FilePendingStore } from "./resume.js";
 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 ?? "",
@@ -30,16 +32,16 @@ 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"),
                 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 +63,19 @@ 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 });
+        if (opts?.evidence)
+            resume.evidence = 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 } 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>;