@decidio/sdk 0.1.9 → 0.1.11

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

@@ -20,9 +20,14 @@ export interface GuardFacadeConfig {
     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";
+    /** null/"generic" → the core gate; engine adapters (langgraph/openai/temporal/inngest)
+     *  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";
     /** The action name this wrapper produces, declared UP FRONT so the resume registry is populated
@@ -31,18 +36,31 @@ export interface ProtectOptions {
      *  `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). */
+    /** Blocking-mode poll ceiling in ms (default 600000 = 10 min). Set it here so a CI pipeline
+     *  fails fast instead of blocking the full 10-minute default while a routed action waits.
+     *  Accepted identically by the Python SDK (poll_timeout, seconds). */
     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
@@ -63,6 +81,9 @@ export declare class Guard {
         stop: () => void;
     };
     private ensureResume;
+    /** Throws when the facade has no gate URL — at USE time, not import time, so `import { guard }`
+     *  stays safe in envless contexts. */
+    private assertConfigured;
     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"`. */

package/dist/guard.js

@@ -1,19 +1,17 @@
-// 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 {
     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 ?? "http://localhost:4000",
+            apiUrl: process.env.DECIDIO_API_URL ?? "",
             agentId: process.env.DECIDIO_AGENT_ID ?? "agent",
             apiToken: process.env.DECIDIO_API_TOKEN,
             sourceSystem: process.env.DECIDIO_SOURCE_SYSTEM,
@@ -26,39 +24,37 @@ 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);
     }
     ensureResume() {
-        if (!this.resume) {
+        this.assertConfigured();
+        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"),
-                // 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,
             });
         }
-        return this.resume;
+        return this._resume;
+    }
+    assertConfigured() {
+        if (!this.config.apiUrl)
+            throw new Error("[decidio] no gate URL configured — set DECIDIO_API_URL (the hosted sandbox is https://decidio-api.onrender.com) or run `npx @decidio/sdk init`, then start your process with `node --env-file=.env`. Nothing was routed or executed.");
     }
     protect(fn, describe, opts) {
+        this.assertConfigured();
         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 REAL = ["langgraph", "openai", "temporal", "inngest"];
+            if (REAL.includes(opts.adapter)) {
+                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.`);
+            }
+            throw new Error(`[decidio] unknown adapter "${opts.adapter}" — the available engine adapters are ${REAL.map((a) => `"${a}"`).join(", ")} (each via its @decidio/sdk/<name> subpath), or omit the option for the core gate.`);
         }
         const c = this.config;
         const base = {
@@ -67,22 +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.");
-            // 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);
+            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);
         }
-        // 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 });
+        if (opts?.evidence)
+            resume.evidence = opts.evidence;
+        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume }, opts?.evidence ? { evidence: opts.evidence } : undefined);
     }
 }
-/** Preconfigured singleton — `import { guard } from "@decidio/sdk"`. */
 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 } 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". */
@@ -75,15 +80,13 @@ 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. */
+/** A transport failure with GUIDANCE instead of a raw fetch stack. 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`. */
+ *  server says exactly how much and until when — `limit`, `remaining` and `resetAt` relay its
+ *  answer verbatim so automation never has to parse a message. Nothing was routed, recorded,
+ *  or executed; retry after `resetAt`. */
 export declare class DecidioRateLimitError extends Error {
     limit: number | undefined;
     remaining: number | undefined;
@@ -104,4 +107,10 @@ export declare class DecidioNetworkError extends Error {
 /** `<appUrl>/d/<decisionId>` — the deep link that opens this decision directly, on the web app or
  *  the phone build. Null when DECIDIO_APP_URL is not configured, never a half-built URL. */
 export declare function decisionUrl(appUrl: string | undefined, decisionId: string): string | null;
-export declare function withApproval<A extends any[], R>(fn: (...args: A) => Promise<R>, describe: (...args: A) => ApprovalContext, config: GuardConfig): (...args: A) => Promise<R>;
+export declare function withApproval<A extends any[], R>(fn: (...args: A) => Promise<R>, describe: (...args: A) => ApprovalContext, config: GuardConfig, opts?: {
+    /** Map YOUR function's natural return value to the evidence Decidio records. The gate awards
+     *  its strongest wrapper tier (application_confirmed) only for a committed record id plus a
+     *  success indication — this lets a real API keep its own shape instead of being forced into
+     *  magic field names: `evidence: (r) => ({ recordId: r.transactionId, success: r.status === "committed" })`. */
+    evidence?: (result: R) => unknown;
+}): (...args: A) => Promise<R>;

package/dist/index.js

@@ -1,37 +1,14 @@
-// @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";
+import { DecidioSuspendedError } from "./resume.js";
+import { signBoundProof, signConfirm, assertSafeTransport } from "./signing.js";
+import { canonicalize, canonicalizeArgs } from "./canonical.js";
+import { readConfirmResponse, buildConfirmBody } from "./evidence.js";
 export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 export { guard, Guard } from "./guard.js";
-export { generateKeypair, signBoundProof, signConfirm, canonicalize, assertJsonSafe } from "./signing.js";
+export { DecidioHttpError } from "./errors.js";
+import { 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 { readConfirmResponse, buildConfirmBody, describeTierGap, EVIDENCE_TIERS } from "./evidence.js";
 export class DecidioBlockedError extends Error {
     reason;
     decisionId;
@@ -61,15 +38,6 @@ 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;
@@ -88,9 +56,6 @@ 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). `
@@ -115,6 +80,7 @@ async function reach(f, url, op, init) {
 }
 async function post(cfg, path, body) {
     const f = cfg.fetchImpl ?? fetch;
+    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
     const res = await reach(f, cfg.apiUrl.replace(/\/$/, "") + path, `POST ${path}`, {
         method: "POST",
         headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
@@ -124,47 +90,58 @@ async function post(cfg, path, body) {
         const b = await res.json().catch(() => null);
         throw new DecidioRateLimitError(b?.limit, b?.remaining, b?.resetAt, b?.message);
     }
-    if (!res.ok)
-        throw new Error(`decidio ${path} ${res.status}: ${await res.text().catch(() => "")}`);
+    if (!res.ok) {
+        const raw = await res.text().catch(() => "");
+        let parsed = raw;
+        try {
+            parsed = raw ? JSON.parse(raw) : undefined;
+        }
+        catch { }
+        throw new DecidioHttpError(res.status, path, parsed);
+    }
     return res.json();
 }
 async function get(cfg, path) {
     const f = cfg.fetchImpl ?? fetch;
+    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
     const res = await reach(f, cfg.apiUrl.replace(/\/$/, "") + path, `GET ${path}`, {
         headers: { ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
     });
     if (!res.ok)
-        throw new Error(`decidio ${path} ${res.status}`);
+        throw new DecidioHttpError(res.status, path);
     return res.json();
 }
-/**
- * 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;
     return `${appUrl.replace(/\/$/, "")}/d/${encodeURIComponent(decisionId)}`;
 }
-export function withApproval(fn, describe, config) {
+export function withApproval(fn, describe, config, opts) {
     const pollInterval = config.pollIntervalMs ?? 2_000;
     const pollTimeout = config.pollTimeoutMs ?? 600_000;
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;
-    return async (...args) => {
-        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.
+    return async (...rawArgs) => {
+        const args = canonicalizeArgs(rawArgs);
+        let ctx;
+        try {
+            ctx = describe(...args);
+        }
+        catch (e) {
+            if (e instanceof TypeError && /read only|not extensible|object is not extensible|frozen/i.test(e.message ?? "")) {
+                throw new TypeError(`[decidio] your describe() callback tried to MODIFY the call arguments (${e.message}). ` +
+                    `Those arguments are the approved value: they are what a human sees, what the signature covers, ` +
+                    `what is parked for a durable resume, and what your function ultimately runs on — so changing them ` +
+                    `here would mean the action that executes is not the action that was approved. Read from the ` +
+                    `arguments and RETURN the context instead: (inv) => ({ action: "pay", amount: inv.amount }). ` +
+                    `If you need a modified value at execution time, compute it inside your function. ` +
+                    `Nothing was routed or executed.`);
+            }
+            throw e;
+        }
         const 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(...)");
+        canonicalize(ctx, "describe(...)");
         const auth = await post(config, "/agent/authorize", {
             requester: config.agentId, action: ctx.action, amount: ctx.amount,
             scope: ctx.scope, sourceSystem: config.sourceSystem,
@@ -172,52 +149,28 @@ 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.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")
@@ -227,42 +180,25 @@ 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);
-            const confirmBody = await post(config, "/agent/confirm", {
-                decisionId: auth.decisionId,
-                capturedResponse: result ?? null,
-                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.`);
+            const evidenceOf = (opts?.evidence ?? ((r) => r));
+            const reported = canonicalize(evidenceOf(result) ?? null, "evidence(result)");
+            const confirmBody = await post(config, "/agent/confirm", buildConfirmBody(config, auth.decisionId, reported, confirmIdentity));
+            const ev = readConfirmResponse(confirmBody, { signed: !!confirmIdentity, capturedResponse: reported });
+            if (!ev.reportRecorded)
+                console.warn(`[decidio] ${auth.decisionId}: ${ev.diagnostic}`);
+            else if (!ev.executionConfirmed)
+                console.warn(`[decidio] execution evidence for ${auth.decisionId} recorded as ${ev.evidenceTier} — ${ev.diagnostic}`);
         }
         catch (e) {
-            // surface but don't throw — the action already happened
             console.warn(`[decidio] confirmation post failed (action succeeded): ${e.message}`);
         }
         return result;