@decidio/sdk 0.3.0 → 0.3.5

package/README.md

@@ -57,6 +57,9 @@ npm install @decidio/sdk
 npx @decidio/sdk init --unique my-agent   # --unique appends a random suffix: collision-proof
 ```
 
+> Just ran `npx @decidio/sdk quickstart` in this directory and kept its agent? Its `.env` already
+> works — skip this step and continue at step 3.
+
 Every CLI command talks to the hosted sandbox by default and announces its target host on
 stderr each run — set `DECIDIO_API_URL` (env or `.env`) to point at another Decidio instead.
 
@@ -148,8 +151,12 @@ evidence is yours, not ours. To also prove *who* issued it, pin your workspace's
 record verify panel — or simply read it off the `receipt` command's output, which prints your
 workspace's issuer DID from the authenticated response so you never have to hunt for it).
 
-**What VALID means — and what it does not.** A pinned `VALID` proves the receipt's bytes were
-sealed by your workspace's issuer and are unaltered since. It does **not** prove the approved
+**What VALID means — and what it does not.** A pinned `VALID` proves the receipt's **claims** were
+sealed by your workspace's issuer and that none of them has changed since. Not its *bytes*: the
+signature covers the record's canonical form (JCS), so reformatting the file — reindenting it,
+minifying it, reordering keys — still verifies, and should, because none of that alters a claim.
+If you need byte-for-byte custody, hash the file and keep that hash yourself; this proves the
+content, which is what an auditor is asking about. It does **not** prove the approved
 action ran. Execution is confirmed *after* the seal, and a sealed record is immutable, so the
 receipt's own `authority.result` and `confirmation.status` are a snapshot taken at seal time — a
 receipt for an approved-but-never-executed action verifies `VALID`, correctly. The verifier now
@@ -226,7 +233,11 @@ Real approvals take minutes to days, and nobody keeps a terminal open for them.
 `mode: "blocking"` (durable is the default) and a routed action **suspends** instead of
 waiting: it parks its call arguments agent-side (`.decidio-pending/` by default — Decidio
 stores none of your downstream payload) and throws `DecidioSuspendedError`. The process may
-exit. Two ways the parked action resumes when a human decides:
+exit. **The parked payload is plaintext on the agent's disk:** the full call arguments and their
+signature sit in `.decidio-pending/` until the decision resolves — owner-only permissions where the
+OS supports it, gitignored by `init`, but not encrypted. Treat that directory as you treat the `.env`
+beside it; a custom `PendingStore` can encrypt at rest. Two ways the parked action resumes when a
+human decides:
 
 **The worker (self-serve — start here).** No inbound URL, no shared secrets, and it resumes work
 the current process never started. Here is a complete `agent.mjs` you can run:
@@ -417,11 +428,12 @@ the store you configured, so two workers sharing one Redis or Postgres store can
 other's work. (Through 0.1.x this was a separate local-filesystem journal, which meant two
 workers kept two disjoint journals and neither could. `reportDir` is accepted and ignored now.)
 
-**Parked arguments must be JSON-serializable.** A suspended action is signed and then written to
-disk as JSON, so values that don't survive `JSON.stringify` round-tripping — `Date`, `Map`,
-`undefined`, `NaN`, class instances with custom `toJSON` — come back changed and fail the
-integrity check on resume (a refusal, never a wrong execution). Pass plain data; rehydrate
-inside your function.
+**Parked arguments must be JSON-serializable — and that is checked BEFORE routing.** Values that
+do not survive JSON with their meaning intact — `Date`, `Map`, `undefined`, `NaN`, class instances,
+functions — are refused with `DecidioUnsafeArgumentsError` before any decision exists and before any
+network call (since 0.1.12): nothing is parked, nothing is routed. The parked payload is also
+signed, so a file edited on disk fails the integrity check on resume (a refusal, never a wrong
+execution). Pass plain data; rehydrate inside your function.
 
 **Payload integrity.** When a routed action is parked, the SDK signs its arguments (bound to the
 decision id) with your agent key; on resume it **refuses to execute** if the parked payload was
@@ -445,6 +457,97 @@ for engines you don't. Each adapter's shipped `.d.ts` header documents its wirin
 @decidio/sdk quickstart` is the fastest runnable end-to-end.
 
 
+
+
+## The durable store is a revision chain (since 0.3.2)
+
+`FilePendingStore` keeps each decision's execution record as an **append-only revision chain** —
+`<id>.rev.1`, `<id>.rev.2`, … — and the head is the highest number. Every state change reads the
+head, validates against exactly that record, writes the successor to a temp file, and publishes it
+with `link()` to the next revision number. `link()` fails if that name already exists, so **exactly
+one writer wins each revision**, with no lock, no timeout and no daemon — on any volume that
+supports hard links (NTFS, ext4, APFS, XFS; not FAT/exFAT, and not every network or FUSE mount —
+on those every write fails closed rather than silently degrading). A loser re-reads the new head
+and validates again — against what actually happened, not a snapshot. **No revision file is ever
+deleted:** a name that could be reused is a race that could be lost, so the chain is genuinely
+append-only and a decision's whole history stays readable in place.
+
+This replaced the 0.2/0.3 one-marker-per-state layout after an external retest showed why it had to:
+that layout made a transition in three separate steps (read the markers, write the new one, sweep
+the weaker ones), so a process holding `claimed_preinvoke` could validate its snapshot, lose to a
+second process that durably wrote *and returned* a denial, then write `invoking` anyway — and its
+sweep deleted the tombstone. The SDK reported a denial as final and ran the denied action. Every
+*sequential* schedule was safe; the window was inside one transition. The chain has no such window:
+nothing ever deletes the head, and the rule that refuses a denied decision now runs against the
+denial that just landed.
+
+**Upgrading.** A directory in the older layout is migrated once, at the first construction of a
+0.3.2 store: each decision's markers become the head of a fresh chain and the markers are removed.
+Corrupt markers are left exactly as found and the decision reads as unreadable until a person
+inspects it. **Stop every older worker that shares the directory BEFORE the first 0.3.2 process
+constructs its store, then upgrade them together.** The one-time migration reads the markers it
+finds and removes exactly those; an older SDK still writing leaves a marker beside a chain, and
+that decision is then *unreadable* by design — neither reading can be trusted over the other, so
+the store refuses to pick one.
+
+**Custom stores.** The `PendingStore` contract has said since 0.2.0 that every method must be atomic
+against concurrent callers. The shipped file store did not honor that until now; a custom store must.
+The deterministic two-process schedules that proved the defect live in the Decidio source
+repository's conformance suite (not part of this package): a denial landing while an invoker is
+paused between validating and publishing; two conflicting settlements from one head; and a denier
+paused while the approver publishes four revisions past it. A store that cannot pass those schedules
+is not atomic, whatever its methods say.
+
+**Sizing envelope.** Nothing deletes a revision, so each decision leaves a handful of small files (one
+per transition, typically four to six) and a head lookup lists the directory. That is comfortable for
+tens of thousands of decisions on a local disk; beyond that, or for any deployment that shares a store
+across hosts, use a transactional custom `PendingStore`. The tested envelope is a **single host on a local
+filesystem with hard links** — network, FUSE and multi-host volumes are outside it, and their link
+semantics have not been exercised. Never compact the directory while a worker runs; if compaction is
+ever wanted it is an offline job with every writer stopped.
+
+## Reading a receipt
+
+The cryptography is only half the evidence. These are the fields that an outside reader has
+actually misread on a first run, and what each one means.
+
+**`ratified: yes` next to `deciders: 0` is not a contradiction.** `deciders` is the list of people
+nominated **in advance** to decide. When an agent's request is *routed* rather than pre-assigned,
+that list is empty — nobody was nominated, because the request had not happened yet. The person who
+actually decided is the **ratifier** (`ratifiedBy`). So a receipt for a human-approved action reads
+`deciders: 0, ratified: yes`, and the human is recorded, in the field named for the role they
+played. The verifier prints this explanation whenever the pair appears.
+
+**`appliedLimits` is what the request was MEASURED AGAINST, not a rule that fired.** It holds up to
+three entries, and only those that have a value: `requested_amount` (the amount actually asked for),
+`auto_approve_threshold` and `hard_cap` (the ceilings on the agent's own token). So a decision routed
+to a human because *no rule matched* can still list an `auto_approve_threshold` — that is the bar the
+request was compared to and did not clear, not a limit that was applied to it. Read
+`requested_amount` as the ask, the other two as ceilings.
+
+**`firedRules` is what the policy engine actually matched — for any verdict.** It is not an
+auto-approve indicator: a request **blocked by the universal backstop** (no active policy governs
+agents at all) carries that backstop rule here, so non-empty does not mean "approved" and empty does
+not mean "blocked". The field that states the
+disposition is `authority.result`; `firedRules` tells you which named, versioned rules produced it.
+
+**`payloadSchemaUri` is a `urn:`, not a URL.** It is content-addressed —
+`urn:decidio:sealed-payload:1:sha256:<hash>` — so it *identifies* the exact schema the record was
+sealed under and pins it against substitution. It does not locate a document, and nothing will
+resolve it. (Shipping the schema alongside the verifier so you can check the hash yourself is on
+the roadmap; today the URN is an identifier only, and this note exists so it does not look broken.)
+
+**`prevHash` proves a pointer, not an ancestry.** A non-null `prevHash` shows this record was
+sealed after a specific predecessor, but a single-file verification cannot check that predecessor
+exists or is what it claims. Verify a chain (`verify a.json b.json c.json`) when the sequence
+matters.
+
+**Pinning is trust-on-first-use.** The first time you fetch a receipt, the record *and* the issuer
+DID arrive in the same authenticated response — so that first check trusts the connection, not the
+key. What pinning buys is everything afterwards: record the DID once, out of band if you can, and
+every later verification is checked against a key you chose rather than one you were handed. The
+verifier says so on every unpinned run.
+
 ## 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
@@ -455,8 +558,10 @@ verdict, reason?)` is now REQUIRED — it writes the tombstone that makes a deni
 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.
+payload, and `settle` takes `workerStopped`. The shipped stores show the shape; the ownership
+corpus that pins these rules (claim fencing, terminal denial, advance-only transitions, settle
+preconditions) lives in the Decidio source repository and is not part of this package — the rules
+themselves are the ones stated above.
 
 **`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
@@ -495,8 +600,9 @@ that fits every other confirm error.
 
 - **Engine adapters are BETA.** They share the core's gate semantics — the verdict allow-list,
   the canonical argument model, the transport rule and evidence handling are ONE implementation,
-  and a conformance matrix runs the same malformed-verdict, unsafe-argument and plaintext-transport
-  battery against every door. What is *not* yet verified is the engine integration itself: those
+  and a conformance matrix runs the same malformed-verdict, unsafe-argument, plaintext-transport and
+  malformed-description (blank action, negative amount) battery against every door. What is *not* yet
+  verified is the engine integration itself: those
   paths are exercised against structural mocks, not live LangGraph/Temporal/Inngest/OpenAI
   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?
@@ -545,7 +651,7 @@ manager for production.
 
 ## Errors
 
-- `DecidioBlockedError` — policy blocked the action (incl. the universal deny-by-default backstop).
+- `DecidioBlockedError` — policy blocked the action: a named block rule, or the universal backstop that fires when NO active policy governs agents at all (fail closed, no human involved). Distinct from routing-by-default — with an active policy and no matching auto-approve rule, a request is not blocked, it is ROUTED to a person.
 - `DecidioRejectedError` — a human rejected the routed action.
 - `DecidioSuspendedError` — (durable mode) the action was routed and is parked for async approval; the process may exit and resume later. Not a failure.
 - `DecidioTimeoutError` — (blocking mode only) no human decided within `pollTimeoutMs` (default 10 min); the decision stays open in Decidio, nothing executed locally.

package/dist/adapters/_gate.js

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { DecidioBlockedError, DecidioRejectedError, DecidioHttpError, signBoundProof, signConfirm, assertSafeTransport, carriesCredential, canonicalize, readConfirmResponse, buildConfirmBody, decisionIdProblem } from "../index.js";
+import { DecidioBlockedError, DecidioRejectedError, DecidioHttpError, signBoundProof, signConfirm, assertSafeTransport, carriesCredential, canonicalize, assertDescribed, readConfirmResponse, buildConfirmBody, decisionIdProblem } from "../index.js";
 export const AUTHORIZE_VERDICTS = ["proceed", "route", "block"];
 export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
     const a = auth;
@@ -14,7 +14,8 @@ export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
     return a;
 }
 export async function gateAuthorize(config, ctx) {
-    canonicalize(ctx, "describe(...)");
+    ctx = canonicalize(ctx, "describe(...)");
+    assertDescribed(ctx);
     assertSafeTransport(config.apiUrl, carriesCredential(config));
     const f = config.fetchImpl ?? fetch;
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;

package/dist/adapters/openai.d.ts

@@ -15,7 +15,7 @@ interface RunStateLike {
  * park the serialized state agent-side on `route`, resume on Decidio's approval.
  *
  * const state = result.state;                       // or RunState from the run
- * const { resolved, pending } = await gateInterruptions(config, state, describe);
+ * const { resolved, pending } = await authorizeInterruptions(config, state, describe);
  * if (pending.length) { await store.put(decisionId, state.toString()); return; }  // suspend
  * result = await run(agent, state);                 // all resolved → resume
  * // on Decidio approval webhook: state = await RunState.fromString(agent, parked);