@decidio/sdk 0.1.8 → 0.1.9

package/dist/guard.d.ts

@@ -8,25 +8,53 @@ export interface GuardFacadeConfig {
     resumeUrl?: string;
     webhookSecret?: string;
     pendingDir?: string;
+    /** Local signing key (DECIDIO_AGENT_KEY) + public did (DECIDIO_AGENT_DID), from `init`.
+     *  When present the gate authorizes against a PROVEN identity, not a claimed label. */
     agentKey?: string;
     agentDid?: string;
+    /** The workspace this agent acts in (DECIDIO_WORKSPACE_ID). Bound into the signed proof (D-B3.6)
+     *  so a captured proof can't be replayed in another tenant. */
     workspaceId?: string;
+    /** Base URL of the Decidio app (DECIDIO_APP_URL) — used to deep-link a routed decision. */
     appUrl?: string;
     fetchImpl?: typeof fetch;
 }
 export interface ProtectOptions {
+    /** null/"generic" → the core gate; engine adapters (langgraph/openai/temporal/inngest/mcp)
+     *  live in @decidio/sdk/adapters and take the engine handle. */
     adapter?: "generic" | "langgraph" | "openai" | "temporal" | "inngest" | "mcp";
+    /** "durable" (default) suspends for async approval; "blocking" polls (short approvals only). */
     mode?: "durable" | "blocking";
+    /** The action name this wrapper produces, declared UP FRONT so the resume registry is populated
+     *  at WRAP time rather than on first call. Required for the cold-worker pattern: after a
+     *  restart, `guard.worker()` can only re-execute actions registered in THIS process, and
+     *  `describe` (which names the action) cannot run without the original call arguments. Declare
+     *  it and a restarted process resumes work it never originated. */
     action?: string;
+    /** Blocking-mode poll ceiling in ms (default 600000 = 10 min). Documented since 0.1.0 but only
+     *  reachable via the low-level withApproval config until now (round-2 blind catch: passing it
+     *  here was SILENTLY ignored and CI pipelines blocked the full 10 minutes instead of failing
+     *  fast — and the Python twin rejected the same call loudly, a twin divergence). */
+    pollTimeoutMs?: number;
+    /** Blocking-mode poll interval in ms (default 3000). */
+    pollIntervalMs?: number;
 }
 export declare class Guard {
     config: GuardFacadeConfig;
     resume?: ResumeController;
     constructor(config: GuardFacadeConfig, resume?: 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
+     *  `{ action }` to `protect(...)`, which does it for you at wrap time. */
     register(action: string, fn: (...a: any[]) => Promise<any>): void;
+    /** Mount on a node/Express/Fastify route: `app.post("/decidio/resume", guard.resumeHandler())`. */
     resumeHandler(): import("http").RequestListener;
+    /** Mount on a Next.js/Hono/CF/Bun route: `export const POST = (req) => guard.resumeFetchHandler()(req)`. */
     resumeFetchHandler(): (req: Request) => Promise<Response>;
+    /** Durable resume with NOTHING to host: a background watcher polls Decidio outward and finishes
+     *  any parked approval — so a suspended action survives a process restart. One line at startup.
+     *  Production may swap this for the webhook (resumeUrl); the suspend/resume shape is identical. */
     worker(opts?: {
         intervalMs?: number;
         timeoutMs?: number;
@@ -37,4 +65,5 @@ export declare class Guard {
     private ensureResume;
     protect<A extends any[], R>(fn: (...a: A) => Promise<R>, describe: (...a: A) => ApprovalContext, opts?: ProtectOptions): (...a: A) => Promise<R>;
 }
+/** Preconfigured singleton — `import { guard } from "@decidio/sdk"`. */
 export declare const guard: Guard;

package/dist/guard.js

@@ -1,3 +1,7 @@
+// The Guard facade — `guard.protect(fn, describe)`, the one agnostic line (TS mirror
+// of decidio-guard Python). A thin layer over the verified primitives: durable mode
+// builds a resume controller and suspends; blocking mode polls (opt-in, loud). The
+// agent executes its own action; Decidio gates + records + signals — never executes.
 import { withApproval } from "./index.js";
 import { createDecidioResume, FilePendingStore } from "./resume.js";
 export class Guard {
@@ -22,9 +26,17 @@ export class Guard {
             appUrl: process.env.DECIDIO_APP_URL,
         });
     }
+    /** 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
+     *  `{ action }` to `protect(...)`, which does it for you at wrap time. */
     register(action, fn) { this.ensureResume().register(action, fn); }
+    /** Mount on a node/Express/Fastify route: `app.post("/decidio/resume", guard.resumeHandler())`. */
     resumeHandler() { return this.ensureResume().webhookHandler(); }
+    /** Mount on a Next.js/Hono/CF/Bun route: `export const POST = (req) => guard.resumeFetchHandler()(req)`. */
     resumeFetchHandler() { return this.ensureResume().fetchHandler(); }
+    /** Durable resume with NOTHING to host: a background watcher polls Decidio outward and finishes
+     *  any parked approval — so a suspended action survives a process restart. One line at startup.
+     *  Production may swap this for the webhook (resumeUrl); the suspend/resume shape is identical. */
     worker(opts) {
         return this.ensureResume().worker(opts);
     }
@@ -34,6 +46,8 @@ export class Guard {
             this.resume = createDecidioResume({
                 apiUrl: c.apiUrl, apiToken: c.apiToken, webhookSecret: c.webhookSecret,
                 resumeUrl: c.resumeUrl, store: new FilePendingStore(c.pendingDir ?? ".decidio-pending"),
+                // Carry the signing identity so the durable/cold confirm on resume is signed too (incl. the
+                // workspace binding — D-B3.6 — so a cold-resume confirm proof is tenant-scoped as well).
                 agentId: c.agentId, agentKey: c.agentKey, agentDid: c.agentDid, workspaceId: c.workspaceId,
                 fetchImpl: c.fetchImpl,
             });
@@ -42,22 +56,33 @@ export class Guard {
     }
     protect(fn, describe, opts) {
         if (opts?.adapter && opts.adapter !== "generic") {
+            // Engine adapters are bound explicitly via @decidio/sdk/adapters (they need the
+            // engine handle at call time). Surfaced as a clear error until wired in this build.
             throw new Error(`[decidio] adapter "${opts.adapter}" must be bound via the @decidio/sdk/${opts.adapter} subpath (it needs the engine handle). See that adapter's exports.`);
         }
         const c = this.config;
         const base = {
             apiUrl: c.apiUrl, agentId: c.agentId, apiToken: c.apiToken,
             sourceSystem: c.sourceSystem, agentKey: c.agentKey, agentDid: c.agentDid, workspaceId: c.workspaceId, appUrl: c.appUrl, fetchImpl: c.fetchImpl,
+            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.");
+            // No resumeUrl on the blocking path — the server must not fire a webhook to an
+            // endpoint a blocking agent isn't serving; the poll is the only resume channel.
             return withApproval(fn, describe, base);
         }
+        // durable: refuse-don't-downgrade — always wire a resume transport, never silently block.
         const resume = this.ensureResume();
+        // WRAP-TIME registration when the action is declared: the call-time registration inside
+        // withApproval only helps the process that made the original call, so a restarted worker
+        // found an empty registry and answered no_handler — the documented restart-survival pattern
+        // could not actually work without this (or an explicit guard.register at startup).
         if (opts?.action)
             resume.register(opts.action, fn);
         return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume });
     }
 }
+/** Preconfigured singleton — `import { guard } from "@decidio/sdk"`. */
 export const guard = Guard.fromEnv();

package/dist/index.d.ts

@@ -1,27 +1,54 @@
 import type { ResumeController } from "./resume.js";
-export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume } from "./resume.js";
+export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 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 } from "./signing.js";
+export { generateKeypair, signBoundProof, signConfirm, canonicalize, assertJsonSafe } from "./signing.js";
 export type { RequesterIdentity } from "./signing.js";
 export interface GuardConfig {
+    /** Base URL of the Decidio gate, e.g. "https://api.decidio.io". */
     apiUrl: string;
+    /** The agent identity registered with Decidio (onboarding wizard), e.g. "salesforce/SalesforceBot". */
     agentId: string;
+    /** Bearer token for the REST floor (a trusted, already-authenticated internal
+     *  caller). Lives ONLY in the agent host's environment — never in client code. */
     apiToken?: string;
+    /** Source system label sealed onto the receipt (e.g. "salesforce"). */
     sourceSystem?: string;
+    /** The agent's PRIVATE signing key (PKCS8 base64), generated locally by `init` and held
+     *  ONLY in the agent host's env as DECIDIO_AGENT_KEY. When set (with `agentDid`), the SDK
+     *  signs a request-bound identity proof on each authorize so the floor PROVES the requester
+     *  instead of trusting the label — required for a registered agent to auto-approve. */
     agentKey?: string;
+    /** The agent's PUBLIC did:key (the one registered with Decidio). Pairs with `agentKey`. */
     agentDid?: string;
+    /** The workspace this agent acts in (DECIDIO_WORKSPACE_ID, from the owner's agent-token mint).
+     *  Bound into the signed proof (D-B3.6) so a captured proof can't be replayed in another tenant.
+     *  For a tester's per-workspace agent token this is the tester's workspace id. */
     workspaceId?: string;
+    /** Poll cadence + ceiling while a routed action awaits human approval. Used ONLY
+     *  by the blocking transport (no `resume` configured). */
     pollIntervalMs?: number;
     pollTimeoutMs?: number;
+    /** Optional async notifier so a long human wait surfaces in your logs/UI. */
     onPending?: (info: {
         decisionId: string;
         receiptId: string;
         url: string | null;
     }) => void;
+    /** Base URL of the Decidio app (DECIDIO_APP_URL). When set, a routed action can say WHERE to
+     *  approve it — `<appUrl>/d/<decisionId>` opens that decision directly, on web or on the phone
+     *  build. This link used to be built only inside our own example, so a developer who pasted the
+     *  env block set DECIDIO_APP_URL and nothing ever read it. */
     appUrl?: string;
+    /** Durable async resume. When set, a routed action SUSPENDS (parks its args in the
+     *  store, throws DecidioSuspendedError) instead of blocking — the process may exit
+     *  and resume later via the controller's webhook handler or poll worker. This is
+     *  the production transport for real (minutes-to-days) human approvals. */
     resume?: ResumeController;
+    /** Callback URL Decidio POSTs the verdict to on approval (webhook transport).
+     *  Sent on /agent/authorize so the decision carries it. Falls back to
+     *  resume.resumeUrl. Omit when using the poll worker. */
     resumeUrl?: string;
     fetchImpl?: typeof fetch;
 }
@@ -29,6 +56,9 @@ export interface ApprovalContext {
     action: string;
     amount: number;
     scope?: string;
+    /** Optional human-facing DETAILS of the action (e.g. { Account, "Lead Source", Stage }) shown to
+     *  the approver as "what you're approving". Display-only — the policy decides on `amount`/`scope`,
+     *  never these. Residual-safe tokenized server-side before persistence. */
     context?: Record<string, string | number>;
 }
 export declare class DecidioBlockedError extends Error {
@@ -45,6 +75,15 @@ export declare class DecidioTimeoutError extends Error {
     decisionId: string;
     constructor(decisionId: string);
 }
+/** A transport failure with GUIDANCE instead of a raw undici stack (round-4 Codex catch: the CLI
+ *  wrapped network errors kindly but the runtime leaked `TypeError: fetch failed`). Carries the
+ *  endpoint, the operation, the underlying code, and the safety state a caller cares about most:
+ *  whether anything could have executed. */
+/** The workspace's governed-action allowance is exhausted (HTTP 429, code AGENT_RATE). The
+ *  server says exactly how much and until when — relayed here instead of discarded (round-2
+ *  blind catch: this surfaced as a bare `Error` with no decisionId, the tour misdiagnosed it as
+ *  a connectivity failure, and doctor then corroborated the wrong suspect). Nothing was routed,
+ *  recorded, or executed; retry after `resetAt`. */
 export declare class DecidioRateLimitError extends Error {
     limit: number | undefined;
     remaining: number | undefined;
@@ -57,5 +96,12 @@ export declare class DecidioNetworkError extends Error {
     code: string | undefined;
     constructor(endpoint: string, op: string, code: string | undefined, cause: unknown);
 }
+/**
+ * Wrap an async action behind the Decidio gate. `describe` extracts the approval
+ * context (action, amount, scope) from the call arguments. Returns a function with
+ * the SAME signature as `fn` — drop-in.
+ */
+/** `<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>;

package/dist/index.js

@@ -1,8 +1,37 @@
-import { DecidioSuspendedError } from "./resume.js";
-import { signBoundProof, signConfirm } from "./signing.js";
-export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume } from "./resume.js";
+// @decidio/sdk — the one-line approval gate for AI-agent actions.
+//
+//   import { guard } from "@decidio/sdk";
+//   const createOpportunity = guard.protect(createOpportunityRaw, (a) => ({
+//     action: "createOpportunity", amount: a.amount, scope: "Opportunity",
+//   }));
+//
+// NOTE: `guard` is the preconfigured SINGLETON (a Guard instance, see guard.ts). It is NOT a
+// GuardConfig, so it cannot be passed as withApproval's third argument — this comment used to
+// show exactly that, and the error propagated into the product's own copy-paste snippets.
+// `withApproval(fn, describe, config)` is the lower-level export and takes a config OBJECT.
+//
+// On call, the wrapper asks Decidio's gate to authorize the action. Decidio's
+// policy engine (Cedar / computeChain) returns proceed | route | block:
+//   • proceed → the wrapped fn runs immediately (auto-approved under policy)
+//   • route   → the wrapper WAITS for a human to approve in Decidio's queue, then
+//               runs the fn (or throws if rejected)
+//   • block   → the wrapper throws; the fn never runs
+// The wrapper is a LISTENER: it captures the real source-system response the wrapped
+// fn returns and reports it to Decidio, which seals an `application_confirmed`
+// Authority Receipt (Decidio minimizes + tokenizes before sealing — the immutable
+// seal never stores raw payloads). The agent executes its own action; Decidio
+// authorizes, records, and (optionally) independently verifies it. Decidio holds NO
+// write credentials for your system — only the authority decision and the record.
+//
+// Framework-agnostic by design: it wraps at the tool-call boundary, so it works with
+// any agent runtime (LangGraph, OpenAI Agents SDK, CrewAI, a raw tool loop) and any
+// action (Salesforce, M365, SAP, a DB write) — the wrapper doesn't care what the fn
+// does, only that it returns the source response.
+import { DecidioSuspendedError, assertConfirmRecorded } from "./resume.js";
+import { signBoundProof, signConfirm, assertJsonSafe } from "./signing.js";
+export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 export { guard, Guard } from "./guard.js";
-export { generateKeypair, signBoundProof, signConfirm, canonicalize } from "./signing.js";
+export { generateKeypair, signBoundProof, signConfirm, canonicalize, assertJsonSafe } from "./signing.js";
 export class DecidioBlockedError extends Error {
     reason;
     decisionId;
@@ -32,6 +61,15 @@ export class DecidioTimeoutError extends Error {
     }
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** A transport failure with GUIDANCE instead of a raw undici stack (round-4 Codex catch: the CLI
+ *  wrapped network errors kindly but the runtime leaked `TypeError: fetch failed`). Carries the
+ *  endpoint, the operation, the underlying code, and the safety state a caller cares about most:
+ *  whether anything could have executed. */
+/** The workspace's governed-action allowance is exhausted (HTTP 429, code AGENT_RATE). The
+ *  server says exactly how much and until when — relayed here instead of discarded (round-2
+ *  blind catch: this surfaced as a bare `Error` with no decisionId, the tour misdiagnosed it as
+ *  a connectivity failure, and doctor then corroborated the wrong suspect). Nothing was routed,
+ *  recorded, or executed; retry after `resetAt`. */
 export class DecidioRateLimitError extends Error {
     limit;
     remaining;
@@ -50,6 +88,9 @@ export class DecidioNetworkError extends Error {
     op;
     code;
     constructor(endpoint, op, code, cause) {
+        // A refused localhost connection almost always means MISSING CONFIG, not a broken network
+        // (blind-review catch: forgetting `--env-file .env` produced advice about network debugging).
+        // Name the likely cause before the generic one.
         super(`[decidio] could not reach ${endpoint} during ${op}${code ? ` (${code})` : ""}. ` +
             (/localhost|127\.0\.0\.1/.test(endpoint) && code === "ECONNREFUSED"
                 ? `A refused localhost connection usually means the SDK never saw your config: if your settings live in .env, run node with --env-file=.env (or export DECIDIO_API_URL — the hosted sandbox is https://decidio-api.onrender.com). `
@@ -96,6 +137,13 @@ async function get(cfg, path) {
         throw new Error(`decidio ${path} ${res.status}`);
     return res.json();
 }
+/**
+ * Wrap an async action behind the Decidio gate. `describe` extracts the approval
+ * context (action, amount, scope) from the call arguments. Returns a function with
+ * the SAME signature as `fn` — drop-in.
+ */
+/** `<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 function decisionUrl(appUrl, decisionId) {
     if (!appUrl)
         return null;
@@ -107,9 +155,16 @@ export function withApproval(fn, describe, config) {
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;
     return async (...args) => {
         const ctx = describe(...args);
+        // 1. ask the gate (carry the resume URL so a routed decision knows where to call back).
+        //    When a signing key is configured, sign a request-bound identity proof so the floor
+        //    can PROVE this agent rather than trust the `requester` label (registered agents must
+        //    sign to auto-approve). Unsigned still works for generic/non-agent callers.
         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;
+        // The described request must ALSO be JSON-safe (prodsec F-01): a NaN amount would reach the
+        // human as null — they would approve something other than what the caller described.
+        assertJsonSafe(ctx, "describe(...)");
         const auth = await post(config, "/agent/authorize", {
             requester: config.agentId, action: ctx.action, amount: ctx.amount,
             scope: ctx.scope, sourceSystem: config.sourceSystem,
@@ -117,28 +172,52 @@ export function withApproval(fn, describe, config) {
             ...(requesterIdentity ? { requesterIdentity } : {}),
             ...(resumeUrl ? { resumeUrl } : {}),
         });
+        // Allow-list, not deny-list: an unrecognised verdict means this SDK is older than the
+        // server, and the safe reading of an answer you do not understand is NO. Without this, the
+        // day a fourth verdict ships every deployed SDK falls through and executes it.
         if (auth.decision !== "proceed" && auth.decision !== "route" && auth.decision !== "block")
             throw new DecidioBlockedError(`unrecognized gate verdict: ${String(auth.decision)}`, auth.decisionId);
         if (auth.decision === "block")
             throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
+        // 2. routed → either SUSPEND for async resume (durable) or BLOCK-poll (interactive)
         if (auth.decision === "route") {
+            // ALWAYS hand back the decision id — an agent that suspends and says only "waiting" leaves
+            // the operator hunting through a queue, and an agent that says NOTHING (the pre-0.1.2 bug:
+            // the print was gated on appUrl, which init never writes) leaves them staring at a silent
+            // terminal. The Codex acceptance run failed exactly this claim; the id line is unconditional
+            // now, with the deep link when appUrl is configured and the CLI command when not.
             const approvalUrl = decisionUrl(config.appUrl, auth.decisionId);
             if (config.onPending)
                 config.onPending({ decisionId: auth.decisionId, receiptId: auth.receiptId, url: approvalUrl });
+            // stderr, not stdout: this is SDK diagnostics inside a USER'S process — their stdout
+            // belongs to their application output (round-3 blind catch: piping the agent's stdout
+            // captured this status line interleaved with app output, while the warning went to stderr).
             else
-                console.log(`[decidio] ${ctx.action} is awaiting approval (decision ${auth.decisionId}) — approve it ${approvalUrl ? `at ${approvalUrl}` : `in your Decidio queue, or: npx @decidio/sdk approvals approve ${auth.decisionId}`}`);
+                console.error(`[decidio] ${ctx.action} is awaiting approval (decision ${auth.decisionId}) — approve it ${approvalUrl ? `at ${approvalUrl}` : `in your Decidio queue, or: npx @decidio/sdk approvals approve ${auth.decisionId}`}`);
+            // Durable transport: park the args agent-side, register the raw fn so a (cold)
+            // resume can replay it, and SUSPEND. The process may exit now; the controller's
+            // webhook handler or poll worker re-executes THIS fn when a human approves.
+            // Decidio never executes — it only signals.
             if (config.resume) {
+                // Propagate the agent's signing identity to the resume controller so the eventual
+                // (possibly cold) confirm on resume is SIGNED too — earning application_confirmed on
+                // the durable path, not just inline. (No-op if the controller already has its own.)
                 config.resume.agentId ??= config.agentId;
                 config.resume.agentKey ??= config.agentKey;
                 config.resume.agentDid ??= config.agentDid;
                 config.resume.register(ctx.action, fn);
+                // park() (not store.put) so the payload is SIGNED — resolve() refuses a pending file
+                // whose args no longer match what was routed (round-6 acceptance catch).
                 await config.resume.park({
                     decisionId: auth.decisionId, receiptId: auth.receiptId,
                     action: ctx.action, amount: ctx.amount, scope: ctx.scope, args,
                 });
                 throw new DecidioSuspendedError(auth.decisionId, ctx.action);
             }
+            // Interactive transport (no resume configured): block until decided. Only
+            // appropriate for short, watched approvals (demos, synchronous tools).
             const deadline = Date.now() + pollTimeout;
+            // eslint-disable-next-line no-constant-condition
             while (true) {
                 const st = await get(config, `/agent/status/${encodeURIComponent(auth.decisionId)}`);
                 if (st.state === "approved" || st.state === "auto_approved")
@@ -148,25 +227,42 @@ export function withApproval(fn, describe, config) {
                 if (st.state === "blocked")
                     throw new DecidioBlockedError(st.reason ?? "blocked", auth.decisionId);
                 if (Date.now() > deadline) {
+                    // The founder-visible failure of blocking: the wait has a ceiling, and past it the
+                    // work is LOST — the decision stays open in Decidio but nothing is parked to resume.
+                    // Say so, say the limit, and say the durable way out.
                     console.warn(`[decidio] blocking wait hit its ${Math.round(pollTimeout / 1000)}s limit — decision ${auth.decisionId} is still open in Decidio, but this process stopped waiting and nothing was executed. Re-run to request again, or use durable resume (guard.worker()) so an approval is never lost.`);
                     throw new DecidioTimeoutError(auth.decisionId);
                 }
                 await sleep(pollInterval);
             }
         }
+        // 3. authorized inline (proceed, or interactive route just approved) → run the
+        //    REAL action and capture the source response (listener)
         const result = await fn(...args);
+        // 4. report the captured outcome → Decidio seals application_confirmed
+        //    (server minimizes + tokenizes the response before sealing). Best-effort:
+        //    a confirmation failure must not undo a successful business action.
         try {
+            // Sign the confirmation too (bound to {action:"confirm", scope:decisionId}) so the gate
+            // can PROVE this is the receipt's original requester before granting the wrapper tier
+            // (application_confirmed). Without a key the report is capped at agent_asserted server-side.
             const confirmIdentity = signConfirm(auth.decisionId, config);
-            await post(config, "/agent/confirm", {
+            const confirmBody = await post(config, "/agent/confirm", {
                 decisionId: auth.decisionId,
                 capturedResponse: result ?? null,
-                source: "wrapper",
+                source: "wrapper", // the SDK captured the genuine response, not an agent self-report
                 ...(confirmIdentity ? { requesterIdentity: confirmIdentity } : {}),
             });
+            // The ONE confirm-body rule, on this door too (guard equivalent-path catch: transport
+            // success is not confirmation — a tierless 2xx must not read as recorded evidence).
+            assertConfirmRecorded(confirmBody, auth.decisionId, !!confirmIdentity);
+            // An UNSIGNED confirm is server-capped at the weaker agent_asserted tier. Say so at the
+            // moment it happens — a silent evidence downgrade was round 3's acceptance FAIL.
             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.`);
         }
         catch (e) {
+            // surface but don't throw — the action already happened
             console.warn(`[decidio] confirmation post failed (action succeeded): ${e.message}`);
         }
         return result;

package/dist/inngest.d.ts

@@ -1,7 +1,11 @@
 import type { RequestListener } from "node:http";
 import { verifyResumeSignature } from "./resume.js";
 import type { GuardConfig, ApprovalContext } from "./index.js";
+/** The Inngest event Decidio's verdict is translated into. The waiting function
+ *  correlates on `data.decisionId`. */
 export declare const DECIDIO_RESUME_EVENT = "decidio/decision.resolved";
+/** The minimal slices of the Inngest step + client APIs we use, typed structurally so
+ *  this file doesn't force an `inngest` type dependency on the core build. */
 export interface InngestStepLike {
     run<T>(id: string, fn: () => Promise<T>): Promise<T>;
     waitForEvent(id: string, opts: {
@@ -25,6 +29,16 @@ export type GateStepOutcome<R> = {
     decisionId: string;
     result?: R;
 };
+/**
+ * Gate an action INSIDE an Inngest function, with durable suspend on routing.
+ *   • proceed → run the action (as a step) + confirm.
+ *   • route   → `step.waitForEvent` durably suspends until Decidio's resume event for
+ *               THIS decision arrives; approved → run + confirm; rejected → status.
+ *   • block   → return blocked (the action never runs).
+ * The action runs in YOUR process with YOUR credentials — Decidio only signals.
+ * `config.resumeUrl` must point at the bridge endpoint (createInngestResumeBridge),
+ * so Decidio's webhook is translated into the event this step waits on.
+ */
 export declare function decidioGateStep<R>(args: {
     step: InngestStepLike;
     config: GuardConfig;
@@ -32,6 +46,12 @@ export declare function decidioGateStep<R>(args: {
     run: () => Promise<R>;
     timeout?: string;
 }): Promise<GateStepOutcome<R>>;
+/**
+ * Decidio → Inngest bridge. Mount as an HTTP endpoint and register it as the agent's
+ * `resumeUrl`. It verifies Decidio's signed resume webhook (same HMAC as the core
+ * handler) and emits `DECIDIO_RESUME_EVENT` into Inngest, waking the suspended
+ * `decidioGateStep`. Fails CLOSED without a configured secret (unless allowUnsigned).
+ */
 export declare function createInngestResumeBridge(opts: {
     inngest: InngestClientLike;
     webhookSecret?: string;

package/dist/inngest.js

@@ -1,12 +1,26 @@
 import { verifyResumeSignature } from "./resume.js";
 import { signBoundProof, signConfirm } from "./signing.js";
+/** The Inngest event Decidio's verdict is translated into. The waiting function
+ *  correlates on `data.decisionId`. */
 export const DECIDIO_RESUME_EVENT = "decidio/decision.resolved";
+/**
+ * Gate an action INSIDE an Inngest function, with durable suspend on routing.
+ *   • proceed → run the action (as a step) + confirm.
+ *   • route   → `step.waitForEvent` durably suspends until Decidio's resume event for
+ *               THIS decision arrives; approved → run + confirm; rejected → status.
+ *   • block   → return blocked (the action never runs).
+ * The action runs in YOUR process with YOUR credentials — Decidio only signals.
+ * `config.resumeUrl` must point at the bridge endpoint (createInngestResumeBridge),
+ * so Decidio's webhook is translated into the event this step waits on.
+ */
 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}` } : {}) };
+    // 1. authorize (memoized as a step, so a replay doesn't re-ask the gate)
     const auth = await step.run("decidio-authorize", async () => {
+        // Sign the bound proof so an Inngest-path agent can prove its identity + auto-approve.
         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;
@@ -26,6 +40,9 @@ export async function decidioGateStep(args) {
     if (auth.decision === "block")
         return { status: "blocked", decisionId: auth.decisionId };
     if (auth.decision === "route") {
+        // 2. durably SUSPEND until the resume event for THIS decision arrives. Zero
+        //    compute while waiting; the worker/process may be recycled — Inngest resumes
+        //    from this checkpoint. `if` correlates the awaited event to this decisionId.
         const ev = await step.waitForEvent("decidio-await-approval", {
             event: DECIDIO_RESUME_EVENT,
             timeout: args.timeout ?? "30d",
@@ -39,6 +56,8 @@ export async function decidioGateStep(args) {
         if (verdict !== "approved" && verdict !== "auto_approved")
             return { status: "blocked", decisionId: auth.decisionId };
     }
+    // 3. authorized → perform the agent's OWN action (a step), then confirm the captured
+    //    response so Decidio seals application_confirmed (never executes it itself).
     const result = await step.run("agent-action", args.run);
     await step.run("decidio-confirm", async () => {
         const requesterIdentity = signConfirm(auth.decisionId, config);
@@ -50,6 +69,12 @@ export async function decidioGateStep(args) {
     });
     return { status: "executed", decisionId: auth.decisionId, result };
 }
+/**
+ * Decidio → Inngest bridge. Mount as an HTTP endpoint and register it as the agent's
+ * `resumeUrl`. It verifies Decidio's signed resume webhook (same HMAC as the core
+ * handler) and emits `DECIDIO_RESUME_EVENT` into Inngest, waking the suspended
+ * `decidioGateStep`. Fails CLOSED without a configured secret (unless allowUnsigned).
+ */
 export function createInngestResumeBridge(opts) {
     const secret = opts.webhookSecret ?? "";
     const eventName = opts.eventName ?? DECIDIO_RESUME_EVENT;
@@ -85,4 +110,5 @@ export function createInngestResumeBridge(opts) {
         });
     };
 }
+// Re-export the signature check so a host can verify the webhook out-of-band if needed.
 export { verifyResumeSignature };