@decidio/sdk 0.2.2 → 0.3.0

package/README.md

@@ -2,6 +2,8 @@
 
 One line to put a human-or-policy approval gate in front of any AI-agent action — and get a signed, verifiable Authority Receipt for every decision, with execution evidence accruing on the record.
 
+`@decidio/sdk` is the client for Decidio — the system of record for enterprise authority, from OmniTwin Technologies.
+
 ## The two-minute tour
 
 ```bash
@@ -21,15 +23,17 @@ prints the approve command and exits rather than approve its own request (CI can
 
 ## Quickstart — seven steps to your first sealed receipt
 
-Under 30 minutes, no help needed. You'll need Node 20.6+, a terminal, and a Decidio workspace
-(request one at [decidioai.com](https://decidioai.com/#early-access) — the hosted sandbox is
-synthetic data, safe to experiment in — and it is ONE SHARED workspace: workspace-wide views
-like `tokens list` or `approvals` show every lab member's agents and decisions there, which is
-the shared-lab boundary working as designed; production workspaces are per-tenant). Lab
-workspaces have a **governed-action allowance**
-(currently 30 actions/hour); hitting it raises a typed `DecidioRateLimitError` naming the limit
-and reset time — nothing is routed or executed — and `tokens list` shows your remaining
-allowance any time.
+Under 30 minutes, no help needed. You'll need Node 20.6+ and a terminal.
+
+**You'll need a Decidio workspace.** → Request one at [decidioai.com](https://decidioai.com/#early-access)
+
+The hosted sandbox is synthetic data, safe to experiment in. Note it is ONE SHARED workspace:
+workspace-wide views like `tokens list` or `approvals` show every lab member's agents and
+decisions — the shared-lab boundary working as designed. Production workspaces are per-tenant.
+
+Lab workspaces have a **governed-action allowance** (currently 30 actions/hour); hitting it raises
+a typed `DecidioRateLimitError` naming the limit and reset time — nothing is routed or executed —
+and `tokens list` shows your remaining allowance any time.
 
 **PowerShell users** — the equivalents for every Bash idiom used below:
 
@@ -382,10 +386,30 @@ 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
+// "indeterminate"       → no outcome was recorded; check downstream, then reconcile. Never blind-retry
 // "parked"              → still waiting on a human; nothing has executed
 ```
 
+Two things `reconcile()` will refuse, because both would undo an authority decision rather than
+record one. **It refuses by returning, not by throwing** — check `reportRecorded`, and read
+`diagnostic` to see why:
+
+```js
+// A denial is final. There is no outcome to record — nothing ran — so neither outcome is accepted.
+const r = await guard.resume.reconcile(deniedId, { outcome: "not_committed" });
+r.reportRecorded;   // false — r.diagnostic says the decision was DENIED
+
+// A decision that is still `invoking` may be running the action at this moment. Releasing it would
+// let a second worker run the same approved action, so it takes an explicit assertion — from you,
+// after you have checked. Nothing here can see another machine's process table, so this is your
+// judgement, and it is stamped into the ledger as such.
+await guard.resume.reconcile(id, { outcome: "not_committed", reason: "…" });   // refused while invoking
+await guard.resume.reconcile(id, { outcome: "not_committed", reason: "…", workerStopped: true });  // released
+```
+
+`indeterminate` needs no such flag: the handler has already returned or thrown, so nothing is in
+flight — only the downstream result is unknown.
+
 The report a worker sends is written to the pending store's execution ledger *before* the first
 send attempt, so a lost confirmation is recoverable; and because that record holds no handler
 binding, replaying it can only re-send evidence — never re-run your function. The ledger lives in
@@ -420,6 +444,53 @@ 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.
 
+
+## Upgrading from 0.2.x to 0.3.0
+
+0.3.0 is a breaking release. Every item below changes behaviour a 0.2.x caller may depend on, so
+none of it is left to be discovered at runtime.
+
+**If you wrote a custom `PendingStore`, it will fail to construct.** `markDiscarded(decisionId,
+verdict, reason?)` is now REQUIRED — it writes the tombstone that makes a denied decision
+permanently unclaimable, and a store that cannot record a denial cannot uphold the guarantee, so
+this is refused at construction rather than deep inside a resolve. `delete` also takes an optional
+owning attempt (`delete(id, attemptId?)`) so a superseded attempt cannot clean up the live one's
+payload, and `settle` takes `workerStopped`. The shipped stores show the shape, and
+`packages/conformance/vectors/ownership.json` is the corpus your store should pass.
+
+**`recover()` now throws instead of returning `[]`** when the ledger cannot be read
+(`DecidioRecoveryUnavailableError`). `[]` and "I cannot tell you what you owe" are the same value
+to a caller and mean opposite things, so a script reading `if (!(await recover()).length)` treated
+a permissions change as proof that nothing was outstanding. Wrap the call if you poll it.
+
+**`reconcile()` refuses two things it used to allow.** A DENIED decision cannot be reconciled on
+either outcome, and releasing a decision that is still `invoking` takes an explicit
+`workerStopped: true` — that is the one state where the handler may be running right now, and
+releasing it hands one approved action to two live workers. It refuses by RETURNING, not throwing:
+check `reportRecorded` and read `diagnostic`.
+
+**The adapters return a different shape.** `decidioGate` (LangGraph, Temporal) returns
+`ProtectedExecution` — `{ value, decisionId, confirmation }` — instead of the bare value.
+`decidioGateStep` (Inngest) renames `result` to `value` and carries `confirmation`.
+`gateInterruptions` is now `authorizeInterruptions` and returns `confirmationSupported: false`
+(the old name remains as a deprecated alias). Read `.value` where you previously read the result.
+
+**The transport rule refuses URLs it used to accept.** A gate URL must now be absolute and either
+https or an exact loopback host, whatever credentials the config holds. A relative or scheme-less
+`apiUrl` throws at startup — it used to pass on the reasoning that the shipped transport rejects
+it, which says nothing about a custom `fetchImpl`.
+
+**Decision ids are shape-checked.** Letters, digits, dot, dash and underscore, starting with a
+letter or digit, at most 128 characters, never trimmed. The server enforces the same grammar (it
+had none before 0.3.0, which is why the SDK was the stricter of the two). Ids Decidio issues are
+well inside it.
+
+**`/agent/confirm` can answer 409.** `TERMINALLY_DENIED` means a human refused the decision and
+your action appears to have run anyway; `NOT_AUTHORIZED` means there is no approved, sealed
+decision for evidence to attach to. Neither is a report failure and neither is retryable — the SDK
+raises `DecidioHttpError` with advice that says so, rather than the "only its report failed" note
+that fits every other confirm error.
+
 ## Engine adapters (BETA) — and Python too
 
 - **Engine adapters are BETA.** They share the core's gate semantics — the verdict allow-list,
@@ -430,6 +501,17 @@ for engines you don't. Each adapter's shipped `.d.ts` header documents its wirin
   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.
+- **One result shape on every door (0.3.0, breaking).** `decidioGate` (LangGraph, Temporal) and
+  `decidioGateStep` (Inngest) now return `{ value, decisionId, confirmation }` — the same
+  `ProtectedExecution` the core path returns. They used to hand back the bare value and discard what
+  Decidio recorded, so "it ran and was recorded" and "it ran and Decidio does not know" were the
+  same return value to a caller. Inngest keeps its `status`, because its durable path can end in
+  `rejected` or `blocked` without ever calling your action; its value field is `value`, not
+  `result`.
+  The OpenAI door is the exception and now says so: it was renamed `gateInterruptions` →
+  `authorizeInterruptions` and returns `confirmationSupported: false`. The OpenAI runtime executes
+  the tool itself, so this SDK never sees the return value and has nothing to attest — and an
+  ABSENT confirmation must not look like a failed one. The old name remains as a deprecated alias.
 - **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
@@ -495,3 +577,12 @@ your queue.
 - **Confirmation integrity:** the wrapper runs in your process, so it captures the genuine API response — a materially stronger signal than an agent self-report, but it trusts the host. For high-assurance, Decidio can *independently* read the source back (`independently_reconciled`) where it holds a read connection.
 - **Zero-code alternative:** an agent that speaks MCP (e.g. Claude on the web) can reach the same gate via Decidio's `request_approval` MCP tool with no code at all.
 - **API surface:** the agent-gate REST contract this SDK speaks is described in [`openapi.yaml`](./openapi.yaml), shipped in the package.
+
+## Using this for real?
+
+The hosted sandbox is synthetic and shared. Production workspaces are per-tenant, with your own
+issuer key and receipts that verify offline against it.
+
+[decidioai.com](https://decidioai.com) · [Developer docs](https://decidioai.com/developers/) · [Request access](https://decidioai.com/#early-access)
+
+Built by OmniTwin Technologies.

package/dist/adapters/langgraph.d.ts

@@ -1,5 +1,5 @@
 import { Command } from "@langchain/langgraph";
-import { type GuardConfig, type ApprovalContext } from "../index.js";
+import { type GuardConfig, type ApprovalContext, type ProtectedExecution } from "../index.js";
 /**
  * @decidio/sdk/langgraph — durable suspend via LangGraph's native `interrupt()`.
  * `interrupt` finds the running graph itself (no handle needed), so the gate drops into
@@ -13,7 +13,7 @@ import { type GuardConfig, type ApprovalContext } from "../index.js";
 /** Gate `run()` behind Decidio inside a LangGraph node. */
 export declare function decidioGate<R>(config: GuardConfig, ctx: ApprovalContext, run: () => Promise<R>, opts?: {
     evidence?: (r: R) => unknown;
-}): Promise<R>;
+}): Promise<ProtectedExecution<R>>;
 /** Translate Decidio's signed resume webhook into the LangGraph resume Command. The host
  *  maps decisionId → thread_id and passes this to graph.invoke/stream. */
 export declare function decidioResumeCommand(body: {

package/dist/adapters/langgraph.js

@@ -10,8 +10,8 @@ export async function decidioGate(config, ctx, run, opts) {
         assertVerdict(verdictFrom(resumed), auth.decisionId, resumed?.reason);
     }
     const result = await run();
-    await gateConfirm(config, auth.decisionId, result, opts?.evidence);
-    return result;
+    const confirmation = await gateConfirm(config, auth.decisionId, result, opts?.evidence);
+    return { value: result, decisionId: auth.decisionId, confirmation };
 }
 export function decidioResumeCommand(body) {
     return new Command({ resume: { verdict: body.verdict, reason: body.reason } });

package/dist/adapters/openai.d.ts

@@ -34,13 +34,23 @@ export interface Pending {
     item: ToolApprovalItem;
     decisionId: string;
 }
-/** Ask Decidio for each pending tool-approval on a RunState.
- *  proceed → state.approve(item); block → state.reject(item); route → pending (a human
- *  decides via Decidio; the host parks state.toString() + resumes via applyResume). */
-export declare function gateInterruptions(config: GuardConfig, state: RunStateLike, describe: (item: ToolApprovalItem) => ApprovalContext): Promise<{
+/** THIS DOOR AUTHORIZES; IT DOES NOT CONFIRM. Named `gateInterruptions` it looked like the other
+ *  `decidioGate*` functions, which all run the action and report what happened. This one cannot:
+ *  the OpenAI Agents runtime executes the tool itself, so the SDK never sees the return value and
+ *  has nothing to attest. Every other adapter now returns a `confirmation`; this one deliberately
+ *  returns `confirmationSupported: false` instead of an empty one, because an absent confirmation
+ *  and a failed confirmation must not look alike.
+ *
+ *  proceed → state.approve(item); block → state.reject(item); route → pending (a human decides via
+ *  Decidio; the host parks state.toString() + resumes via applyResume). */
+export declare function authorizeInterruptions(config: GuardConfig, state: RunStateLike, describe: (item: ToolApprovalItem) => ApprovalContext): Promise<{
     resolved: Resolved[];
     pending: Pending[];
+    confirmationSupported: false;
 }>;
+/** @deprecated Renamed to `authorizeInterruptions` in 0.3.0 — the old name read like the other
+ *  `decidioGate*` doors, which execute and confirm. This one only ever authorized. */
+export declare const gateInterruptions: typeof authorizeInterruptions;
 /** Apply a Decidio verdict to a resumed RunState (after RunState.fromString).
  *
  *  VALIDATES BEFORE MUTATING. `else state.reject(item)` treated every unrecognised string as a

package/dist/adapters/openai.js

@@ -1,6 +1,6 @@
 import { gateAuthorize, checkEngineVersion } from "./_gate.js";
 import { DecidioBlockedError } from "../index.js";
-export async function gateInterruptions(config, state, describe) {
+export async function authorizeInterruptions(config, state, describe) {
     const resolved = [];
     const pending = [];
     for (const item of state.getInterruptions()) {
@@ -18,8 +18,9 @@ export async function gateInterruptions(config, state, describe) {
         else
             throw new DecidioBlockedError(`unhandled authorization verdict ${JSON.stringify(auth.decision)}`, auth.decisionId);
     }
-    return { resolved, pending };
+    return { resolved, pending, confirmationSupported: false };
 }
+export const gateInterruptions = authorizeInterruptions;
 export function applyResume(state, item, verdict) {
     if (verdict === "approved" || verdict === "auto_approved") {
         state.approve(item);

package/dist/adapters/temporal.d.ts

@@ -1,4 +1,4 @@
-import { type GuardConfig, type ApprovalContext } from "../index.js";
+import { type GuardConfig, type ApprovalContext, type ProtectedExecution } from "../index.js";
 import { type GateAuth } from "./_gate.js";
 /**
  * @decidio/sdk/temporal — durable suspend via Temporal's native `condition()` + a
@@ -32,4 +32,4 @@ export interface DecidioGateOpts<R = unknown> {
 export declare function decidioGate<R>(config: GuardConfig, ctx: ApprovalContext, run: () => Promise<R>, verdicts: Map<string, {
     verdict: string;
     reason?: string;
-}>, opts?: DecidioGateOpts<R>): Promise<R>;
+}>, opts?: DecidioGateOpts<R>): Promise<ProtectedExecution<R>>;

package/dist/adapters/temporal.js

@@ -21,18 +21,23 @@ export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
         throw new DecidioBlockedError(`unhandled authorization verdict ${JSON.stringify(auth.decision)} — refusing to execute`, auth.decisionId);
     }
     const result = await run();
+    let confirmation;
     if (opts.confirm) {
         if (opts.evidence)
             console.warn("[decidio] temporal: `evidence` is ignored when you supply `confirm` — your callback owns the report, so map the result inside it. Remove one of the two to make the intent clear.");
         await opts.confirm(auth.decisionId, result);
+        confirmation = {
+            reportRecorded: false, executionConfirmed: false, confirmationRetryable: false, reportJournalled: false,
+            diagnostic: "your own `confirm` callback reported this execution, so this SDK cannot read back what Decidio recorded. Check the record, or return the gate's response body from your activity and validate it with readConfirmResponse.",
+        };
         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, opts?.evidence);
+        confirmation = await gateConfirm(config, auth.decisionId, result, opts?.evidence);
     }
-    return result;
+    return { value: result, decisionId: auth.decisionId, confirmation };
 }
 checkEngineVersion("temporal");

package/dist/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync, rmSync } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { userInfo } from "node:os";
 import { createServer } from "node:http";
 import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline";
 import { createRequire } from "node:module";
 import { generateKeypair, assertSafeTransport } from "./signing.js";
+import { hardenFile } from "./resume.js";
 import { withApproval, DecidioRateLimitError, didFromPrivateKey } from "./index.js";
 import { verifyReceipt, runVerify } from "@decidio/verify";
 const VERSION = (() => {
@@ -39,6 +39,14 @@ function readEnvFile() {
     return out;
 }
 const OFFLINE_CMD = ["verify", "--version", "-v", "-V", "version", "--help", "-h", "help", undefined].includes(process.argv[2]);
+if (!OFFLINE_CMD) {
+    readEnvFile();
+    if (envUnreadable) {
+        console.error(`✘ .env exists here but could not be read, so this command cannot know what is already configured in this directory.`);
+        console.error(`  Treating it as empty would risk overwriting an agent key that cannot be recovered. Fix the file's permissions (or move it aside) and run the command again. Nothing was changed.`);
+        process.exit(1);
+    }
+}
 if (!OFFLINE_CMD)
     for (const [k, v] of Object.entries(readEnvFile())) {
         if (k === "DECIDIO_SESSION_TOKEN") {
@@ -106,21 +114,9 @@ function writeSecretFile(path, body) {
         chmodSync(path, 0o600);
     }
     catch { }
-    if (process.platform === "win32") {
-        try {
-            execFileSync("icacls", [path, "/inheritance:r", "/grant:r", `${effectiveUser()}:F`], { stdio: "ignore" });
-        }
-        catch {
-            console.warn(`⚠ could not restrict ${path} to owner-only on this Windows volume — it keeps the directory's inherited permissions. For production, move these values to a secret manager.`);
-        }
-    }
-}
-function effectiveUser() {
-    try {
-        return userInfo().username;
-    }
-    catch {
-        return process.env.USERNAME ?? process.env.USER ?? "";
+    const why = hardenFile(path);
+    if (why) {
+        console.warn(`⚠ could not restrict ${path} to owner-only on this Windows volume (${why}) — it keeps the directory's inherited permissions. For production, move these values to a secret manager.`);
     }
 }
 function upsertEnv(updates) {
@@ -720,8 +716,11 @@ async function cmdQuickstart(opts = {}) {
                     const rv = await api(`/api/workspace/agent-token/${encodeURIComponent(prevJti)}`, { method: "DELETE" }, session);
                     if (rv.status >= 200 && rv.status < 300)
                         log(`  ✔ the previous tour agent (${prevId}) had its token REVOKED before this tour replaced it — no live credential is left behind`);
-                    else
-                        log(`  ⚠ could not revoke the previous tour's token (jti ${prevJti}, ${rv.status}) — revoke it by hand: npx @decidio/sdk tokens revoke ${prevJti}`);
+                    else {
+                        const carried = [...(prev.match(/^DECIDIO_ORPHANED_TOKEN_JTI=(.+)$/m)?.[1] ?? "").split(",").filter(Boolean), prevJti];
+                        envOut.DECIDIO_ORPHANED_TOKEN_JTI = [...new Set(carried)].join(",");
+                        log(`  ⚠ could not revoke the previous tour's token (jti ${prevJti}, ${rv.status}) — it is still LIVE. Its id is kept in ${envFile} as DECIDIO_ORPHANED_TOKEN_JTI, and \`quickstart cleanup\` will retry it; or revoke it by hand: npx @decidio/sdk tokens revoke ${prevJti}`);
+                    }
                 }
                 else {
                     log(`  ⚠ the previous tour file carried no revocation id, so its token (if any) must be revoked from your Decidio app.`);
@@ -859,6 +858,7 @@ async function cmdQuickstart(opts = {}) {
     log(`  // production is DURABLE mode (default) + one worker: guard.worker();  // README has the full pattern`);
     log("");
     log(`Your workspace + queue: ${API.replace("decidio-api.onrender.com", "app.decidioai.com")}  ·  Next: the README's 7-step quickstart (durable, workers, adapters).`);
+    log(`Built by OmniTwin — decidioai.com  ·  Putting this in front of real approvals? decidioai.com/#early-access`);
     let doCleanup = false;
     if (interactive) {
         const answer = await ask(`\nKeep this agent for development? [Enter = keep · c + Enter = clean up now]: `);
@@ -884,6 +884,23 @@ async function quickstartCleanup(session, envFile) {
             }
         return out;
     })();
+    const orphans = (env.DECIDIO_ORPHANED_TOKEN_JTI ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    const stillOrphaned = [];
+    for (const jti of orphans) {
+        const rv = await api(`/api/workspace/agent-token/${encodeURIComponent(jti)}`, { method: "DELETE" }, session);
+        if (rv.status >= 200 && rv.status < 300)
+            log(`  ✔ orphaned token revoked (jti ${jti}) — it had survived an earlier replace`);
+        else {
+            stillOrphaned.push(jti);
+            err(`  ⚠ orphaned token ${jti} could NOT be revoked (${rv.status}) — it is still live.`);
+        }
+    }
+    if (stillOrphaned.length) {
+        err(`✘ ${stillOrphaned.length} orphaned token(s) are STILL LIVE and could not be revoked. Nothing was deleted; ${envFile} keeps their ids so you can retry:`);
+        for (const jti of stillOrphaned)
+            err(`    npx @decidio/sdk tokens revoke ${jti}`);
+        return 1;
+    }
     if (env.DECIDIO_TOKEN_JTI) {
         const rev = await api(`/api/workspace/agent-token/${encodeURIComponent(env.DECIDIO_TOKEN_JTI)}`, { method: "DELETE" }, session);
         if (rev.status >= 200 && rev.status < 300 && rev.body?.changed === false)
@@ -906,7 +923,7 @@ async function quickstartCleanup(session, envFile) {
         return 1;
     }
     if (existsSync(envFile)) {
-        const TOUR_KEYS = new Set(["DECIDIO_API_URL", "DECIDIO_AGENT_ID", "DECIDIO_AGENT_DID", "DECIDIO_AGENT_KEY", "DECIDIO_API_TOKEN", "DECIDIO_WORKSPACE_ID", "DECIDIO_TOKEN_JTI"]);
+        const TOUR_KEYS = new Set(["DECIDIO_API_URL", "DECIDIO_AGENT_ID", "DECIDIO_AGENT_DID", "DECIDIO_AGENT_KEY", "DECIDIO_API_TOKEN", "DECIDIO_WORKSPACE_ID", "DECIDIO_TOKEN_JTI", "DECIDIO_ORPHANED_TOKEN_JTI"]);
         const kept = readFileSync(envFile, "utf8").split(/\r?\n/).filter((line) => {
             const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)=/);
             return m ? !TOUR_KEYS.has(m[1]) : line.trim() !== "";

package/dist/errors.js

@@ -1,6 +1,12 @@
 const RETRYABLE_STATUS = (status) => status === 408 || status === 429 || (status >= 500 && status !== 501);
-function sideEffectNote(endpoint) {
+function sideEffectNote(endpoint, code) {
     if (endpoint.startsWith("/agent/confirm")) {
+        if (code === "TERMINALLY_DENIED") {
+            return " A human DENIED this decision, and your action appears to have run anyway. Decidio recorded the refusal and will NOT attach execution evidence to a denied decision. Do NOT re-run it — investigate why the action executed without an approval.";
+        }
+        if (code === "NOT_AUTHORIZED") {
+            return " This decision is not an approved, sealed decision, so no execution evidence can attach to it yet. If your action already ran, it ran WITHOUT authority — do NOT re-run it; investigate. If you are confirming early, wait for the approval and confirm then.";
+        }
         return " Your action ALREADY RAN — only its report failed. Do NOT re-run it.";
     }
     if (endpoint.startsWith("/agent/status")) {
@@ -22,7 +28,7 @@ export class DecidioHttpError extends Error {
                 : retryable
                     ? ` — this looks transient; retrying is safe (a retry creates a NEW request and can never double-execute).`
                     : ` — the server refused the request itself, so retrying it unchanged will fail the same way. Fix the request (or the decision it names) first.`) +
-            sideEffectNote(endpoint));
+            sideEffectNote(endpoint, typeof body?.code === "string" ? body.code : undefined));
         this.status = status;
         this.endpoint = endpoint;
         this.body = body;
@@ -44,7 +50,9 @@ export function decisionIdProblem(raw) {
         if (cp < 0x20 || cp === 0x7f)
             return "it contains control characters";
     }
-    if (raw.length > 256)
-        return `it is ${raw.length} characters long (limit 256)`;
+    if (raw.length > 128)
+        return `it is ${raw.length} characters long (limit 128)`;
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(raw))
+        return "it is not letters, digits, dot, dash or underscore starting with a letter or digit (an opaque id needs nothing else, and every other character is a way to make two different strings look like the same decision)";
     return null;
 }

package/dist/evidence.js

@@ -32,20 +32,22 @@ export function readConfirmResponse(body, opts) {
     if (!EVIDENCE_TIERS.includes(tier)) {
         return { reportRecorded: false, executionConfirmed: false, confirmationRetryable: false, reportJournalled: journalled, 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 rpt = body?.executionReport;
+    const hasVerdict = !!rpt && typeof rpt === "object" && typeof rpt.verified === "boolean";
+    const proofExplicitlyFailed = hasVerdict && rpt.verified === false;
+    const executionConfirmed = CONFIRMING.includes(tier) && !proofExplicitlyFailed;
     const outcome = { reportRecorded: true, evidenceTier: tier, executionConfirmed, reportJournalled: journalled };
-    if (!executionConfirmed && opts.signed)
+    if (!executionConfirmed && !proofExplicitlyFailed && opts.signed)
         outcome.diagnostic = describeTierGap(opts.capturedResponse);
-    else if (!executionConfirmed)
+    else if (!executionConfirmed && !proofExplicitlyFailed)
         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.";
-    const rpt = body?.executionReport;
-    if (rpt && typeof rpt === "object" && typeof rpt.verified === "boolean") {
+    if (hasVerdict) {
         outcome.executionReportVerified = rpt.verified;
         if (typeof rpt.reason === "string" && rpt.reason)
             outcome.executionReportReason = rpt.reason;
-        if (!rpt.verified) {
+        if (proofExplicitlyFailed) {
             const why = typeof rpt.reason === "string" && rpt.reason ? ` (${rpt.reason})` : "";
-            outcome.diagnostic = `${outcome.diagnostic ? outcome.diagnostic + " " : ""}The signed execution report did NOT verify${why} — the report was recorded without a proven attestation. Check the agent's key/DID/registration (npx @decidio/sdk doctor).`;
+            outcome.diagnostic = `the signed execution report did NOT verify${why}, so this is NOT a confirmed execution — the gate reported tier "${tier}", and this SDK refuses to read an unproven attestation as confirmation. Your action DID run; check the agent's key/DID/registration (npx @decidio/sdk doctor), then ${retry}`;
         }
     }
     return outcome;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { ResumeController } from "./resume.js";
 import { type EvidenceOutcome } from "./evidence.js";
-export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
+export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, 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";

package/dist/index.js

@@ -2,7 +2,7 @@ import { DecidioSuspendedError } from "./resume.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 { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 export { guard, Guard } from "./guard.js";
 export { DecidioHttpError, decisionIdProblem } from "./errors.js";
 import { DecidioHttpError, decisionIdProblem } from "./errors.js";

package/dist/inngest.d.ts

@@ -1,6 +1,6 @@
 import type { RequestListener } from "node:http";
 import { verifyResumeSignature } from "./resume.js";
-import type { GuardConfig, ApprovalContext } from "./index.js";
+import type { GuardConfig, ApprovalContext, EvidenceOutcome } 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";
@@ -24,10 +24,18 @@ export interface InngestClientLike {
         data: Record<string, any>;
     }): Promise<unknown>;
 }
+/** ONE RESULT SHAPE ACROSS EVERY DOOR (F-008), with the one field this door genuinely needs on
+ *  top of it. `status` stays because Inngest's durable path can legitimately end in `rejected` or
+ *  `blocked` without ever calling your action — the other adapters signal that by throwing. What
+ *  changed: the value is `value` (not `result`) so it reads the same as every other door, and
+ *  `confirmation` is CARRIED rather than discarded. It used to be thrown away inside the confirm
+ *  step, which made "it ran and Decidio recorded it" and "it ran and Decidio does not know"
+ *  indistinguishable to the caller. */
 export type GateStepOutcome<R> = {
     status: "executed" | "rejected" | "blocked";
     decisionId: string;
-    result?: R;
+    value?: R;
+    confirmation?: EvidenceOutcome;
 };
 /**
  * Gate an action INSIDE an Inngest function, with durable suspend on routing.

package/dist/inngest.js

@@ -22,8 +22,8 @@ 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, args.evidence); return true; });
-    return { status: "executed", decisionId: auth.decisionId, result };
+    const confirmation = await step.run("decidio-confirm", async () => gateConfirm(config, auth.decisionId, result, args.evidence));
+    return { status: "executed", decisionId: auth.decisionId, value: result, confirmation };
 }
 export function createInngestResumeBridge(opts) {
     const secret = opts.webhookSecret ?? "";