@decidio/sdk 0.3.5 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog — @decidio/sdk
+
+Release notes for the client SDK. The Python package `decidio` ships the same changes under the same
+version (the two are conformance-locked twins). Each entry names what changed, what a reader must do
+on upgrade, and what proved it.
+
+## 0.4.0 — the scope statement
+
+- **README: "What 0.4 does not yet claim" and "Compatibility and support."** The stability promise is
+  stated: what is stable, what is Beta (the engine adapters), what is deprecated and kept until 1.0
+  (`protectBestEffort`, `gateInterruptions`), and the five things reviewers keep finding that only
+  product decisions close (trust-on-first-use issuer DID, the unshipped schema, the unshipped
+  conformance suites, provenance and the repository link). 1.0.0 follows user-acceptance testing.
+- **The tour fails closed on an unpinned check.** If the API omits the issuer DID, the tour used to warn
+  and still report success; it now fails and cleans up.
+- **The tour's preflight names everything it writes**, including `.decidio-token-journal` and
+  `.decidio-pending/`.
+- **`--` ends option parsing on all three verifier doors**, so a receipt saved under a dash-leading
+  name can be verified.
+- **The token recovery journal treats corruption as uncertainty, never absence** (prodsec retest of
+  0.3.5). Every row is parsed and schema-checked before any mint; a row that cannot be trusted refuses
+  `init` and `quickstart`, turns `doctor` red and makes `quickstart cleanup` exit non-zero - the bytes are
+  left as found. Appends are framed (a delimiter first if the previous row lost its newline, a schema
+  version, a write loop before the fsync), so a torn row stays discoverable.
+- **A resume signal that finds the decision `invoking` answers `indeterminate`**, not `already_resolved`
+  with "already ran": the action may still be running, may have crashed before any effect, or may have
+  finished without reporting. `already_resolved` is reserved for the final states.
+- **Temporal (Beta): a custom `confirm` may return the gate's confirm outcome** (validated with
+  `readConfirmResponse`) and it becomes the step's confirmation instead of being discarded.
+- **Transport: every refusal redacts URL userinfo**, including the opaque `scheme:user:secret@` spelling,
+  and Unicode space and format characters (NBSP, ideographic space, zero-width space, …) are refused in
+  both runtimes from one explicit list. Four cases joined the shared transport corpus.
+- **This file ships** in the tarball (and in the Python sdist), as a deliberate publish-boundary line.
+
+## 0.3.5 — the retest residuals
+
+- **Transport:** any control character or whitespace anywhere in the URL is refused before anything is
+  sent; refusals echo a redacted spelling (URL userinfo is a credential).
+- **Credential lifecycle:** the quickstart inspects a previous `.env.quickstart` before minting; secret
+  files are written temp + fsync + rename; **the token recovery journal** (`.decidio-token-journal`,
+  owner-only, append-only) records every minted token id before the credential file exists and retires
+  it on a durable write or any proven revoke. Credential creation fails closed if the journal cannot be
+  written. `quickstart cleanup` sweeps it; `doctor` lists outstanding entries.
+- **Verifiers (all three doors):** the `verificationMethod` must be the issuer's exact `did:key` method
+  identifier, and `created` must be a real calendar date-time. Correctly signed receipts naming a
+  nonexistent method fragment or an impossible time are now INVALID.
+- **Adapter gate:** the same describe validation as the core (a blank action or negative amount is
+  refused before signing or posting).
+- **Outcomes:** a resume signal that lost the race to a final answer is `already_resolved`; a parked row
+  whose payload is gone is `orphaned_state`.
+- Upgrade: no action. Custom stores are unaffected.
+
+## 0.3.4 — first-run consistency
+
+- Tour and README pointers, routing-by-default vs the universal-backstop block named as two states, the
+  stale "unsafe values park and fail on resume" paragraph corrected, cleanup discloses the durable
+  store, help never loads `.env` (and only when usage will actually print), adapter headers current.
+- Upgrade: no action.
+
+## 0.3.2 / 0.3.3 — the transition itself is atomic (COORDINATED UPGRADE)
+
+- **The shipped file stores are an append-only revision chain** (`<key>.rev.<N>`), published with a
+  hard link that refuses an existing name: exactly one writer wins each transition, and a loser
+  re-validates against what actually happened. This closed the pre-0.3.2 race in which a denial could
+  be written and returned and the denied action still run.
+- **Upgrade — read this if a directory is shared by more than one worker:** the first 0.3.2+ store
+  migrates the older marker layout one way. **Stop every older worker that shares the directory before
+  the first 0.3.2+ process starts**, then upgrade them together. An older worker writing into an
+  upgraded directory leaves a marker beside the chain, and that decision reads as unreadable by design.
+  Nothing deletes a revision; each decision keeps a handful of small files (see the README's sizing
+  envelope).
+- 0.3.3: one snapshot of `describe()`'s answer for signing and posting; the shared id grammar at every
+  exported resume door; a compensating revoke when a minted token's credential file fails to write;
+  `reconfirm()` on a reported decision tells the truth about confirmation.
+
+## 0.3.1
+
+- The verifier says what it proves (canonical signed claims, not exact bytes); proof options
+  (`proofPurpose`, `verificationMethod`, `created`) are part of the claim on every door; duplicate
+  `--issuer` flags are refused everywhere; orphaned token ids survive every replacement.
+
+## 0.3.0
+
+- A claim that gates nothing: `reportRecorded` and `executionConfirmed` are distinct, honest booleans.
+  A denial is final on every path. The decision-id grammar is defined server-side and mirrored here.
+- Upgrade for custom stores: `markDiscarded` is required (a hard construction failure without it).
+
+## 0.2.x
+
+- The execution state machine (`parked → claimed_preinvoke → invoking → executed_unreported |
+  indeterminate → reported`), `reconcile()`, `ExecutionContext` with a stable idempotency key, and the
+  composite return (`{ value, decisionId, confirmation }`) with `protectBestEffort` keeping the old shape.

package/README.md

@@ -66,7 +66,8 @@ stderr each run — set `DECIDIO_API_URL` (env or `.env`) to point at another De
 `init` signs you into your workspace (email + password, or paste the sign-in link from your
 workspace email), generates the agent's Ed25519 keypair **locally** (only the public `did:key`
 is sent), registers the agent, mints its **floor-limited API token** (limited to the agent runtime — request authorization, poll status, report signed confirmation; it cannot administer the workspace or approve anything — and your workspace session never touches the agent's disk), and writes `.env`.
-Every later command reads `.env` from this directory automatically. Re-running init for an
+Every later command that talks to Decidio reads `.env` from this directory automatically (`verify` is
+offline and never does). Re-running init for an
 agent that already has a token REPLACES it — the server keeps one active token per agent, so
 the previous one is revoked and init says so.
 
@@ -677,6 +678,45 @@ Every error raised after a decision exists carries the `decisionId`, so a suspen
 timed-out action is always findable in
 your queue.
 
+## What 0.4 does not yet claim
+
+The retest that graded 0.3.3 *A- for the core and the shipped stores* and the first-run reviews of
+0.3.3 and 0.3.5 agree on what is left, and none of it is a defect a patch release closes. Stated here so
+the next reader grades a promise, not a moving target:
+
+- **Engine adapters are Beta and outside the stability promise.** They pass the same conformance
+  battery as the core against structural mocks; no live LangGraph/Temporal/Inngest/OpenAI restart suite
+  exists yet. Use the core path for production until it does.
+- **The issuer DID is trust on first use.** The tour and `receipt` print your workspace's issuer DID
+  from the same authenticated response that carries the receipt. Pinned verification is only as strong
+  as where you keep that DID: record it through a channel you trust independently (your app's
+  record-verify panel today; a published well-known location is on the roadmap).
+- **Verification is cryptographic, not schema validation.** `VALID` means the issuer's key signed these
+  canonical claims; the sealed-payload schema the receipt names by hash is not shipped, so a
+  structurally odd but correctly signed document is not refused on shape. Shipping the schema is on
+  the roadmap.
+- **The conformance suites are not in the package.** The deterministic two-process schedules that
+  prove the durable store, and the corpus every door is held to, live in the Decidio source repository.
+  A customer cannot rerun them from this tarball; a public conformance kit is on the roadmap.
+- **No provenance attestation, no repository link.** The source repository is private; npm refuses
+  provenance for private repositories, and a link that 404s is worse than none. Registry signatures and
+  lockfile integrity are what you can check today.
+
+## Compatibility and support
+
+- **Stable in 0.4:** `guard.protect` / `withApproval` and their options; the durable resume
+  controller (`createDecidioResume`: `park`, `resolve`, `reconcile`, `reconfirm`, `recover`, the worker
+  and both webhook handlers); the `PendingStore` contract and both shipped stores, including the on-disk
+  revision-chain layout; `EvidenceOutcome` (a root export) and `ResumeStatus` / `RecoveryState` (on the
+  `@decidio/sdk/resume` subpath), additive growth only; the error classes; the CLI's commands, flags and exit codes; the receipt verifier's verdict and
+  reasons. Changes to any of these announce themselves in the changelog first.
+- **Beta:** the engine adapters (above).
+- **Deprecated, kept until 1.0:** `protectBestEffort` (the value-only shape) and the old adapter
+  name `gateInterruptions`. They will be removed in 1.0.0, not before.
+- **Versioning:** 0.x minor releases may still carry deliberate breaking cleanups, announced in the
+  changelog with the upgrade step. 1.0.0 follows user-acceptance testing of this release and freezes the
+  surface above.
+
 ## Notes
 
 - **Framework-agnostic:** it wraps at the tool-call boundary, so it works with any agent runtime (LangGraph, OpenAI Agents SDK, CrewAI, a raw tool loop) and any action (Salesforce, M365, SAP, a DB write).

package/dist/adapters/temporal.d.ts

@@ -1,4 +1,4 @@
-import { type GuardConfig, type ApprovalContext, type ProtectedExecution } from "../index.js";
+import { type GuardConfig, type ApprovalContext, type ProtectedExecution, type EvidenceOutcome } from "../index.js";
 import { type GateAuth } from "./_gate.js";
 /**
  * @decidio/sdk/temporal — durable suspend via Temporal's native `condition()` + a
@@ -23,7 +23,10 @@ export declare function installDecidioSignal(): Map<string, {
 }>;
 export interface DecidioGateOpts<R = unknown> {
     authorize?: () => Promise<GateAuth>;
-    confirm?: (decisionId: string, result: unknown) => Promise<void>;
+    /** Reports through YOUR activity. Return the gate's confirm response body (validated with
+     *  `readConfirmResponse`) and it becomes the outcome; return nothing and the outcome says the SDK could
+     *  not read back what Decidio recorded (prodsec V035-03: a returned outcome used to be discarded). */
+    confirm?: (decisionId: string, result: unknown) => Promise<EvidenceOutcome | void>;
     /** Map your action's return value to the evidence Decidio records — the same option the core
      *  path takes. Every adapter's stderr note named it and no adapter accepted one, so on this
      *  path the advice could not be followed. */

package/dist/adapters/temporal.js

@@ -25,12 +25,13 @@ export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
     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 = {
+        const returned = await opts.confirm(auth.decisionId, result);
+        const usable = !!returned && typeof returned === "object" && typeof returned.reportRecorded === "boolean";
+        confirmation = usable ? returned : {
             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) {
+        if (!usable && !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.`);
         }

package/dist/cli.js

@@ -168,11 +168,25 @@ async function revokeFreshMint(jti, bearer, writeError, target) {
     return false;
 }
 const JOURNAL_PATH = ".decidio-token-journal";
+const JOURNAL_SCHEMA = 1;
+const JOURNAL_EVENTS = new Set(["probe", "minted", "retired"]);
 function journalAppend(entry) {
     const fresh = !existsSync(JOURNAL_PATH);
+    const row = Buffer.from(JSON.stringify({ v: JOURNAL_SCHEMA, ...entry, at: new Date().toISOString() }) + "\n", "utf8");
     const fd = openSync(JOURNAL_PATH, "a", 0o600);
     try {
-        writeSync(fd, JSON.stringify({ ...entry, at: new Date().toISOString() }) + "\n");
+        if (!fresh) {
+            const st = readFileSync(JOURNAL_PATH);
+            if (st.length && st[st.length - 1] !== 0x0a) {
+                let w = 0;
+                const nl = Buffer.from("\n");
+                while (w < nl.length)
+                    w += writeSync(fd, nl, w);
+            }
+        }
+        let written = 0;
+        while (written < row.length)
+            written += writeSync(fd, row, written);
         fsyncSync(fd);
     }
     finally {
@@ -186,7 +200,60 @@ function journalAppend(entry) {
         hardenFile(JOURNAL_PATH);
     }
 }
+function journalRowProblem(e) {
+    if (!e || typeof e !== "object" || Array.isArray(e))
+        return "not a JSON object";
+    if (e.v !== undefined && e.v !== JOURNAL_SCHEMA)
+        return `schema version ${JSON.stringify(e.v)} is not ${JOURNAL_SCHEMA}`;
+    if (typeof e.event !== "string" || !JOURNAL_EVENTS.has(e.event))
+        return `unknown event ${JSON.stringify(e.event ?? null)}`;
+    if (e.event !== "probe" && (typeof e.jti !== "string" || !e.jti.trim()))
+        return `${e.event} row without a string jti`;
+    if (e.event === "retired" && e.how !== "persisted" && e.how !== "revoked")
+        return `retired row with how=${JSON.stringify(e.how ?? null)}`;
+    return null;
+}
+class JournalCorruptError extends Error {
+    line;
+    why;
+    constructor(line, why) {
+        super(`${JOURNAL_PATH} line ${line}: ${why}`);
+        this.line = line;
+        this.why = why;
+        this.name = "JournalCorruptError";
+    }
+}
+function journalRows() {
+    if (!existsSync(JOURNAL_PATH))
+        return [];
+    const rows = [];
+    const lines = readFileSync(JOURNAL_PATH, "utf8").split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.trim())
+            continue;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            throw new JournalCorruptError(i + 1, "not valid JSON (a torn or hand-edited row)");
+        }
+        const why = journalRowProblem(e);
+        if (why)
+            throw new JournalCorruptError(i + 1, why);
+        rows.push(e);
+    }
+    return rows;
+}
+const REFUSE_MINT_CORRUPT_JOURNAL = (e) => `✘ the token recovery journal cannot be trusted (${e.message}) - it may hold the id of a token that is still live. Refusing to mint on top of uncertain history. Inspect the file, revoke anything it names (npx @decidio/sdk tokens list --mine), and repair or move it aside; every byte is left as found. Nothing was minted.`;
 function journalProbe() {
+    try {
+        journalRows();
+    }
+    catch (e) {
+        return `CORRUPT: ${e?.message ?? e}`;
+    }
     try {
         journalAppend({ event: "probe" });
         return null;
@@ -201,27 +268,18 @@ function journalRetire(jti, how) { try {
 }
 catch { } }
 function journalOutstanding() {
-    if (!existsSync(JOURNAL_PATH))
-        return [];
     const minted = new Map();
-    for (const line of readFileSync(JOURNAL_PATH, "utf8").split(/\r?\n/)) {
-        if (!line.trim())
-            continue;
-        let e;
-        try {
-            e = JSON.parse(line);
-        }
-        catch {
-            continue;
-        }
-        if (e?.event === "minted" && typeof e.jti === "string")
+    for (const e of journalRows()) {
+        if (e.event === "minted")
             minted.set(e.jti, { jti: e.jti, agentId: e.agentId, label: e.label, apiUrl: e.apiUrl, at: e.at });
-        if (e?.event === "retired" && typeof e.jti === "string")
+        if (e.event === "retired")
             minted.delete(e.jti);
     }
     return [...minted.values()];
 }
-const REFUSE_MINT_NO_JOURNAL = (why) => `✘ could not write the token recovery journal (${JOURNAL_PATH}: ${why}) - refusing to mint a credential this directory cannot record a revocation handle for. Fix the directory's permissions or free space and re-run. Nothing was minted.`;
+const REFUSE_MINT_NO_JOURNAL = (why) => why.startsWith("CORRUPT: ")
+    ? REFUSE_MINT_CORRUPT_JOURNAL(new Error(why.slice("CORRUPT: ".length)))
+    : `✘ could not write the token recovery journal (${JOURNAL_PATH}: ${why}) - refusing to mint a credential this directory cannot record a revocation handle for. Fix the directory's permissions or free space and re-run. Nothing was minted.`;
 function upsertEnv(updates) {
     const remaining = { ...updates };
     const updatedKeys = new Set();
@@ -514,14 +572,14 @@ async function cmdDoctor() {
     let warned = 0;
     const line = (good, label) => { log(`${good ? "✔" : "✘"} ${label}`); ok = ok && good; };
     const warn = (label) => { warned++; log(`⚠ ${label}`); };
-    let journalRows = [];
+    let journalItems = [];
     try {
-        journalRows = journalOutstanding();
+        journalItems = journalOutstanding();
     }
     catch (e) {
-        warn(`token recovery journal (${JOURNAL_PATH}) could not be read (${e?.message ?? e}) — it may hold live token ids; fix its permissions and re-run doctor.`);
+        line(false, `token recovery journal: ${e?.message ?? e} — it may hold the id of a live token, and this directory cannot mint until it is repaired or moved aside (every byte is left as found).`);
     }
-    for (const j of journalRows) {
+    for (const j of journalItems) {
         const where = j.apiUrl && j.apiUrl !== API ? `DECIDIO_API_URL=${j.apiUrl} ` : "";
         warn(`token recovery journal: jti ${j.jti} (${j.label ?? "token"}, agent ${j.agentId ?? "?"}, minted ${j.at ?? "?"} against ${j.apiUrl ?? API}) has no recorded revocation in this directory's journal — it may still be live. Revoke it, or confirm it is gone: ${where}npx @decidio/sdk quickstart cleanup   (or: ${where}npx @decidio/sdk tokens revoke ${j.jti})`);
     }
@@ -762,6 +820,10 @@ function cmdVerify(argsIn) {
     const files = [];
     for (let i = 0; i < argsIn.length; i++) {
         const a = argsIn[i];
+        if (a === "--") {
+            files.push(...argsIn.slice(i + 1));
+            break;
+        }
         if (a === "--issuer") {
             const v = argsIn[i + 1];
             if (v === undefined || v === "" || v.startsWith("-")) {
@@ -817,8 +879,10 @@ async function cmdQuickstart(opts = {}) {
     log(`  Target: ${API}${process.env.DECIDIO_API_URL ? "" : "  (the hosted synthetic sandbox — set DECIDIO_API_URL to use your own)"}`);
     log("");
     log("  This tour will: register one synthetic agent · mint a 7-DAY floor-limited token ·");
-    log("  write .env (or .env.quickstart) + .gitignore entries · create one synthetic decision");
-    log("  and its sealed record (records are permanent by design). Cleanup offer at the end.");
+    log("  write .env (or .env.quickstart), .decidio-token-journal (revocation ids, no secrets) and .gitignore");
+    log("  entries (incl. .decidio-pending/, the durable store your real agent will use) · save the receipt");
+    log("  as decidio-receipt-<id>.json here (public; it stays) · create one synthetic decision and its");
+    log("  sealed record (records are permanent by design). Cleanup offer at the end.");
     log("");
     const session = await acquireSession("The quickstart");
     if (!session)
@@ -1043,11 +1107,17 @@ async function cmdQuickstart(opts = {}) {
     const issuer = rec.body?.issuer;
     const v = verifyReceipt(rec.body.credential, issuer);
     log(`  ${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? `, PINNED to your workspace issuer ${issuer}` : ""})`);
+    if (!v.valid) {
+        err(`  ✘ the receipt did not verify (${v.reason ?? "no reason given"}) — the tour did not complete.`);
+        return failTour(1);
+    }
     if (!issuer) {
         err(`  ⚠ the server did not return an issuer DID, so this check ran UNPINNED — it proves the`);
         err(`    receipt is internally consistent, NOT who issued it (a self-signed forgery also passes).`);
         err(`    Get your workspace's issuer DID from the app's record-verify panel, then re-check:`);
         err(`      npx @decidio/sdk verify --issuer <did:key:...> ${fname}`);
+        err(`  ✘ the tour does not count an UNPINNED check as success.`);
+        return failTour(1);
     }
     if (issuer)
         log(`    Keep that DID: it is your trust anchor — npx @decidio/sdk verify --issuer ${issuer} <receipt.json>`);
@@ -1101,7 +1171,15 @@ async function quickstartCleanup(session, envFile) {
     })();
     let journalRevoked = 0;
     const journalStuck = [];
-    for (const j of journalOutstanding()) {
+    let outstanding = [];
+    try {
+        outstanding = journalOutstanding();
+    }
+    catch (e) {
+        err(`✘ the token recovery journal cannot be trusted (${e?.message ?? e}). It may hold the id of a live token, so this cleanup cannot claim nothing is owed. Every byte is left as found: inspect ${JOURNAL_PATH}, revoke anything it names (npx @decidio/sdk tokens list --mine), then repair or move it aside and re-run.`);
+        return 1;
+    }
+    for (const j of outstanding) {
         if (j.apiUrl && j.apiUrl !== API) {
             journalStuck.push(j.jti);
             err(`  ⚠ journalled token ${j.jti} was minted against ${j.apiUrl}, not ${API} — revoke it there: DECIDIO_API_URL=${j.apiUrl} npx @decidio/sdk tokens revoke ${j.jti}`);
@@ -1437,7 +1515,12 @@ async function main(argv) {
             if (argsIn.includes("cleanup")) {
                 const envFile = existsSync(".env.quickstart") ? ".env.quickstart"
                     : (readEnvFile().DECIDIO_AGENT_ID ?? "").startsWith("quickstart-") ? ENV_PATH
-                        : journalOutstanding().length ? ".env.quickstart" : undefined;
+                        : (() => { try {
+                            return journalOutstanding().length ? ".env.quickstart" : undefined;
+                        }
+                        catch {
+                            return ".env.quickstart";
+                        } })();
                 if (!envFile) {
                     log("Nothing to clean up here: no .env.quickstart, .env doesn't belong to a quickstart agent, and the token recovery journal owes nothing.");
                     return 0;
@@ -1458,7 +1541,8 @@ async function main(argv) {
                 err("✘ --expires-days needs a positive whole number of days (e.g. --expires-days 30).");
                 return 2;
             }
-            const nameArg = argsIn.find((x, i) => !x.startsWith("-") && !(expIdx >= 0 && i === expIdx + 1));
+            const ddIdx = argsIn.indexOf("--");
+            const nameArg = ddIdx >= 0 ? argsIn[ddIdx + 1] : argsIn.find((x, i) => !x.startsWith("-") && !(expIdx >= 0 && i === expIdx + 1));
             let name = nameArg ?? process.env.DECIDIO_AGENT_ID ?? "my-agent";
             if (unique)
                 name = `${name}-${randomBytes(2).toString("hex")}`;

package/dist/inngest.d.ts

@@ -35,6 +35,8 @@ export type GateStepOutcome<R> = {
     status: "executed" | "rejected" | "blocked";
     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;
 };
 /**

package/dist/resume.d.ts

@@ -450,9 +450,11 @@ export declare class DecidioSuspendedError extends Error {
 /** `indeterminate` (0.2.0): the handler was INVOKED and then threw. Whether the downstream
  *  effect committed is not knowable from here, so the action is never retried automatically —
  *  it waits for reconcile(). Callers that switch exhaustively on this union must handle it. */
-/** `already_resolved` (0.3.5): this resume signal LOST the transition race to an earlier, final answer
- *  (a denial, or an execution that already ran) — `reason` names which. It used to read `unknown`,
- *  which is the word for "not ours"; safety was right and the diagnosis was not (prodsec V033-06). */
+/** `already_resolved` (0.3.5): this resume signal LOST the transition race to an earlier, FINAL answer
+ *  (a denial, an execution that already ran, or a report already recorded) — `reason` names which. It used
+ *  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";
 /** The states a durable action can actually be in — every one of them nameable, including the
  *  one nobody likes. */

package/dist/resume.js

@@ -1037,7 +1037,12 @@ export function createDecidioResume(opts) {
                     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);
-                    return finish({ status: claim.state === "indeterminate" ? "indeterminate" : "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` });
+                    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}", …).`
+                                : claim.reason });
+                    }
+                    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 };
             }

package/dist/signing.d.ts

@@ -78,6 +78,10 @@ export declare function assertJsonSafe(value: unknown, path?: string): void;
  *  (it is refused as one), so no refusal may print it - every branch of assertSafeTransport echoes through
  *  this, not the raw string (invariant-guard, 0.3.5). */
 export declare function redactUrl(u: string): string;
+/** Unicode SPACE and FORMAT characters a URL must never contain: the Zs/Zl/Zp separators (NBSP, ideographic
+ *  space, …) and the zero-width formats. Spelled as an explicit list in BOTH runtimes so the answers cannot
+ *  drift with a library's notion of whitespace (Python's urlsplit strips a leading NBSP; WHATWG does not). */
+export declare const URL_UNICODE_SPACE: RegExp;
 export declare function assertSafeTransport(url: string, hasCredential: boolean): void;
 /** The ONE answer to "does this request carry a credential worth protecting?" (A6, 0.1.12).
  *  A signed identity proof is a credential too: sending it over remote plaintext disclosed

package/dist/signing.js

@@ -106,14 +106,17 @@ export function assertJsonSafe(value, path = "args") {
     };
     walk(value, path);
 }
-export function redactUrl(u) { return u.replace(/\/\/[^/@]*@/, "//***@"); }
+export function redactUrl(u) {
+    return u.replace(/\/\/[^/?#]*@/, "//***@").replace(/^([^/?#@:]*:)(?!\/\/)[\/\\]*[^/?#]*@/, "$1***@");
+}
+export const URL_UNICODE_SPACE = /[\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\u200b-\u200d\u2060]/;
 export function assertSafeTransport(url, hasCredential) {
     if (typeof url !== "string") {
         throw new Error(`[decidio] the gate URL is ${url === null ? "null" : typeof url}, not a string, so there is no host to send to. Decidio needs a full https URL (or http://localhost for local dev). Nothing was sent.`);
     }
     for (const ch of url) {
         const cp = ch.codePointAt(0);
-        if (cp <= 0x20 || (cp >= 0x7f && cp <= 0x9f) || cp === 0xfeff) {
+        if (cp <= 0x20 || (cp >= 0x7f && cp <= 0x9f) || cp === 0xfeff || URL_UNICODE_SPACE.test(ch)) {
             throw new Error(`[decidio] the gate URL ${JSON.stringify(redactUrl(url))} contains whitespace or a control character (U+${cp.toString(16).toUpperCase().padStart(4, "0")}) - a validator and a transport can read such a spelling differently, so it is refused as written. Remove it. Nothing was sent.`);
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "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",
@@ -40,6 +40,7 @@
     "dist",
     "openapi.yaml",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
@@ -82,7 +83,7 @@
     "prepublishOnly": "npm run typecheck && npm run build && node ../publish-boundary/check.mjs --only @decidio/sdk"
   },
   "dependencies": {
-    "@decidio/verify": "0.3.5"
+    "@decidio/verify": "0.4.0"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {