@decidio/sdk 0.10.0 → 0.12.0

package/dist/demo-gate.js

@@ -41,6 +41,7 @@ export async function startDemoGate(opts = {}) {
     let relayCode = null;
     let relayOk = null;
     let committed = null;
+    let claimedBy = null;
     const relayFetch = async (path, init = {}) => {
         if (!relayBase)
             return null;
@@ -112,6 +113,7 @@ export async function startDemoGate(opts = {}) {
                     return send({ ok: true, changed: true });
                 if (path === "/agent/authorize") {
                     verdict = null;
+                    claimedBy = null;
                     committed = typeof body?.requestCommitment === "string" && /^[0-9a-f]{64}$/.test(body.requestCommitment) ? body.requestCommitment : null;
                     return send({ decision: "route", decisionId: DECISION_ID, receiptId: "R-DEMO-1", requestCommitment: committed });
                 }
@@ -128,6 +130,18 @@ export async function startDemoGate(opts = {}) {
                         return send({ state: "rejected", reason: "quickstart: withdrawn — the tour stopped waiting", requestCommitment: committed });
                     return send(verdict === "reject" ? { state: "rejected", reason: "quickstart: rejected by the approver", requestCommitment: committed } : { state: verdict === "approve" ? "approved" : "pending", requestCommitment: committed });
                 }
+                if (path.startsWith("/agent/claim/")) {
+                    const key = typeof body?.claimKey === "string" && /^[A-Za-z0-9._:-]{16,128}$/.test(body.claimKey) ? body.claimKey : null;
+                    if (!key)
+                        return send({ code: "VALIDATION", message: "claimKey must be 16-128 characters of letters, digits, dot, colon, underscore or dash" }, 400);
+                    if (verdict !== "approve")
+                        return send({ code: "NOT_CLAIMABLE", decisionId: DECISION_ID, state: verdict === "reject" ? "rejected" : "pending", message: "only a person's approval is collected here" }, 409);
+                    if (claimedBy && claimedBy !== key)
+                        return send({ code: "ALREADY_USED", decisionId: DECISION_ID, state: "approved", message: "another caller already collected this approval - ask again for a new one" }, 409);
+                    const again = claimedBy === key;
+                    claimedBy = key;
+                    return send({ ok: true, claimed: true, decisionId: DECISION_ID, again });
+                }
                 if (path.startsWith("/agent/withdraw/")) {
                     if (verdict)
                         return send({ code: "NOT_OPEN", state: verdict === "approve" ? "approved" : "rejected", decisionId: DECISION_ID }, 409);

package/dist/errors.js

@@ -30,7 +30,9 @@ export class DecidioHttpError extends Error {
                         ? ` — this looks transient. Your action ALREADY RAN; do NOT re-run it — only its report failed to land, and the door's own note says whether a report was kept to re-send.`
                         : /\/agent\/status/.test(endpoint)
                             ? ` — this looks transient; polling again is safe (a status read changes nothing).`
-                            : ` — this looks transient; retrying is safe (a retry creates a NEW request and can never double-execute).`)
+                            : /\/agent\/authorize/.test(endpoint)
+                                ? ` — this looks transient. This SDK already retried it with the same request key (a request still waiting is answered with the one already waiting); retrying is safe and can never double-execute.`
+                                : ` — this looks transient; retrying is safe 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, typeof body?.code === "string" ? body.code : undefined));
         this.status = status;

package/dist/guard.d.ts

@@ -17,6 +17,8 @@ export interface GuardFacadeConfig {
     workspaceId?: string;
     /** Base URL of the Decidio app (DECIDIO_APP_URL) — used to deep-link a routed decision. */
     appUrl?: string;
+    /** The per-call id behind the default request key (0.12.0) - see GuardConfig.invocationId. Leave it unset. */
+    invocationId?: () => string;
     fetchImpl?: typeof fetch;
 }
 export interface ProtectOptions {
@@ -53,6 +55,9 @@ export interface ProtectOptions {
      *  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;
+    /** YOUR OWN REQUEST KEY for a call, from its arguments (0.12.0) - e.g. `(inv) => inv.id` - so the same call asked again,
+     *  even from a new process, is the same request. Without it each call sends a fresh random key. See withApproval. */
+    requestKey?: (...args: any[]) => string;
 }
 export declare class Guard {
     config: GuardFacadeConfig;

package/dist/guard.js

@@ -60,6 +60,7 @@ export class Guard {
         const base = {
             apiUrl: c.apiUrl, agentId: c.agentId, apiToken: c.apiToken,
             sourceSystem: c.sourceSystem, agentKey: c.agentKey, agentDid: c.agentDid, workspaceId: c.workspaceId, appUrl: c.appUrl, fetchImpl: c.fetchImpl,
+            ...(c.invocationId ? { invocationId: c.invocationId } : {}),
             pollTimeoutMs: opts?.pollTimeoutMs, pollIntervalMs: opts?.pollIntervalMs,
         };
         if ((opts?.mode ?? "durable") === "blocking") {
@@ -68,12 +69,12 @@ export class Guard {
                 `(pollTimeoutMs), and when it does, this process stops waiting and the request is withdrawn in Decidio: ` +
                 `a later approval does nothing. 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 } : {}), ...(opts?.withContext ? { withContext: true } : {}) });
+            return withApproval(fn, describe, base, { ...(opts?.evidence ? { evidence: opts.evidence } : {}), ...(opts?.withContext ? { withContext: true } : {}), ...(opts?.requestKey ? { requestKey: opts.requestKey } : {}) });
         }
         const resume = this.ensureResume();
         if (opts?.action)
             resume.register(opts.action, fn, opts?.evidence, opts?.withContext);
-        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume }, { ...(opts?.evidence ? { evidence: opts.evidence } : {}), ...(opts?.withContext ? { withContext: true } : {}) });
+        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume }, { ...(opts?.evidence ? { evidence: opts.evidence } : {}), ...(opts?.withContext ? { withContext: true } : {}), ...(opts?.requestKey ? { requestKey: opts.requestKey } : {}) });
     }
     protectBestEffort(fn, describe, opts) {
         const wrapped = this.protect(fn, describe, opts);

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import type { ResumeController, ApprovalCheck } from "./resume.js";
+import type { ResumeController, ApprovalCheck, ClaimOutcome } from "./resume.js";
 import { type CommittedRequest } from "./signing.js";
 import { type EvidenceOutcome } from "./evidence.js";
-export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded, checkApproval } from "./resume.js";
-export type { PendingAction, PendingStore, ResumeController, ResumeOutcome, ApprovalCheck, ApprovalCheckCode, DecisionStatus } from "./resume.js";
+export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded, checkApproval, claimApproval, newClaimKey } from "./resume.js";
+export type { PendingAction, PendingStore, ResumeController, ResumeOutcome, ApprovalCheck, ApprovalCheckCode, DecisionStatus, ClaimOutcome, ClaimCode } from "./resume.js";
 export { guard, Guard } from "./guard.js";
 export type { GuardFacadeConfig, ProtectOptions } from "./guard.js";
 export { DecidioHttpError, decisionIdProblem } from "./errors.js";
-export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential, bindingMaterial, boundScope, requestCommitment, idempotencyKey, committedRequestJson } from "./signing.js";
+export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential, bindingMaterial, boundScope, requestCommitment, idempotencyKey, invocationRequestKey, ownRequestKey, committedRequestJson } from "./signing.js";
 export type { BindingMaterial, CommittedRequest } from "./signing.js";
 export { canonicalize, canonicalizeArgs, canonicalJson, DecidioUnsafeArgumentsError } from "./canonical.js";
 export type { JsonValue, JsonPrimitive } from "./canonical.js";
@@ -61,6 +61,11 @@ export interface GuardConfig {
      *  Sent on /agent/authorize so the decision carries it. Falls back to
      *  resume.resumeUrl. Omit when using the poll worker. */
     resumeUrl?: string;
+    /** Where the per-call id behind the DEFAULT REQUEST KEY comes from (0.12.0, 11f). Every call that sends a request
+     *  commitment also sends a request key derived from a fresh random id and that commitment, so this SDK's own retry of
+     *  the authorize is the same request. Leave it unset: a fixed id makes every call the SAME request. It exists so a
+     *  test or a conformance harness can pin the bytes it compares. */
+    invocationId?: () => string;
     fetchImpl?: typeof fetch;
 }
 export interface ApprovalContext {
@@ -115,11 +120,15 @@ export declare function coreRequest(ctx: {
 export declare class DecidioTimeoutError extends Error {
     decisionId: string;
     withdrawn: boolean;
+    shared: boolean;
     /** `withdrawn` (0.6.4+): true when the SDK told Decidio it gave up and the request was closed as
      *  WITHDRAWN (the queue no longer carries it; a later approval does nothing); false when that
      *  best-effort call failed, so the request may still be open in Decidio. Nothing was executed
-     *  locally either way. */
-    constructor(decisionId: string, withdrawn?: boolean);
+     *  locally either way.
+     *  `shared` (0.12.0): true when the request was left open on purpose because it may be shared - the authorize
+     *  answered an earlier request (`idempotentReplay`) or joined one another caller is waiting on (`openTwin`), or the
+     *  withdraw was refused because another caller joined it (409 SHARED_REQUEST). A person still decides it. */
+    constructor(decisionId: string, withdrawn?: boolean, shared?: boolean);
 }
 /** 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
@@ -132,7 +141,10 @@ export declare class DecidioRateLimitError extends Error {
     limit: number | undefined;
     remaining: number | undefined;
     resetAt: string | undefined;
-    constructor(limit: number | undefined, remaining: number | undefined, resetAt: string | undefined, serverMessage?: string);
+    code?: string | undefined;
+    /** `code` (0.12.0): the server's own code - `AGENT_RATE` for the workspace's hourly allowance, which is never retried;
+     *  a 429 without it is a transport throttle the SDK retries before it gives up. */
+    constructor(limit: number | undefined, remaining: number | undefined, resetAt: string | undefined, serverMessage?: string, code?: string | undefined);
 }
 export declare class DecidioNetworkError extends Error {
     endpoint: string;
@@ -145,6 +157,18 @@ export declare class DecidioNetworkError extends Error {
  *  every engine door reached the mock authorization path with a request the core would have refused.
  *  Exported so `adapters/_gate.ts` calls the same function rather than a second copy that can drift. */
 export declare function assertDescribed(ctx: ApprovalContext): void;
+/** THE ONE AUTHORIZE POST (0.12.0, 11f) - the core wrapper and every engine adapter send through here. A network failure
+ *  or a transient answer is retried a bounded number of times with the SAME body: under a request key that is the same
+ *  request (the gate answers the decision it already made, `idempotentReplay`), and a keyless request asked again while
+ *  it waits joins the one waiting (`openTwin`). A body that carries a commitment WITHOUT a key is never retried - nothing
+ *  would make the retry the same request. `rateLimit: "http"` keeps an adapter's 429 a DecidioHttpError, as it always was. */
+export declare function sendAuthorize(config: GuardConfig, first: Record<string, unknown>, opts?: {
+    rateLimit?: "typed" | "http";
+    resign?: () => unknown;
+}): Promise<any>;
+/** The typed refusal for a claim that did not let this run go ahead (0.12.0) - DecidioBlockedError, so code that treats
+ *  a block as "did not run" keeps doing so; the words say what happened and what to do ("ask again"). */
+export declare function claimRefusal(claim: ClaimOutcome): DecidioBlockedError;
 /**
  * Wrap an async action behind the Decidio gate. `describe` extracts the approval
  * context (action, amount, scope) from the call arguments. Returns a function with
@@ -172,6 +196,9 @@ export interface ProtectedExecution<R> {
     /** 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;
+    /** The request key this call sent with its authorize (0.12.0, 11f) - absent when none was sent (no key material, so no
+     *  commitment). It names the REQUEST to Decidio; your downstream idempotency key stays `decisionId`. */
+    requestKey?: string;
 }
 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
@@ -183,4 +210,9 @@ export declare function withApproval<A extends any[], R>(fn: (...args: A) => Pro
      *  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;
+    /** YOUR OWN REQUEST KEY for a call (0.12.0, 11f), from its arguments - an order or invoice id - so the same call asked
+     *  again, even from a new process, is the same request. Keyed with this agent's material before it is sent (your id
+     *  never reaches Decidio in the clear). The same key for a CHANGED request is refused by the gate (409
+     *  IDEMPOTENCY_CONFLICT), never a silent second request. Without it each call sends a fresh random key. */
+    requestKey?: (...args: A) => string;
 }): (...args: A) => Promise<ProtectedExecution<R>>;

package/dist/index.js

@@ -1,12 +1,13 @@
-import { DecidioSuspendedError, checkApproval } from "./resume.js";
-import { signBoundProof, signConfirm, assertSafeTransport, carriesCredential, bindingMaterial, requestCommitment } from "./signing.js";
+import { randomUUID } from "node:crypto";
+import { DecidioSuspendedError, checkApproval, claimApproval, newClaimKey, RETRY_DELAYS_MS } from "./resume.js";
+import { signBoundProof, signConfirm, assertSafeTransport, carriesCredential, bindingMaterial, requestCommitment, invocationRequestKey, ownRequestKey } from "./signing.js";
 import { canonicalize, canonicalizeArgs } from "./canonical.js";
 import { readConfirmResponse, buildConfirmBody } from "./evidence.js";
-export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded, checkApproval } from "./resume.js";
+export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded, checkApproval, claimApproval, newClaimKey } from "./resume.js";
 export { guard, Guard } from "./guard.js";
 export { DecidioHttpError, decisionIdProblem } from "./errors.js";
 import { DecidioHttpError, decisionIdProblem } from "./errors.js";
-export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential, bindingMaterial, boundScope, requestCommitment, idempotencyKey, committedRequestJson } from "./signing.js";
+export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential, bindingMaterial, boundScope, requestCommitment, idempotencyKey, invocationRequestKey, ownRequestKey, committedRequestJson } 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 {
@@ -66,10 +67,12 @@ export function coreRequest(ctx, args) {
 export class DecidioTimeoutError extends Error {
     decisionId;
     withdrawn;
-    constructor(decisionId, withdrawn = false) {
+    shared;
+    constructor(decisionId, withdrawn = false, shared = false) {
         super(`Timed out waiting for human approval (${decisionId})`);
         this.decisionId = decisionId;
         this.withdrawn = withdrawn;
+        this.shared = shared;
         this.name = "DecidioTimeoutError";
     }
 }
@@ -78,12 +81,14 @@ export class DecidioRateLimitError extends Error {
     limit;
     remaining;
     resetAt;
-    constructor(limit, remaining, resetAt, serverMessage) {
+    code;
+    constructor(limit, remaining, resetAt, serverMessage, code) {
         super(`[decidio] governed-action rate limit reached${limit != null ? ` (${limit}/hour on this workspace)` : ""}${resetAt ? ` — resets ${resetAt}` : ""}. ` +
             `${serverMessage ? serverMessage + " " : ""}Nothing was routed or executed; retry after the reset.`);
         this.limit = limit;
         this.remaining = remaining;
         this.resetAt = resetAt;
+        this.code = code;
         this.name = "DecidioRateLimitError";
     }
 }
@@ -97,8 +102,9 @@ export class DecidioNetworkError extends Error {
                 ? `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). `
                 : "") +
             `Nothing was executed locally and no verdict was received — if a request reached Decidio it is ` +
-            `visible in your queue. Check the network/URL (DECIDIO_API_URL) and retry; retrying is safe ` +
-            `(a retry creates a new request — it can never double-execute).`);
+            `visible in your queue. ` +
+            (/\/agent\/authorize/.test(op) ? `This SDK already retried it with the same request key. ` : "") +
+            `Check the network/URL (DECIDIO_API_URL) and retry; retrying is safe — it can never double-execute.`);
         this.endpoint = endpoint;
         this.op = op;
         this.code = code;
@@ -132,7 +138,7 @@ async function post(cfg, path, body) {
     });
     if (res.status === 429) {
         const b = await res.json().catch(() => null);
-        throw new DecidioRateLimitError(b?.limit, b?.remaining, b?.resetAt, b?.message);
+        throw new DecidioRateLimitError(b?.limit, b?.remaining, b?.resetAt, b?.message, typeof b?.code === "string" ? b.code : undefined);
     }
     if (!res.ok) {
         const raw = await res.text().catch(() => "");
@@ -145,6 +151,56 @@ async function post(cfg, path, body) {
     }
     return res.json();
 }
+function retriesSafely(e) {
+    if (e instanceof DecidioNetworkError)
+        return true;
+    if (e instanceof DecidioRateLimitError)
+        return e.code !== "AGENT_RATE";
+    if (e instanceof DecidioHttpError)
+        return (e.status >= 500 && e.status !== 501) || (e.status === 429 && e.body?.code !== "AGENT_RATE");
+    return false;
+}
+export async function sendAuthorize(config, first, opts = {}) {
+    const mayRetry = !!first.idempotencyKey || !first.requestCommitment;
+    let body = first;
+    const once = async () => {
+        if ((opts.rateLimit ?? "typed") === "typed")
+            return post(config, "/agent/authorize", body);
+        const f = config.fetchImpl ?? fetch;
+        assertSafeTransport(config.apiUrl, carriesCredential(config));
+        const res = await reach(f, config.apiUrl.replace(/\/$/, "") + "/agent/authorize", "POST /agent/authorize", {
+            method: "POST",
+            headers: { "content-type": "application/json", ...(config.apiToken ? { authorization: `Bearer ${config.apiToken}` } : {}) },
+            body: JSON.stringify(body),
+        });
+        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 res.json();
+    };
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await once();
+        }
+        catch (e) {
+            if (!mayRetry || attempt >= RETRY_DELAYS_MS.length || !retriesSafely(e))
+                throw e;
+            await sleep(RETRY_DELAYS_MS[attempt]);
+            const fresh = first.requesterIdentity && opts.resign ? opts.resign() : undefined;
+            if (fresh)
+                body = { ...first, requesterIdentity: fresh };
+        }
+    }
+}
+export function claimRefusal(claim) {
+    return new DecidioBlockedError(claim.ok ? "the approval was collected" : claim.reason, claim.decisionId);
+}
 async function get(cfg, path) {
     const f = cfg.fetchImpl ?? fetch;
     assertSafeTransport(cfg.apiUrl, carriesCredential(cfg));
@@ -190,13 +246,30 @@ export function withApproval(fn, describe, config, opts) {
         const material = bindingMaterial(config);
         const committed = coreRequest(ctx, args);
         const sentCommitment = material ? requestCommitment(material, committed) : undefined;
-        const auth = await post(config, "/agent/authorize", {
+        let requestKey;
+        if (opts?.requestKey) {
+            const own = opts.requestKey(...args);
+            if (typeof own !== "string" || own.length === 0)
+                throw new Error(`[decidio] requestKey(...) must return a non-empty string naming this call (got ${JSON.stringify(own ?? null)}). Nothing was routed or executed.`);
+            if (!material)
+                throw new Error("[decidio] requestKey needs this agent's key material (DECIDIO_AGENT_KEY + DECIDIO_AGENT_DID, or DECIDIO_API_TOKEN): a key rides only beside the request commitment that material makes, and Decidio refuses one alone. Nothing was routed or executed.");
+            requestKey = ownRequestKey(material, own);
+        }
+        else if (material && sentCommitment) {
+            requestKey = invocationRequestKey(material, config.invocationId ? String(config.invocationId()) : randomUUID(), sentCommitment);
+        }
+        const auth = await sendAuthorize(config, {
             requester: config.agentId, action: ctx.action, amount: ctx.amount,
             scope: ctx.scope, sourceSystem: config.sourceSystem,
             ...(ctx.context ? { context: ctx.context } : {}),
             ...(requesterIdentity ? { requesterIdentity } : {}),
             ...(resumeUrl ? { resumeUrl } : {}),
             ...(sentCommitment ? { requestCommitment: sentCommitment } : {}),
+            ...(requestKey ? { idempotencyKey: requestKey } : {}),
+        }, {
+            resign: () => (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,
         });
         if (auth.decision !== "proceed" && auth.decision !== "route" && auth.decision !== "block")
             throw new DecidioBlockedError(`unrecognized gate verdict: ${String(auth.decision)}`, auth.decisionId);
@@ -238,13 +311,18 @@ export function withApproval(fn, describe, config, opts) {
                 if (Date.now() > deadline) {
                     let withdrawn = false;
                     let lateState = null;
-                    try {
-                        await post(config, `/agent/withdraw/${encodeURIComponent(auth.decisionId)}`, { reason: "timeout" });
-                        withdrawn = true;
-                    }
-                    catch (e) {
-                        if (e instanceof DecidioHttpError && e.status === 409 && typeof e.body?.state === "string")
-                            lateState = e.body.state;
+                    let shared = auth.idempotentReplay === true || auth.openTwin === true;
+                    if (!shared) {
+                        try {
+                            await post(config, `/agent/withdraw/${encodeURIComponent(auth.decisionId)}`, { reason: "timeout" });
+                            withdrawn = true;
+                        }
+                        catch (e) {
+                            if (e instanceof DecidioHttpError && e.status === 409 && typeof e.body?.state === "string")
+                                lateState = e.body.state;
+                            else if (e instanceof DecidioHttpError && e.status === 409 && e.body?.code === "SHARED_REQUEST")
+                                shared = true;
+                        }
                     }
                     if (lateState === "approved" || lateState === "auto_approved")
                         break;
@@ -252,14 +330,19 @@ export function withApproval(fn, describe, config, opts) {
                         throw new DecidioRejectedError("rejected by approver", auth.decisionId);
                     if (lateState === "blocked")
                         throw new DecidioBlockedError("blocked", auth.decisionId);
-                    console.warn(`[decidio] blocking wait hit its ${Math.round(pollTimeout / 1000)}s limit — decision ${auth.decisionId} ${withdrawn ? "was withdrawn in Decidio (the queue no longer shows it; a later approval does nothing)" : "is still open in Decidio (the withdraw call failed), 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, withdrawn);
+                    console.warn(`[decidio] blocking wait hit its ${Math.round(pollTimeout / 1000)}s limit — decision ${auth.decisionId} ${withdrawn ? "was withdrawn in Decidio (the queue no longer shows it; a later approval does nothing)" : shared ? "is shared with another caller (or an earlier try of this one), so it was left open for a person to decide - this process stopped waiting" : "is still open in Decidio (the withdraw call failed), 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, withdrawn, shared);
                 }
                 await sleep(pollInterval);
             }
             const check = await checkApproval(config, auth.decisionId, committed, { sent: !!sentCommitment, ...(approvedStatus ? { status: approvedStatus } : {}) });
             if (!check.ok)
                 throw approvalRefusal(check);
+            if (check.state === "approved") {
+                const claimed = await claimApproval(config, auth.decisionId, newClaimKey());
+                if (!claimed.ok)
+                    throw claimRefusal(claimed);
+            }
         }
         const result = opts?.withContext
             ? await fn({ decisionId: auth.decisionId, attemptId: null, idempotencyKey: auth.decisionId }, ...args)
@@ -299,6 +382,6 @@ export function withApproval(fn, describe, config, opts) {
         }
         if (evidenceProblem)
             confirmation.evidenceError = evidenceProblem;
-        return { value: result, decisionId: auth.decisionId, confirmation };
+        return { value: result, decisionId: auth.decisionId, confirmation, ...(requestKey ? { requestKey } : {}) };
     };
 }

package/dist/inngest.d.ts

@@ -39,6 +39,7 @@ export type GateStepOutcome<R> =
     decisionId: string;
     value: R;
     confirmation: EvidenceOutcome;
+    requestKey?: string;
 }
 /** The action never ran — a human said no, or a rule blocked it — so there is nothing to confirm. */
  | {
@@ -70,6 +71,10 @@ export declare function decidioGateStep<R>(args: {
      *  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;
+    /** Inngest's id for THIS function run - the handler's `runId` (0.12.0, 11f). The request key is keyed on it, so Inngest
+     *  retrying the authorize step is the same request while it waits. Without it the key is
+     *  over a fresh id for the call (a retried step may then ask again). */
+    runId?: string;
 }): Promise<GateStepOutcome<R>>;
 /**
  * Decidio → Inngest bridge. Mount as an HTTP endpoint and register it as the agent's

package/dist/inngest.js

@@ -4,7 +4,7 @@ import { approvalRefusal } from "./index.js";
 export const DECIDIO_RESUME_EVENT = "decidio/decision.resolved";
 export async function decidioGateStep(args) {
     const { step, config, ctx } = args;
-    const auth = await step.run("decidio-authorize", async () => gateAuthorize(config, ctx));
+    const auth = await step.run("decidio-authorize", async () => gateAuthorize(config, ctx, typeof args.runId === "string" && args.runId ? { naturalId: { engine: "inngest", runId: args.runId, step: "decidio-authorize" } } : {}));
     assertAuthorizeVerdict(auth, auth?.decisionId);
     if (auth.decision === "block")
         return { status: "blocked", decisionId: auth.decisionId };
@@ -31,7 +31,7 @@ export async function decidioGateStep(args) {
     }
     const result = await step.run("agent-action", args.run);
     const confirmation = await step.run("decidio-confirm", async () => gateConfirm(config, auth.decisionId, result, args.evidence));
-    return { status: "executed", decisionId: auth.decisionId, value: result, confirmation };
+    return { status: "executed", decisionId: auth.decisionId, value: result, confirmation, ...(typeof auth.requestKey === "string" ? { requestKey: auth.requestKey } : {}) };
 }
 export function createInngestResumeBridge(opts) {
     const secret = opts.webhookSecret ?? "";

package/dist/resume.d.ts

@@ -38,6 +38,13 @@ export interface PendingAction {
      *  compared with the commitment Decidio returns. Absent on entries parked before 0.7.0 (and by
      *  an agent with no key material), which are checked on Decidio's state alone. */
     requestCommitment?: string;
+    /** THE RUN'S CLAIM KEY (0.12.0, founder call 24): made at random when the action is parked, and the key this parked
+     *  action collects a person's approval with (POST /agent/claim) right before it runs. It lives HERE, with the parked
+     *  action, so every resume of it - a worker that restarts, a signal after a lost answer, a claim an operator released -
+     *  is the same run to Decidio (`again: true`), while another process that parked its own copy of the request holds its
+     *  own key and is told the approval was used. Covered by the payload signature. Absent on entries parked before 0.12.0:
+     *  those claim with a fresh key each time (a lost answer then costs a new approval, never a second run). */
+    claimKey?: string;
 }
 /** Where suspended actions live between request and approval. The default is a
  *  file store; swap in Redis/Postgres/your queue for production. AGENT-SIDE only —
@@ -636,7 +643,11 @@ export interface ResumeController extends ResumeConfig {
      *  /agent/status + the request commitment — `checkApproval`). Decidio still pending → `not_approved`;
      *  Decidio says rejected/blocked → recorded as that denial; an approval that cannot be tied to these
      *  arguments → `request_unverified`. A transport failure during that check throws (nothing ran). A
-     *  `rejected`/`blocked` verdict is applied as given — it can only ever prevent execution. */
+     *  `rejected`/`blocked` verdict is applied as given — it can only ever prevent execution.
+     *
+     *  A PERSON'S approval is then COLLECTED ONCE (0.12.0, `claimApproval`) with the claim key parked with the action:
+     *  another run already used it, or it expired → `blocked` with the reason (recorded like a block; nothing ran); a 404
+     *  or a claim that could not be sent → throws (nothing ran, the entry stays parked for the next signal). */
     resolve(input: {
         decisionId: string;
         verdict: "approved" | "rejected" | "blocked";
@@ -704,7 +715,9 @@ export declare function assertConfirmRecorded(body: any, decisionId: string, sig
  *  authorized with, or null for a decision whose request was never bound. `spent` and `grantExpiresAt` (0.8.0,
  *  mini-approvals): the grant is ONE-TIME - `spent` once an execution was recorded on it, `grantExpiresAt` when
  *  it lapses (the seal's time plus the gate's TTL) for a granted decision, null otherwise. A gate that predates
- *  them answers neither. */
+ *  them answers neither. `handedBackAt` (when a replay handed the grant to a retry) and `claimed` (0.12.0: whether a
+ *  run has collected a person's approval - never by whom) are informational: reading the status claims NOTHING, and
+ *  this SDK decides a claim only by claiming (claimApproval). */
 export interface DecisionStatus {
     state: string;
     decisionId?: string;
@@ -713,6 +726,8 @@ export interface DecisionStatus {
     requestCommitment?: string | null;
     spent?: boolean;
     grantExpiresAt?: string | null;
+    handedBackAt?: string | null;
+    claimed?: boolean;
 }
 type StatusConfig = {
     apiUrl: string;
@@ -764,6 +779,41 @@ export declare function checkApproval(cfg: StatusConfig, decisionId: string, req
     sent?: boolean;
     status?: DecisionStatus;
 }): Promise<ApprovalCheck>;
+/** How long the SDK waits before each retry of a call it may safely repeat (11f): the authorize POST (with the same
+ *  body, so the same request key) and the claim (with the same claim key). Bounded: two retries, then the failure is the
+ *  caller's to see. Python twin: RETRY_DELAYS. */
+export declare const RETRY_DELAYS_MS: readonly number[];
+/** The grammar the gate takes for a request key and a claim key alike. */
+export declare const REQUEST_KEY_RE: RegExp;
+/** A claim key: RANDOM PER RUN (two workers with one key would be one run to Decidio, and both would run). The durable
+ *  path makes one when it parks an action and keeps it there; the blocking wait and the OpenAI resume make one per call. */
+export declare function newClaimKey(): string;
+/** Why a claim did not let this run go ahead. already_used / expired / not_claimable are Decidio's FINAL answers (409):
+ *  this approval will never run here. not_found (404: no such decision for this credential, or a gate that predates
+ *  claims), refused (any other 4xx), unreachable (a network failure or a 5xx after the retries) and unrecognized (an
+ *  answer this SDK does not understand) may change - nothing ran, and a later try may succeed. */
+export type ClaimCode = "already_used" | "expired" | "not_claimable" | "not_found" | "refused" | "unreachable" | "unrecognized";
+/** The outcome of one claim. Plain JSON on purpose, like ApprovalCheck: an engine that must run HTTP in an activity
+ *  (Temporal) returns it across its serialization boundary. */
+export type ClaimOutcome = {
+    ok: true;
+    decisionId: string;
+    again: boolean;
+} | {
+    ok: false;
+    decisionId: string;
+    code: ClaimCode;
+    final: boolean;
+    reason: string;
+    status?: number;
+};
+/** COLLECT A PERSON'S APPROVAL FOR THIS RUN, ONCE (POST /agent/claim/:decisionId) - the step every door that RUNS on a
+ *  person's approval takes right before it runs: the blocking wait, the durable resume, Temporal and the OpenAI resume. The
+ *  first claim wins; the same key claiming again is the same run retrying (`again: true`); any other key is told the
+ *  approval was already used. Reading the status claims nothing, so nothing that only watches ever calls this. An
+ *  auto-approval is never claimed (it is never shared). Retried with the SAME key on a network failure or a 5xx; every
+ *  answer other than a 200 that says `claimed: true` means DO NOT RUN. Never throws for an answer - a refusal is a value. */
+export declare function claimApproval(cfg: StatusConfig, decisionId: string, claimKey: string): Promise<ClaimOutcome>;
 /** The webhook handlers' refusal when no webhook secret is configured - with the remedy. */
 /** The one remedy every webhook-secret refusal names (#4B review W3): the dedicated webhook secret - NEVER the
  *  server's API_AUTH_TOKEN, the admin bearer, which a refusal that said "the value your deployment signs