@decidio/sdk 0.4.0 → 0.4.3

package/dist/inngest.d.ts

@@ -31,13 +31,21 @@ export interface InngestClientLike {
  *  `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";
+export type GateStepOutcome<R> = 
+/** The action ran: the value AND what Decidio recorded (the step confirms before it returns). Encoded in the
+ *  type, not only in prose (prodsec V040-02): narrow on `status` and `confirmation` is there. */
+{
+    status: "executed";
     decisionId: string;
-    value?: R;
-    /** Always present when `status` is "executed" (the step confirms before it returns); optional in the type
-     *  because the other statuses carry none. */
-    confirmation?: EvidenceOutcome;
+    value: R;
+    confirmation: EvidenceOutcome;
+}
+/** The action never ran — a human said no, or a rule blocked it — so there is nothing to confirm. */
+ | {
+    status: "rejected" | "blocked";
+    decisionId: string;
+    value?: undefined;
+    confirmation?: undefined;
 };
 /**
  * Gate an action INSIDE an Inngest function, with durable suspend on routing.

package/dist/resume.d.ts

@@ -455,7 +455,13 @@ export declare class DecidioSuspendedError extends Error {
  *  to read `unknown`, the word for "not ours" (prodsec V033-06). An `invoking` row is NOT final and answers
  *  `indeterminate` (prodsec V035-02). Both members are additive: an exhaustive switch over this union
  *  gains a case per release, which the changelog announces. */
-export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown" | "indeterminate" | "already_resolved";
+/** `lost_race` (0.4.1): this signal lost the pre-invocation claim to ANOTHER ATTEMPT that is still in flight, or
+ *  the invocation boundary could not be recorded at all (a store fault) - and it did NOTHING. (A boundary lost to
+ *  an attempt already in flight reads `indeterminate`: that attempt may be running.) Nothing ran on this signal; the winner reports, or the entry stays
+ *  parked for a later signal. It used to read `unknown` (the word for "not ours") for the claim loser and
+ *  `no_handler` for the boundary loser although a handler was registered (prodsec V040-01). A loss to a FINAL
+ *  answer (a denial, an execution) stays `already_resolved`. Additive, like the two above. */
+export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown" | "indeterminate" | "already_resolved" | "lost_race";
 /** The states a durable action can actually be in — every one of them nameable, including the
  *  one nobody likes. */
 export type RecoveryState = 

package/dist/resume.js

@@ -335,8 +335,10 @@ export class FilePendingStore {
             try {
                 names = readdirSync(this.dir);
             }
-            catch {
-                return out;
+            catch (e) {
+                if (e?.code === "ENOENT")
+                    return out;
+                throw new DecidioStateCorruptError(key, [`${this.dir}: ${e?.message ?? e}`]);
             }
         }
         for (const name of names) {
@@ -753,6 +755,20 @@ export class DecidioSuspendedError extends Error {
         this.name = "DecidioSuspendedError";
     }
 }
+function outcomeFromHead(head, decisionId, action) {
+    if (!head)
+        return undefined;
+    const base = action ? { decisionId, action } : { decisionId };
+    switch (head.state) {
+        case "discarded": return { status: "already_resolved", ...base, reason: `this decision was DENIED (${head.verdict ?? "rejected"}); that answer is final and this signal did nothing` };
+        case "executed_unreported":
+        case "reported": return { status: "already_resolved", ...base, reason: `this decision already ran (durable state ${head.state}); this signal arrived after it and did nothing` };
+        case "invoking":
+        case "indeterminate": return { status: "indeterminate", ...base, reason: `this decision is in durable state ${head.state}: its action may still be running or may have finished without reporting - it may or may not have run. Nothing will retry it; check the worker and the downstream system, then settle it with reconcile("${decisionId}", …).` };
+        case "claimed_preinvoke": return { status: "lost_race", ...base, reason: `another attempt holds the pre-invocation claim on this decision; this signal did nothing. If that attempt is alive it will report; if it died, recover() lists the decision and reconcile() can settle it` };
+        default: return undefined;
+    }
+}
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function sign(secret, body) {
     return "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
@@ -951,7 +967,7 @@ export function createDecidioResume(opts) {
         if (refusalWarned.has(decisionId))
             return;
         refusalWarned.add(decisionId);
-        console.error(msg + (tail ?? " (This prints once — the entry stays parked until you act.)"));
+        console.error(msg + (tail ?? " (This prints once per worker process — the entry stays parked until you act.)"));
     };
     const ctrl = {
         ...opts,
@@ -991,8 +1007,12 @@ export function createDecidioResume(opts) {
             if (idProblem)
                 return { status: "unknown", decisionId: String(decisionId ?? ""), reason: `not a decision id this SDK will act on (${idProblem})` };
             const pending = await ctrl.store.get(decisionId);
-            if (!pending)
+            if (!pending) {
+                const mapped = outcomeFromHead(await ctrl.store.getExecution(decisionId), decisionId);
+                if (mapped)
+                    return finish(mapped);
                 return { status: "unknown", decisionId };
+            }
             if (verdict === "rejected" || verdict === "blocked") {
                 await ctrl.store.markDiscarded(decisionId, verdict, reason);
                 await ctrl.store.delete(decisionId);
@@ -1036,7 +1056,7 @@ export function createDecidioResume(opts) {
                 if (claim.state && NON_REPLAYABLE.includes(claim.state)) {
                     refuseOnce(decisionId, claim.state === "discarded"
                         ? `[decidio] REFUSING to execute ${decisionId}: it was DENIED (${(await ctrl.store.getExecution(decisionId))?.verdict ?? "rejected"}) and that answer is final. Nothing ran. A denial cannot be reconciled or retried — if this action should now proceed, it needs a NEW request and a new approval.`
-                        : `[decidio] REFUSING to execute ${decisionId}: its durable state is ${claim.state} — invocation already began, so re-running it could duplicate a committed effect. Inspect it with guard.resume.recover(); settle it with guard.resume.reconcile("${decisionId}", …).`, claim.state === "discarded" ? " (This prints once. The decision is closed — no action is needed.)" : undefined);
+                        : `[decidio] REFUSING to execute ${decisionId}: its durable state is ${claim.state} — invocation already began, so re-running it could duplicate a committed effect. Inspect it with guard.resume.recover(); settle it with guard.resume.reconcile("${decisionId}", …).`, claim.state === "discarded" ? " (This prints once per worker process. The decision is closed — no action is needed.)" : undefined);
                     if (claim.state === "invoking" || claim.state === "indeterminate") {
                         return finish({ status: "indeterminate", decisionId, action: pending.action, reason: claim.state === "invoking"
                                 ? `this decision is in durable state invoking: its action may still be running, may have crashed before any effect, or may have finished without reporting - it may or may not have run. Nothing will retry it; check the worker and the downstream system, then settle it with reconcile("${decisionId}", …).`
@@ -1044,7 +1064,10 @@ export function createDecidioResume(opts) {
                     }
                     return finish({ status: "already_resolved", decisionId, action: pending.action, reason: claim.state === "discarded" ? `this decision was already DENIED (${(await ctrl.store.getExecution(decisionId))?.verdict ?? "rejected"}); that answer is final and this signal lost the race to it` : `this decision already ran (durable state ${claim.state}); this signal lost the race to it` });
                 }
-                return { status: "unknown", decisionId };
+                const mapped = outcomeFromHead(await ctrl.store.getExecution(decisionId), decisionId, pending.action);
+                if (mapped)
+                    return finish(mapped);
+                return finish({ status: "lost_race", decisionId, action: pending.action, reason: `another attempt holds the pre-invocation claim on this decision${claim.state ? ` (durable state ${claim.state})` : ""}; this signal lost the race and did nothing. If that attempt is alive it will report; if it died, recover() lists the decision and reconcile() can settle it` });
             }
             try {
                 await ctrl.store.markInvoking(decisionId, attemptId);
@@ -1052,7 +1075,10 @@ export function createDecidioResume(opts) {
             catch (e) {
                 await ctrl.store.releasePreinvoke(decisionId, attemptId).catch(() => { });
                 console.error(`[decidio] ${decisionId}: could not record the invocation boundary (${e?.message ?? e}) — refusing to run the action rather than run it unrecorded.`);
-                return finish({ status: "no_handler", decisionId, action: pending.action, reason: "could not durably record the invocation boundary" });
+                const mapped = outcomeFromHead(await ctrl.store.getExecution(decisionId), decisionId, pending.action);
+                if (mapped)
+                    return finish(mapped);
+                return finish({ status: "lost_race", decisionId, action: pending.action, reason: `could not durably record the invocation boundary (${e?.message ?? e}); nothing ran, the entry stays parked, and a later signal may retry` });
             }
             let result;
             try {
@@ -1098,7 +1124,7 @@ export function createDecidioResume(opts) {
                     }
                     catch (e) {
                         res.statusCode = 500;
-                        res.end(JSON.stringify({ error: e?.message ?? "resume failed" }));
+                        res.end(JSON.stringify({ error: e instanceof DecidioStateCorruptError ? "DecidioStateCorruptError" : "resume failed", message: e?.message ?? String(e) }));
                     }
                 });
             };
@@ -1121,7 +1147,7 @@ export function createDecidioResume(opts) {
                     return new Response(JSON.stringify(webhookBody(outcome)), { status: 200, headers: { "content-type": "application/json" } });
                 }
                 catch (e) {
-                    return new Response(JSON.stringify({ error: e?.message ?? "resume failed" }), { status: 500 });
+                    return new Response(JSON.stringify({ error: e instanceof DecidioStateCorruptError ? "DecidioStateCorruptError" : "resume failed", message: e?.message ?? String(e) }), { status: 500 });
                 }
             };
         },
@@ -1294,12 +1320,23 @@ export function createDecidioResume(opts) {
             return items;
         },
         worker(workerOpts) {
+            const corruptWarned = new Set();
+            let listWarned = false;
             const interval = workerOpts?.intervalMs ?? 2_500;
             const deadline = workerOpts?.timeoutMs ? Date.now() + workerOpts.timeoutMs : Infinity;
             let stopped = false;
             (async () => {
                 while (!stopped) {
-                    const pendings = await ctrl.store.list().catch(() => []);
+                    let pendings = [];
+                    try {
+                        pendings = await ctrl.store.list();
+                    }
+                    catch (e) {
+                        if (!listWarned) {
+                            listWarned = true;
+                            console.error(`[decidio] the durable store could not be listed (${e?.message ?? e}) — this worker resumes nothing until it can be read again.`);
+                        }
+                    }
                     for (const p of pendings) {
                         let st;
                         try {
@@ -1314,7 +1351,20 @@ export function createDecidioResume(opts) {
                         if (!verdict)
                             continue;
                         try {
-                            const outcome = await ctrl.resolve({ decisionId: p.decisionId, verdict, reason: st.reason });
+                            let outcome;
+                            try {
+                                outcome = await ctrl.resolve({ decisionId: p.decisionId, verdict, reason: st.reason });
+                            }
+                            catch (e) {
+                                if (e instanceof DecidioStateCorruptError) {
+                                    if (!corruptWarned.has(p.decisionId)) {
+                                        corruptWarned.add(p.decisionId);
+                                        console.error(`[decidio] LEDGER CORRUPT for ${p.decisionId}: ${e.message} — this worker will not touch it until the ledger is repaired; the other parked actions still resume.`);
+                                    }
+                                    continue;
+                                }
+                                throw e;
+                            }
                             if (outcome.status === "executed" && outcome.reportRecorded)
                                 console.error(`[decidio] resumed ${p.decisionId}: approved → "${p.action}" executed; evidence recorded as ${outcome.evidenceTier}${outcome.executionConfirmed ? "" : " (execution NOT confirmed — see the warning above)"}.`);
                             else if (outcome.status === "executed")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.4.0",
+  "version": "0.4.3",
   "description": "One-line approval gate for AI-agent actions. Wrap a risky tool call with guard.protect(); Decidio's policy engine decides proceed | route | block, a human approves routed actions, and every outcome is sealed as a verifiable Authority Receipt.",
   "license": "Apache-2.0",
   "type": "module",
@@ -75,6 +75,7 @@
     "@langchain/langgraph": "^1.4.13",
     "@temporalio/workflow": "^1.23.0",
     "@types/node": "^22.20.1",
+    "tsx": "^4.23.13",
     "typescript": "^5.9.3"
   },
   "scripts": {
@@ -83,7 +84,7 @@
     "prepublishOnly": "npm run typecheck && npm run build && node ../publish-boundary/check.mjs --only @decidio/sdk"
   },
   "dependencies": {
-    "@decidio/verify": "0.4.0"
+    "@decidio/verify": "0.4.3"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {