@decidio/sdk 0.1.11 → 0.2.0

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 import type { ResumeController } from "./resume.js";
+import { type EvidenceOutcome } from "./evidence.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 { DecidioHttpError } from "./errors.js";
-export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport } from "./signing.js";
+export { DecidioHttpError, decisionIdProblem } from "./errors.js";
+export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential } from "./signing.js";
 export { canonicalize, canonicalizeArgs, canonicalJson, DecidioUnsafeArgumentsError } from "./canonical.js";
 export type { JsonValue, JsonPrimitive } from "./canonical.js";
 export { readConfirmResponse, buildConfirmBody, describeTierGap, EVIDENCE_TIERS } from "./evidence.js";
@@ -107,10 +108,34 @@ 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;
+/** What a protected call returns in 0.2.0: your function's value, the decision it was authorized
+ *  under, and what Decidio actually recorded about the execution.
+ *
+ *  Through 0.1.x this was just `R`. The SDK computed the full confirmation outcome — tier, whether
+ *  the report was recorded, whether the signed execution report verified, whether the evidence
+ *  mapper failed — and then dropped it on the floor, surfacing it only as a console warning. For a
+ *  product whose value IS the record, the one thing a caller could not do was find out what got
+ *  recorded. Returning it makes "my action ran but was logged as an unproven assertion" something
+ *  code can branch on instead of something a human might notice in a log.
+ *
+ *  `protectBestEffort` keeps the old value-only shape for callers that genuinely do not care. */
+export interface ProtectedExecution<R> {
+    /** Exactly what your function returned — unchanged, uncanonicalized, your object. */
+    value: R;
+    /** The decision this execution was authorized under. Use it as your downstream idempotency key. */
+    decisionId: string;
+    /** What Decidio recorded. `reportRecorded` false means the execution happened and Decidio does
+     *  NOT know; `executionConfirmed` false means it knows but could not attest a commit. */
+    confirmation: EvidenceOutcome;
+}
 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>;
+    /** Hand the action an `ExecutionContext` as its FIRST argument: `{ decisionId, attemptId,
+     *  idempotencyKey }`. Opt-in, never inferred from the function's arity — guessing wrong means
+     *  passing a context object as someone's first business argument. */
+    withContext?: boolean;
+}): (...args: A) => Promise<ProtectedExecution<R>>;

package/dist/index.js

@@ -1,12 +1,12 @@
 import { DecidioSuspendedError } from "./resume.js";
-import { signBoundProof, signConfirm, assertSafeTransport } from "./signing.js";
+import { signBoundProof, signConfirm, assertSafeTransport, carriesCredential } from "./signing.js";
 import { canonicalize, canonicalizeArgs } from "./canonical.js";
 import { readConfirmResponse, buildConfirmBody } from "./evidence.js";
 export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 export { guard, Guard } from "./guard.js";
-export { DecidioHttpError } from "./errors.js";
-import { DecidioHttpError } from "./errors.js";
-export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport } from "./signing.js";
+export { DecidioHttpError, decisionIdProblem } from "./errors.js";
+import { DecidioHttpError, decisionIdProblem } from "./errors.js";
+export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential } from "./signing.js";
 export { canonicalize, canonicalizeArgs, canonicalJson, DecidioUnsafeArgumentsError } from "./canonical.js";
 export { readConfirmResponse, buildConfirmBody, describeTierGap, EVIDENCE_TIERS } from "./evidence.js";
 export class DecidioBlockedError extends Error {
@@ -80,7 +80,7 @@ async function reach(f, url, op, init) {
 }
 async function post(cfg, path, body) {
     const f = cfg.fetchImpl ?? fetch;
-    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
+    assertSafeTransport(cfg.apiUrl, carriesCredential(cfg));
     const res = await reach(f, cfg.apiUrl.replace(/\/$/, "") + path, `POST ${path}`, {
         method: "POST",
         headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
@@ -103,7 +103,7 @@ async function post(cfg, path, body) {
 }
 async function get(cfg, path) {
     const f = cfg.fetchImpl ?? fetch;
-    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
+    assertSafeTransport(cfg.apiUrl, carriesCredential(cfg));
     const res = await reach(f, cfg.apiUrl.replace(/\/$/, "") + path, `GET ${path}`, {
         headers: { ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
     });
@@ -142,6 +142,12 @@ export function withApproval(fn, describe, config, opts) {
             ? signBoundProof(config.agentKey, { agentId: config.agentId, did: config.agentDid, action: ctx.action, amount: ctx.amount, scope: ctx.scope, workspaceId: config.workspaceId })
             : undefined;
         canonicalize(ctx, "describe(...)");
+        if (typeof ctx?.action !== "string" || ctx.action.trim().length === 0) {
+            throw new Error(`[decidio] describe(...) must return an \`action\` string naming what is being asked (got ${JSON.stringify(ctx?.action ?? null)}). Nothing was routed or executed.`);
+        }
+        if (typeof ctx.amount !== "number" || !Number.isFinite(ctx.amount) || ctx.amount < 0) {
+            throw new Error(`[decidio] describe(...) must return a finite, non-negative \`amount\` — the policy decides on it, so a request without one is not a request Decidio can rule on (got ${JSON.stringify(ctx.amount ?? null)}). Use 0 for an action with no monetary value. Nothing was routed or executed.`);
+        }
         const auth = await post(config, "/agent/authorize", {
             requester: config.agentId, action: ctx.action, amount: ctx.amount,
             scope: ctx.scope, sourceSystem: config.sourceSystem,
@@ -151,6 +157,9 @@ export function withApproval(fn, describe, config, opts) {
         });
         if (auth.decision !== "proceed" && auth.decision !== "route" && auth.decision !== "block")
             throw new DecidioBlockedError(`unrecognized gate verdict: ${String(auth.decision)}`, auth.decisionId);
+        const idProblem = decisionIdProblem(auth.decisionId);
+        if (idProblem)
+            throw new DecidioBlockedError(`the gate answered "${auth.decision}" with no usable decisionId (${JSON.stringify(auth.decisionId ?? null)} — ${idProblem}) — refusing to execute. Every authorized action must be addressable: without an id it cannot be polled, resumed, confirmed or audited.`, typeof auth.decisionId === "string" ? auth.decisionId : String(auth.decisionId ?? ""));
         if (auth.decision === "block")
             throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
         if (auth.decision === "route") {
@@ -163,7 +172,7 @@ export function withApproval(fn, describe, config, opts) {
                 config.resume.agentId ??= config.agentId;
                 config.resume.agentKey ??= config.agentKey;
                 config.resume.agentDid ??= config.agentDid;
-                config.resume.register(ctx.action, fn);
+                config.resume.register(ctx.action, fn, opts?.evidence);
                 await config.resume.park({
                     decisionId: auth.decisionId, receiptId: auth.receiptId,
                     action: ctx.action, amount: ctx.amount, scope: ctx.scope, args,
@@ -186,21 +195,44 @@ export function withApproval(fn, describe, config, opts) {
                 await sleep(pollInterval);
             }
         }
-        const result = await fn(...args);
+        const result = opts?.withContext
+            ? await fn({ decisionId: auth.decisionId, attemptId: null, idempotencyKey: auth.decisionId }, ...args)
+            : await fn(...args);
+        let reported = null;
+        let evidenceProblem;
         try {
-            const confirmIdentity = signConfirm(auth.decisionId, config);
             const evidenceOf = (opts?.evidence ?? ((r) => r));
-            const reported = canonicalize(evidenceOf(result) ?? null, "evidence(result)");
+            reported = canonicalize(evidenceOf(result) ?? null, "evidence(result)");
+        }
+        catch (e) {
+            evidenceProblem = String(e?.message ?? e);
+            console.warn(`[decidio] ${auth.decisionId}: the action SUCCEEDED but its result could not be reported as evidence (${evidenceProblem}). Reporting an empty captured response so the execution is still recorded — map the return value with the \`evidence\` option (e.g. evidence: (r) => ({ recordId: String(r.id), success: true })) to earn a confirming tier. The action was NOT re-run.`);
+        }
+        let confirmation;
+        try {
+            const confirmIdentity = signConfirm(auth.decisionId, config);
             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}`);
+            confirmation = readConfirmResponse(confirmBody, { signed: !!confirmIdentity, capturedResponse: reported, journalled: false });
+            if (!confirmation.reportRecorded)
+                console.warn(`[decidio] ${auth.decisionId}: ${confirmation.diagnostic}`);
+            else if (!confirmation.executionConfirmed || confirmation.executionReportVerified === false)
+                console.warn(`[decidio] execution evidence for ${auth.decisionId} recorded as ${confirmation.evidenceTier} — ${confirmation.diagnostic}`);
+            if (evidenceProblem)
+                console.warn(`[decidio] ${auth.decisionId}: the execution IS recorded, but with an empty captured response — see the evidence note above.`);
         }
         catch (e) {
-            console.warn(`[decidio] confirmation post failed (action succeeded): ${e.message}`);
+            const isHttp = e instanceof DecidioHttpError;
+            console.warn(`[decidio] confirmation post failed (action succeeded): ${e?.message ?? e}`);
+            confirmation = {
+                reportRecorded: false,
+                executionConfirmed: false,
+                confirmationRetryable: isHttp ? e.retryable : true,
+                reportJournalled: false,
+                diagnostic: `your action RAN and Decidio does NOT have its execution report (${e?.message ?? e}). This path journals nothing, so there is no local copy to re-send: record the outcome from your own system. Durable mode DOES journal reports, and its recovery path can re-send them — that is the mode to use if this matters to you. Do NOT re-run the action.`,
+            };
         }
-        return result;
+        if (evidenceProblem)
+            confirmation.evidenceError = evidenceProblem;
+        return { value: result, decisionId: auth.decisionId, confirmation };
     };
 }

package/dist/inngest.d.ts

@@ -45,6 +45,10 @@ export declare function decidioGateStep<R>(args: {
     ctx: ApprovalContext;
     run: () => Promise<R>;
     timeout?: string;
+    /** Map your action's return value to the evidence Decidio records — the same option the core
+     *  path takes. This door's own confirm chokepoint tells callers to use it; until 0.2.0 no
+     *  adapter door accepted one, so the advice was unfollowable everywhere it was printed. */
+    evidence?: (result: R) => unknown;
 }): Promise<GateStepOutcome<R>>;
 /**
  * Decidio → Inngest bridge. Mount as an HTTP endpoint and register it as the agent's

package/dist/inngest.js

@@ -22,7 +22,7 @@ export async function decidioGateStep(args) {
             return { status: "blocked", decisionId: auth.decisionId };
     }
     const result = await step.run("agent-action", args.run);
-    await step.run("decidio-confirm", async () => { await gateConfirm(config, auth.decisionId, result); return true; });
+    await step.run("decidio-confirm", async () => { await gateConfirm(config, auth.decisionId, result, args.evidence); return true; });
     return { status: "executed", decisionId: auth.decisionId, result };
 }
 export function createInngestResumeBridge(opts) {