@decidio/sdk 0.1.10 → 0.1.12

package/README.md

@@ -114,7 +114,9 @@ step 4 printed — angle brackets are placeholders, never typed literally). Appr
 the agent's floor-limited token — it cannot approve anything):
 
 ```bash
-npx @decidio/sdk approvals               # see it pending
+npx @decidio/sdk approvals --mine        # see it pending (--mine narrows to THIS agent; the
+                                         # sandbox is one shared lab workspace, so the bare
+                                         # command lists every member's pending decisions)
 npx @decidio/sdk approvals approve <decisionId>
 ```
 
@@ -156,11 +158,20 @@ evidence that arrives *after* the seal (your function's captured result) lives o
 **record**, not inside the credential bytes: the `receipt` command prints the record's current
 tier next to the file, and with the signing key `init` wrote you'll see `application_confirmed`
 — the wrapper's report carried a signed identity proof bound to your agent, this decision, and
-a freshness window. Precisely: the proof authenticates WHO is confirming WHAT decision — it
-does not yet sign the captured response bytes themselves (that binding is on the receipt-v2
-roadmap), so treat the tier as proven reporter identity, not a cryptographic hash of the
-result. (No signing key configured? The server caps the evidence at the weaker
-`agent_asserted`, and the SDK warns at confirm time.) Immutable seal + accruing evidence is the design, not an omission — corrections and
+a freshness window.
+
+Since 0.1.11 the report also carries an **execution report**: a separate, domain-separated,
+versioned envelope signed over a SHA-256 digest of the canonicalized response, bound to the
+decision, your agent and your workspace, with a single-use nonce and a short expiry. The server
+recomputes that digest from the response on the same request and refuses the attestation if they
+disagree — so "this agent reported this exact result for this decision" is checked, not asserted.
+It is deliberately separate from the evidence TIER: the tier says how strongly the outcome was
+observed, the report says what was reported and by whom, and no signature can turn a weak
+observation into a strong one. An unverifiable report is refused as an attestation (and the
+refusal is itself audited) while the confirmation is still recorded — an optional proof never
+destroys the record of an execution that really happened; the confirm response tells you which
+happened. (No signing key configured? No execution report is sent, the server caps the evidence
+at the weaker `agent_asserted`, and the SDK warns at confirm time.) Immutable seal + accruing evidence is the design, not an omission — corrections and
 later facts supersede, they never rewrite.
 
 One sharing note: a receipt is **not a secret, but it is not metadata-free** — it names the
@@ -204,29 +215,47 @@ exit. Two ways the parked action resumes when a human decides:
 **The worker (self-serve — start here).** No inbound URL, no shared secrets, and it resumes work
 the current process never started. Here is a complete `agent.mjs` you can run:
 
+Two files, on purpose — **the worker and the thing that creates work are different programs**.
+A single file that both starts the worker and calls the action submits a NEW request every time
+you restart it, which is the opposite of what a recovery test should show.
+
+`agent.mjs` — the long-lived worker. Restart it as often as you like; it creates nothing:
+
 ```js
 import { guard } from "@decidio/sdk";
 
-const payInvoiceRaw = async (invoice) => ({ paid: true, id: invoice.id });
+const payInvoiceRaw = async (invoice) => ({ paid: true, id: invoice.id, success: true });
 
-// Declare the action name so the wrapper registers at LOAD time, not on first call —
-// that is what lets a restarted process resume actions approved while it was down.
-const payInvoice = guard.protect(
+// Declaring the action name registers the handler at LOAD time, not on first call — that is
+// what lets a restarted process resume actions approved while it was down.
+guard.protect(
   payInvoiceRaw,
   (invoice) => ({ action: "payInvoice", amount: invoice.amount, scope: "Invoice" }),
   { action: "payInvoice" },
 );
 
-guard.worker();   // polls Decidio, re-executes parked actions on approval, one execution each
+guard.worker();   // polls Decidio and resumes approved actions; creates no work of its own
+console.log("worker running — approve a decision and watch it resume here");
+```
+
+`submit.mjs` — run this ONCE when you want a new request:
+
+```js
+import { guard } from "@decidio/sdk";
+
+const payInvoice = guard.protect(
+  async (invoice) => ({ paid: true, id: invoice.id, success: true }),
+  (invoice) => ({ action: "payInvoice", amount: invoice.amount, scope: "Invoice" }),
+  { action: "payInvoice" },
+);
 
-// New work suspends immediately; approvals land later, through the same worker.
 try { await payInvoice({ id: "INV-1", amount: 86_000 }); }
 catch (e) { console.log(e.name); }   // DecidioSuspendedError — expected, not a failure
 ```
 
-Run it with `node --env-file=.env agent.mjs`, approve from another terminal, and the running
-worker executes it. Kill the process, restart it, then approve: it still executes, because the
-action was registered at load. **If you can't declare the name at wrap time** (a dynamic
+Run `node --env-file=.env agent.mjs`, then `node --env-file=.env submit.mjs` once, approve from
+another terminal, and the running worker executes it. Now kill the worker, restart it, and
+approve: it still executes — and restarting created no second request. **If you can't declare the name at wrap time** (a dynamic
 `describe`), register the raw function explicitly at startup instead —
 `guard.register("payInvoice", payInvoiceRaw)` — before calling `guard.worker()`. Without one of
 those two, a cold worker has an empty registry and reports `no_handler` (the parked action is
@@ -246,18 +275,66 @@ also allow-list resume hosts (default-deny). That's operator territory: if you r
 Decidio (or we run a pilot with you), the webhook is set up then. Against the hosted sandbox,
 use the worker — a webhook secret your server never learned would (correctly) fail closed.
 
+**Earning the strongest evidence tier.** Decidio records `application_confirmed` — its
+strongest wrapper tier — only when your function's captured response shows a committed record:
+a record id (`id` / `recordId` / `Id`) and no explicit denial of success. Precisely, as
+implemented: an id with no `success`/`ok` field is taken as a commit; `success: false` (or
+`ok: false`) records `execution_unconfirmed` even with an id; and a response carrying no id at
+all records `execution_unconfirmed`, because Decidio then has no evidence the downstream write
+committed. Note what this does and does not mean: Decidio is trusting your wrapper's report of
+an identifier — it does not independently read that record back (that is the stronger
+`independently_reconciled` tier). If your API returns an id before the write is durable (a
+202-Accepted or queued shape), map an explicit success flag with `evidence` so the tier reflects
+the commit rather than the acknowledgement. Keep your API's natural shape and map it instead:
+
+```js
+guard.protect(chargeCard, describe, {
+  action: "chargeCard",
+  evidence: (r) => ({ recordId: r.transactionId, success: r.status === "committed" }),
+});
+```
+
+The SDK tells you which of the two is missing rather than leaving you to guess, and it reports
+`reportRecorded` (Decidio accepted the report) separately from `executionConfirmed` (the
+recorded tier attests a commit) — two different questions that used to share one name.
+
 **The supported argument data model is plain JSON**: `null`, booleans, strings, finite
 numbers, arrays, and plain objects. Anything that cannot survive JSON with its meaning intact
 — `NaN`/`Infinity`, `undefined`, `BigInt`, `Map`/`Set`/`Date`, class instances, functions,
-circular structures — is **refused before the decision is routed or the payload signed**
-(typed error naming the offending path), because a value that silently drifts in serialization
-would mean a human approves one thing and your function executes another.
+circular structures, symbol keys, getters, non-enumerable or sparse values — is **refused
+before the decision is routed or the payload signed** (typed error naming the offending path),
+because a value that silently drifts in serialization would mean a human approves one thing and
+your function executes another.
+
+Your arguments are canonicalized ONCE, and that canonical snapshot is what `describe` sees, what
+the signature covers, what is parked, and what your function ultimately receives — so the
+approved value and the executed value are the same. Consequence worth stating plainly: JSON
+canonicalization preserves **value** semantics, not JavaScript object identity. Two properties
+pointing at the same object arrive as two equal objects, and mutating an argument inside your
+function does not affect the caller's copy.
+
+**What the SDK can and cannot promise about duplicates.** It prevents *concurrent* execution:
+an entry is claimed atomically before it runs, so two workers cannot both execute it and a
+duplicate signal finds nothing to replay. It cannot make an external side effect exactly-once —
+no client can. If your action succeeds and the process dies before the result is recorded,
+whether it ran is not knowable from this machine. So the contract is **at-least-once with
+honest recovery**, and your downstream action should be idempotent (the decision id makes a
+natural idempotency key).
+
+Recovery is explicit rather than magical:
 
-Either way, re-execution is **single-use on the happy path**: the parked entry is claimed before
-execution and deleted on success, so a duplicate signal finds nothing to replay. Honest edge — if
-your action succeeds but the process dies *before* the entry is cleared, the claim can be retried
-(robust crash-recovery of stale claims is on the roadmap), so make your downstream action
-idempotent if you need exactly-once under crashes.
+```js
+for (const item of await guard.resume.recover()) {
+  console.log(item.state, item.decisionId, item.guidance);
+}
+// "executed_unreported" → guard.resume.reconfirm(id) re-sends the saved report (never re-runs)
+// "indeterminate"       → a process died mid-flight; reconcile downstream, do NOT blind-retry
+// "parked"              → still waiting on a human; nothing has executed
+```
+
+The report a worker sends is journalled *before* the first attempt, so a lost confirmation is
+recoverable; and because the journal holds no handler binding, replaying it can only re-send
+evidence — never re-run your function.
 
 **Parked arguments must be JSON-serializable.** A suspended action is signed and then written to
 disk as JSON, so values that don't survive `JSON.stringify` round-tripping — `Date`, `Map`,
@@ -286,9 +363,16 @@ imports none of them — install the engine you use alongside the SDK (`npm i in
 for engines you don't. Each adapter's shipped `.d.ts` header documents its wiring; `npx
 @decidio/sdk quickstart` is the fastest runnable end-to-end.
 
-## One surface, every runtime — and Python too
+## Engine adapters (BETA) — and Python too
 
-- **`guard.protect(fn, describe, { adapter })`** is the same call everywhere; the engine adapters above translate it onto each engine's native durable wait. No engine? The worker/webhook resume is the universal path.
+- **Engine adapters are BETA.** They share the core's gate semantics — the verdict allow-list,
+  the canonical argument model, the transport rule and evidence handling are ONE implementation,
+  and a conformance matrix runs the same malformed-verdict, unsafe-argument and plaintext-transport
+  battery against every door. What is *not* yet verified is the engine integration itself: those
+  paths are exercised against structural mocks, not live LangGraph/Temporal/Inngest/OpenAI
+  runtimes. Use the core path for production until that changes. Each adapter is bound through its
+  own `@decidio/sdk/<engine>` subpath (they need the engine handle at call time); no engine at all?
+  The worker/webhook resume is the universal path and is not beta.
 - **Python twin:** `pip install decidio` exposes the identical `guard.protect` (plus the `@guard.approve` decorator, adapters, and the offline verifier); a conformance suite asserts both languages emit an identical request + receipt.
 
 ## CLI
@@ -322,6 +406,23 @@ manager for production.
 - `DecidioRejectedError` — a human rejected the routed action.
 - `DecidioSuspendedError` — (durable mode) the action was routed and is parked for async approval; the process may exit and resume later. Not a failure.
 - `DecidioTimeoutError` — (blocking mode only) no human decided within `pollTimeoutMs` (default 10 min); the decision stays open in Decidio, nothing executed locally.
+- `DecidioRateLimitError` — the workspace's governed-action limit was hit; carries the server's `limit` / `remaining` / `resetAt`.
+- `DecidioHttpError` — the gate refused the call. Carries `status`, `endpoint`, the parsed `body`,
+  and **`retryable`** — the field to branch on. A 401/403 is terminal (the agent token expired, or
+  someone re-ran `init` for that agent and revoked it): retrying cannot help, so the message names
+  the fix. Anything else is transient, and retrying is safe because a retry creates a *new* request
+  and can never double-execute.
+- `DecidioNetworkError` — the gate was unreachable. Nothing executed locally.
+- `DecidioUnsafeArgumentsError` — your call arguments cannot survive JSON with their meaning intact, so nothing was routed and nothing ran. The message names the field and the fix. Most often: `NaN`/`Infinity`, `-0`, a `Date`, `Map` or class instance, a `BigInt`, or a sparse array — anything whose serialized form would differ from the value the approval and signature cover. Pass the already-serialized form.
+
+```js
+try { await payInvoice(inv); }
+catch (e) {
+  if (e instanceof DecidioHttpError && !e.retryable) { await alertOncall(e.message); throw e; }
+  if (e instanceof DecidioHttpError) { await backoff(); return retry(); }
+  throw e;
+}
+```
 
 Every error raised after a decision exists carries the `decisionId`, so a suspended or
 timed-out action is always findable in

package/dist/adapters/_gate.d.ts

@@ -1,13 +1,37 @@
 import { type GuardConfig, type ApprovalContext } from "../index.js";
+/** The ONLY authorization verdicts this SDK understands. A gate answer outside this set means
+ *  the SDK does not understand the decision — and an answer you do not understand means NO. */
+export declare const AUTHORIZE_VERDICTS: readonly ["proceed", "route", "block"];
+export type AuthorizeVerdict = (typeof AUTHORIZE_VERDICTS)[number];
 export interface GateAuth {
-    decision: "proceed" | "route" | "block";
+    decision: AuthorizeVerdict;
     decisionId: string;
     receiptId?: string;
     reason?: string;
 }
+/** Fail-closed verdict allow-list. Called INSIDE gateAuthorize, so every adapter that authorizes
+ *  through the shared gate is protected by construction rather than by remembering — an adapter
+ *  that handled `block` and `route` and let everything else fall through to execute is exactly
+ *  how an unknown verdict reached a protected action. Version skew (the day the gate learns a
+ *  fourth verdict) is the realistic trigger, and it must never mean "run it". */
+export declare function assertAuthorizeVerdict(auth: unknown, fallbackDecisionId?: string): GateAuth;
 export declare function gateAuthorize(config: GuardConfig, ctx: ApprovalContext): Promise<GateAuth>;
 export declare function gateConfirm(config: GuardConfig, decisionId: string, result: unknown): Promise<void>;
 /** Normalize a resume payload ({verdict} | "approved" | ...) to a verdict string. */
 export declare function verdictFrom(payload: any): string;
 /** Throw the right error for a non-approving verdict; return for approved/auto_approved. */
 export declare function assertVerdict(verdict: string, decisionId: string, reason?: string): void;
+/** Engine versions these adapters are written and tested against. Peer dependencies are
+ *  deliberately NOT declared: declaring them made npm resolve four engine ecosystems into ~211MB
+ *  of cache metadata for every consumer, including the majority who use none of them. The
+ *  compatibility contract lives here instead, and it is CHECKED at bind time — a mismatch names
+ *  the version it found, the range it wants, the beta status and the exact remediation, rather
+ *  than failing somewhere deep in the engine later. */
+export declare const ENGINE_RANGES: Record<string, {
+    pkg: string;
+    min: string;
+    lessThan: string;
+}>;
+/** Warn (never throw — a working integration must not be broken by a version table) when the
+ *  installed engine is outside the tested range. Called by each adapter at bind time. */
+export declare function checkEngineVersion(adapter: keyof typeof ENGINE_RANGES | string): void;

package/dist/adapters/_gate.js

@@ -1,7 +1,20 @@
-import { DecidioBlockedError, DecidioRejectedError, signBoundProof, signConfirm, assertJsonSafe, assertConfirmRecorded, assertSafeTransport } from "../index.js";
+import { createRequire } from "node:module";
+import { DecidioBlockedError, DecidioRejectedError, DecidioHttpError, signBoundProof, signConfirm, assertSafeTransport, carriesCredential, canonicalize, readConfirmResponse, buildConfirmBody } from "../index.js";
+export const AUTHORIZE_VERDICTS = ["proceed", "route", "block"];
+export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
+    const a = auth;
+    const decisionId = typeof a?.decisionId === "string" && a.decisionId ? a.decisionId : fallbackDecisionId;
+    if (!a || !AUTHORIZE_VERDICTS.includes(a.decision)) {
+        throw new DecidioBlockedError(`unrecognised authorization verdict ${JSON.stringify(a?.decision ?? null)} — refusing to execute. The gate answers ${AUTHORIZE_VERDICTS.join(" | ")}; anything else means this SDK version does not understand the decision (upgrade @decidio/sdk), and an answer you do not understand is never permission.`, decisionId);
+    }
+    if (typeof a.decisionId !== "string" || !a.decisionId) {
+        throw new DecidioBlockedError(`the gate answered "${a.decision}" with no usable decisionId (${JSON.stringify(a.decisionId ?? null)}) — refusing to execute. Every authorized action must be addressable: without an id it cannot be polled, resumed, confirmed or audited.`, decisionId);
+    }
+    return a;
+}
 export async function gateAuthorize(config, ctx) {
-    assertJsonSafe(ctx, "describe(...)");
-    assertSafeTransport(config.apiUrl, !!config.apiToken);
+    canonicalize(ctx, "describe(...)");
+    assertSafeTransport(config.apiUrl, carriesCredential(config));
     const f = config.fetchImpl ?? fetch;
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;
     const requesterIdentity = (config.agentKey && config.agentDid)
@@ -16,19 +29,35 @@ export async function gateAuthorize(config, ctx) {
             ...(requesterIdentity ? { requesterIdentity } : {}), ...(resumeUrl ? { resumeUrl } : {}),
         }),
     });
-    if (!res.ok)
-        throw new Error(`decidio /agent/authorize ${res.status}`);
-    return res.json();
+    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, "/agent/authorize", parsed);
+    }
+    return assertAuthorizeVerdict(await res.json(), "unknown");
 }
 export async function gateConfirm(config, decisionId, result) {
     const f = config.fetchImpl ?? fetch;
     try {
-        assertSafeTransport(config.apiUrl, !!config.apiToken);
+        assertSafeTransport(config.apiUrl, carriesCredential(config));
     }
     catch (e) {
         console.warn(`[decidio] confirm failed (action succeeded): ${e.message}`);
         return;
     }
+    let reported = null;
+    let evidenceProblem;
+    try {
+        reported = canonicalize(result ?? null, "result");
+    }
+    catch (e) {
+        evidenceProblem = String(e?.message ?? e);
+        console.warn(`[decidio] ${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 to earn a confirming tier. The action was NOT re-run.`);
+    }
     try {
         const requesterIdentity = signConfirm(decisionId, config);
         if (!requesterIdentity)
@@ -36,13 +65,19 @@ export async function gateConfirm(config, decisionId, result) {
         const res = await f(config.apiUrl.replace(/\/$/, "") + "/agent/confirm", {
             method: "POST",
             headers: { "content-type": "application/json", ...(config.apiToken ? { authorization: `Bearer ${config.apiToken}` } : {}) },
-            body: JSON.stringify({ decisionId, capturedResponse: result ?? null, source: "wrapper", ...(requesterIdentity ? { requesterIdentity } : {}) }),
+            body: JSON.stringify(buildConfirmBody(config, decisionId, reported, requesterIdentity)),
         });
         if (!res.ok) {
             console.warn(`[decidio] confirm returned ${res.status} (action succeeded)`);
             return;
         }
-        assertConfirmRecorded(await res.json().catch(() => null), decisionId, !!requesterIdentity);
+        const ev = readConfirmResponse(await res.json().catch(() => null), { signed: !!requesterIdentity, capturedResponse: reported });
+        if (!ev.reportRecorded)
+            console.warn(`[decidio] ${decisionId}: ${ev.diagnostic}`);
+        else if (!ev.executionConfirmed || ev.executionReportVerified === false)
+            console.warn(`[decidio] execution evidence for ${decisionId} recorded as ${ev.evidenceTier} — ${ev.diagnostic}`);
+        if (evidenceProblem)
+            console.warn(`[decidio] ${decisionId}: the execution IS recorded, but with an empty captured response — see the evidence note above.`);
     }
     catch (e) {
         console.warn(`[decidio] confirm failed (action succeeded): ${e.message}`);
@@ -58,3 +93,35 @@ export function assertVerdict(verdict, decisionId, reason) {
         throw new DecidioRejectedError(reason ?? "rejected by approver", decisionId);
     throw new DecidioBlockedError(reason ?? "not approved", decisionId);
 }
+export const ENGINE_RANGES = {
+    langgraph: { pkg: "@langchain/langgraph", min: "0.2.0", lessThan: "2.0.0" },
+    temporal: { pkg: "@temporalio/workflow", min: "1.0.0", lessThan: "2.0.0" },
+    openai: { pkg: "@openai/agents", min: "0.0.1", lessThan: "2.0.0" },
+    inngest: { pkg: "inngest", min: "3.0.0", lessThan: "4.0.0" },
+};
+const cmp = (a, b) => {
+    const pa = a.split(".").map((n) => parseInt(n, 10) || 0), pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) !== (pb[i] ?? 0))
+            return (pa[i] ?? 0) - (pb[i] ?? 0);
+    }
+    return 0;
+};
+export function checkEngineVersion(adapter) {
+    const spec = ENGINE_RANGES[adapter];
+    if (!spec)
+        return;
+    let found;
+    try {
+        const req = createRequire(import.meta.url);
+        found = req(`${spec.pkg}/package.json`)?.version;
+    }
+    catch { }
+    if (!found)
+        return;
+    if (cmp(found, spec.min) < 0 || cmp(found, spec.lessThan) >= 0) {
+        console.warn(`[decidio] ${spec.pkg} ${found} is outside the range this BETA adapter is tested against (>=${spec.min} <${spec.lessThan}). ` +
+            `The adapter may still work, but nothing verifies it at this version. Remediation: install a supported version ` +
+            `(npm i "${spec.pkg}@>=${spec.min} <${spec.lessThan}"), or use the core guard.protect path, which is not beta and needs no engine.`);
+    }
+}

package/dist/adapters/langgraph.js

@@ -1,6 +1,6 @@
 import { interrupt, Command } from "@langchain/langgraph";
 import { DecidioBlockedError } from "../index.js";
-import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict } from "./_gate.js";
+import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict, checkEngineVersion } from "./_gate.js";
 export async function decidioGate(config, ctx, run) {
     const auth = await gateAuthorize(config, ctx);
     if (auth.decision === "block")
@@ -16,3 +16,4 @@ export async function decidioGate(config, ctx, run) {
 export function decidioResumeCommand(body) {
     return new Command({ resume: { verdict: body.verdict, reason: body.reason } });
 }
+checkEngineVersion("langgraph");

package/dist/adapters/openai.js

@@ -1,4 +1,4 @@
-import { gateAuthorize } from "./_gate.js";
+import { gateAuthorize, checkEngineVersion } from "./_gate.js";
 export async function gateInterruptions(config, state, describe) {
     const resolved = [];
     const pending = [];
@@ -23,3 +23,4 @@ export function applyResume(state, item, verdict) {
     else
         state.reject(item);
 }
+checkEngineVersion("openai");

package/dist/adapters/temporal.js

@@ -1,14 +1,15 @@
 import { condition, defineSignal, setHandler } from "@temporalio/workflow";
 import { DecidioBlockedError } from "../index.js";
-import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict } from "./_gate.js";
+import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict, checkEngineVersion, assertAuthorizeVerdict } from "./_gate.js";
 export const decidioResumeSignal = defineSignal("decidioResume");
 export function installDecidioSignal() {
     const verdicts = new Map();
     setHandler(decidioResumeSignal, (decisionId, verdict, reason) => { verdicts.set(decisionId, { verdict, reason }); });
     return verdicts;
 }
+let confirmWarned = false;
 export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
-    const auth = await (opts.authorize ?? (() => gateAuthorize(config, ctx)))();
+    const auth = assertAuthorizeVerdict(await (opts.authorize ?? (() => gateAuthorize(config, ctx)))(), "unknown");
     if (auth.decision === "block")
         throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
     if (auth.decision === "route") {
@@ -16,7 +17,20 @@ export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
         const v = verdicts.get(auth.decisionId);
         assertVerdict(verdictFrom(v), auth.decisionId, v.reason);
     }
+    else if (auth.decision !== "proceed") {
+        throw new DecidioBlockedError(`unhandled authorization verdict ${JSON.stringify(auth.decision)} — refusing to execute`, auth.decisionId);
+    }
     const result = await run();
-    await (opts.confirm ?? ((id, r) => gateConfirm(config, id, r)))(auth.decisionId, result);
+    if (opts.confirm) {
+        await opts.confirm(auth.decisionId, result);
+        if (!confirmWarned) {
+            confirmWarned = true;
+            console.warn(`[decidio] temporal: a custom \`confirm\` reports through your own activity, so this SDK cannot read back the evidence tier Decidio recorded. Check the record (or return the gate's response body from your activity and validate it with readConfirmResponse) if you need to know whether the execution was CONFIRMED, not merely reported.`);
+        }
+    }
+    else {
+        await gateConfirm(config, auth.decisionId, result);
+    }
     return result;
 }
+checkEngineVersion("temporal");

package/dist/canonical.d.ts

@@ -0,0 +1,18 @@
+/** The value model this SDK transports: exactly what JSON can carry, losslessly. */
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Typed refusal for a value outside the canonical model. `decisionId` is set only when the
+ *  refusal happens after a decision already exists (a direct-park caller). */
+export declare class DecidioUnsafeArgumentsError extends Error {
+    decisionId?: string | undefined;
+    constructor(message: string, decisionId?: string | undefined);
+}
+/** Deep-clone `value` into the canonical model, REFUSING anything that cannot be carried
+ *  losslessly. Returns a fresh structure; the input is never referenced by the result. */
+export declare function canonicalize<T = JsonValue>(value: unknown, path?: string): T;
+export declare function canonicalizeArgs(args: readonly unknown[]): JsonValue[];
+/** RFC 8785-shaped canonical JSON of an already-canonical value — the exact bytes hashed for an
+ *  execution report, so both languages produce the same digest. */
+export declare function canonicalJson(value: JsonValue): string;

package/dist/canonical.js

@@ -0,0 +1,128 @@
+export class DecidioUnsafeArgumentsError extends Error {
+    decisionId;
+    constructor(message, decisionId) {
+        super(message);
+        this.decisionId = decisionId;
+        this.name = "DecidioUnsafeArgumentsError";
+    }
+}
+const NOT_ROUTED = "The decision was NOT routed; nothing reached Decidio.";
+function refuse(path, what, fix) {
+    throw new DecidioUnsafeArgumentsError(`[decidio] ${path} ${what} — the approval payload must be plain JSON so that what a human approves is exactly what executes; ${fix} ${NOT_ROUTED}`);
+}
+function assertNoLoneSurrogate(s, p) {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff) {
+            const n = s.charCodeAt(i + 1);
+            if (n >= 0xdc00 && n <= 0xdfff) {
+                i++;
+                continue;
+            }
+            refuse(p, `contains an unpaired surrogate (U+${c.toString(16).toUpperCase()})`, "it cannot be encoded as UTF-8, so no wire or seal can carry it — repair the string (it is usually a split emoji or truncated UTF-16).");
+        }
+        else if (c >= 0xdc00 && c <= 0xdfff) {
+            refuse(p, `contains an unpaired surrogate (U+${c.toString(16).toUpperCase()})`, "it cannot be encoded as UTF-8, so no wire or seal can carry it — repair the string (it is usually a split emoji or truncated UTF-16).");
+        }
+    }
+}
+export function canonicalize(value, path = "args") {
+    return walk(value, path, new Set());
+}
+function walk(v, p, seen) {
+    if (v === null)
+        return null;
+    const t = typeof v;
+    if (t === "boolean")
+        return v;
+    if (t === "string") {
+        assertNoLoneSurrogate(v, p);
+        return v;
+    }
+    if (t === "number") {
+        const n = v;
+        if (!Number.isFinite(n))
+            refuse(p, `is ${String(n)}`, "a non-finite number becomes null in JSON, so the approver and your function would see different values — pass a finite number or a string.");
+        if (Object.is(n, -0))
+            refuse(p, "is -0", "negative zero is indistinguishable from 0 after serialization — pass 0 if that is what you mean.");
+        return n;
+    }
+    if (t === "undefined")
+        refuse(p, "is undefined", "JSON drops or nullifies it — use null explicitly, or omit the field.");
+    if (t === "bigint")
+        refuse(p, "is a BigInt", "JSON cannot represent it — pass it as a string.");
+    if (t === "function")
+        refuse(p, "is a function", "it cannot be serialized for approval.");
+    if (t === "symbol")
+        refuse(p, "is a symbol", "it cannot be serialized for approval.");
+    const o = v;
+    if (seen.has(o))
+        refuse(p, "is part of a circular structure", "JSON cannot represent cycles — break the cycle or pass an id instead.");
+    seen.add(o);
+    try {
+        const proto = Object.getPrototypeOf(o);
+        if (Array.isArray(v)) {
+            if (proto !== Array.prototype)
+                refuse(p, "is an array subclass", "only plain arrays survive serialization with their behavior intact — pass a plain array.");
+            const arr = v;
+            const keys = Reflect.ownKeys(arr);
+            const expected = arr.length + 1;
+            if (keys.length !== expected) {
+                const extra = keys.filter((k) => k !== "length" && !(typeof k === "string" && /^\d+$/.test(k) && Number(k) < arr.length));
+                if (extra.length)
+                    refuse(`${p}.${String(extra[0])}`, "is an extra property on an array", "JSON serializes arrays by index only, so it would be dropped — move it into an object.");
+                refuse(p, "is a sparse array (it has holes)", "each hole becomes null in JSON — fill the holes or pass a dense array.");
+            }
+            return arr.map((x, i) => walk(x, `${p}[${i}]`, seen));
+        }
+        if (proto !== Object.prototype && proto !== null) {
+            const name = o?.constructor?.name;
+            refuse(p, `is ${name && name !== "Object" ? `a ${name}` : "an exotic object"}`, "only plain JSON objects survive serialization with their meaning intact (a Map becomes {}, a Date becomes a string) — convert it to plain JSON first.");
+        }
+        if (proto === null)
+            refuse(p, "is a null-prototype object", "it round-trips into an ordinary object, changing its kind — pass a plain object.");
+        if (typeof o.toJSON === "function")
+            refuse(p, "defines toJSON()", "its serialized form would differ from the value the approval and signature cover — pass the already-serialized form.");
+        const out = {};
+        for (const key of Reflect.ownKeys(o)) {
+            if (typeof key === "symbol")
+                refuse(p, "has a symbol-keyed property", "JSON drops symbol keys — use string keys.");
+            const d = Object.getOwnPropertyDescriptor(o, key);
+            if (!("value" in d))
+                refuse(`${p}.${key}`, "is a getter/setter", "an accessor is evaluated at serialization time, so the approved value could differ from the executed one — pass a plain data property.");
+            if (!d.enumerable)
+                refuse(`${p}.${key}`, "is a non-enumerable property", "JSON drops it, so the approver would never see it — make it enumerable or remove it.");
+            assertNoLoneSurrogate(key, `${p}.${key}`);
+            Object.defineProperty(out, key, {
+                value: walk(d.value, `${p}.${key}`, seen),
+                writable: true, enumerable: true, configurable: true,
+            });
+        }
+        return out;
+    }
+    finally {
+        seen.delete(o);
+    }
+}
+function deepFreeze(v) {
+    if (v === null || typeof v !== "object")
+        return v;
+    for (const k of Object.keys(v))
+        deepFreeze(v[k]);
+    return Object.freeze(v);
+}
+export function canonicalizeArgs(args) {
+    return args.map((a, i) => deepFreeze(walk(a, `args[${i}]`, new Set())));
+}
+export function canonicalJson(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean" || typeof value === "number")
+        return JSON.stringify(value);
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
+}