@decidio/sdk 0.1.11 → 0.2.0

package/README.md

@@ -90,8 +90,9 @@ const payInvoice = guard.protect(
   { mode: "blocking" },   // blocking = watch the whole loop live in one terminal sitting.
 );                        // Production agents use durable mode instead — see below.
 
-const result = await payInvoice({ id: "INV-2026-001", amount: 86_000 });
-console.log("executed after approval:", result);
+const { value, confirmation } = await payInvoice({ id: "INV-2026-001", amount: 86_000 });
+console.log("executed after approval:", value);
+console.log("Decidio recorded it as:", confirmation.evidenceTier);   // e.g. application_confirmed
 ```
 
 **4. Trigger it:**
@@ -200,7 +201,7 @@ That's the whole contract: gate → human decision → your execution → owned,
    - **proceed** — your function runs immediately (auto-approved under a named, versioned rule).
    - **route** — the action suspends (durable) or waits (blocking) for a human decision in Decidio's queue, then runs your function (or throws `DecidioRejectedError`).
    - **block** — the wrapper throws `DecidioBlockedError`; your function never runs.
-3. After your function runs, the wrapper reports the **real response it captured** back to Decidio, which records it as `application_confirmed` execution evidence (Decidio minimizes + tokenizes before storing — the immutable record never stores raw payloads).
+3. After your function runs, the wrapper reports the **real response it captured** back to Decidio (which minimizes + tokenizes before storing — the immutable record never stores raw payloads). The tier that report earns depends on what it can prove: `application_confirmed` when the agent has key material and signs the execution report, `agent_asserted` when it does not, and `execution_unconfirmed` when the reported value carries no usable evidence. The SDK tells you which it got; it never claims the top tier by default.
 
 Your agent executes its own action. **Decidio holds no write credentials for your system** — it authorizes the decision, records it, and (optionally) independently verifies it.
 
@@ -313,13 +314,42 @@ canonicalization preserves **value** semantics, not JavaScript object identity.
 pointing at the same object arrive as two equal objects, and mutating an argument inside your
 function does not affect the caller's copy.
 
-**What the SDK can and cannot promise about duplicates.** It prevents *concurrent* execution:
-an entry is claimed atomically before it runs, so two workers cannot both execute it and a
-duplicate signal finds nothing to replay. It cannot make an external side effect exactly-once —
-no client can. If your action succeeds and the process dies before the result is recorded,
-whether it ran is not knowable from this machine. So the contract is **at-least-once with
-honest recovery**, and your downstream action should be idempotent (the decision id makes a
-natural idempotency key).
+**What the SDK can and cannot promise about duplicates.** The guarantee, stated exactly:
+
+> Once invocation may have begun, the SDK never automatically invokes it again unless the
+> downstream system provides an idempotency guarantee or an operator explicitly reconciles it.
+
+It holds across processes and restarts, not just within one worker. Before your function is
+called the SDK writes a durable `invoking` marker to the pending store; from that moment no
+poll, no duplicate webhook, no fresh process and no worker cycle will call it again. Deletion of
+the parked row is cleanup, not the guarantee — a store whose `delete()` silently fails cannot
+cause a second execution.
+
+**Closing the last window yourself.** Pass `withContext: true` and your action receives an
+`ExecutionContext` as its first argument:
+
+```js
+const payInvoice = guard.protect(
+  async (ctx, invoice) => stripe.paymentIntents.create(
+    { amount: invoice.amount, currency: "usd" },
+    { idempotencyKey: ctx.idempotencyKey },   // ← stable across every attempt at this decision
+  ),
+  (invoice) => ({ action: "payInvoice", amount: invoice.amount }),
+  { withContext: true },
+);
+```
+
+`ctx` is `{ decisionId, attemptId, idempotencyKey }`. It is opt-in rather than inferred from your
+function's arity, because guessing wrong would hand a payment call a context object where it
+expected an invoice. `describe` still receives your arguments only — it describes the *request*,
+while the context describes the *execution*.
+
+It still cannot make an external side effect exactly-once — no client can. If your action
+succeeds and the process dies before the result is recorded, whether the downstream write
+committed is not knowable from this machine. The difference is what the SDK does about it: that
+decision becomes **`indeterminate`** and stops, rather than being retried into a duplicate
+payment. You settle it with `reconcile()` once you have looked downstream. Pass the decision id
+as your vendor's idempotency key and that window closes on their side too.
 
 Recovery is explicit rather than magical:
 
@@ -332,9 +362,12 @@ for (const item of await guard.resume.recover()) {
 // "parked"              → still waiting on a human; nothing has executed
 ```
 
-The report a worker sends is journalled *before* the first attempt, so a lost confirmation is
-recoverable; and because the journal holds no handler binding, replaying it can only re-send
-evidence — never re-run your function.
+The report a worker sends is written to the pending store's execution ledger *before* the first
+send attempt, so a lost confirmation is recoverable; and because that record holds no handler
+binding, replaying it can only re-send evidence — never re-run your function. The ledger lives in
+the store you configured, so two workers sharing one Redis or Postgres store can reconfirm each
+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`,
@@ -380,6 +413,10 @@ for engines you don't. Each adapter's shipped `.d.ts` header documents its wirin
 `npx @decidio/sdk <cmd>`:
 
 - `quickstart` — the guided two-minute tour (gate → approve → execute → proof)
+  - `--auto-approve-demo` approves the tour's own synthetic decision so it can run headless; it
+    then CLEANS UP the tour agent and token automatically. Pass `--keep-agent` to keep them.
+  - An interactive run keeps the agent by default and offers cleanup at the end;
+    `quickstart cleanup` works later too.
 - `init [agentId] [--unique] [--force] [--expires-days N]` — sign in, register, mint the agent token, write `.env` (+ `.gitignore` entries). Refuses to overwrite a *different* agent's key in this directory; `--force` backs the old `.env` up first.
 - `doctor` — config, connectivity, and what your current token can do
 - `approvals [--mine] [--json]` / `approvals approve|reject <id> [reason]` — the human side, from your terminal (the list is workspace-wide; `--mine` narrows it to this directory's agent)
@@ -392,7 +429,7 @@ for engines you don't. Each adapter's shipped `.d.ts` header documents its wirin
 The CLI's stream contract: **stdout carries results only** (safe to pipe — `--json` output is
 pure JSON); errors, usage shown on *error* paths, and the per-run target-host announcement go
 to **stderr**. Asked-for help (an explicit `--help`, or invoking the bare CLI) is itself a
-result and prints on stdout. Exit codes: 0 success · 1 failure or honest no-op · 2 usage error.
+result and prints on stdout. Exit codes: 0 success · 1 failure or honest no-op · 2 usage error · 3 `quickstart` stopped at the human moment (headless: the decision routed, but nothing executed and no receipt was written, so the run is deliberately not reported as a completed tour).
 
 Commands that administer your workspace (`init`, `approvals`, `receipt`) use a **session**
 sign-in held in memory for that run. What lands on disk in `.env`: the agent's floor-limited
@@ -413,6 +450,7 @@ manager for production.
   the fix. Anything else is transient, and retrying is safe because a retry creates a *new* request
   and can never double-execute.
 - `DecidioNetworkError` — the gate was unreachable. Nothing executed locally.
+- `DecidioUnsafeArgumentsError` — your call arguments cannot survive JSON with their meaning intact, so nothing was routed and nothing ran. The message names the field and the fix. Most often: `NaN`/`Infinity`, `-0`, a `Date`, `Map` or class instance, a `BigInt`, or a sparse array — anything whose serialized form would differ from the value the approval and signature cover. Pass the already-serialized form.
 
 ```js
 try { await payInvoice(inv); }
@@ -430,6 +468,6 @@ your queue.
 ## 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).
-- **Confirmation integrity:** the wrapper runs in your process, so it captures the genuine API response — a materially stronger signal than an agent self-report, but it trusts the host. For high-assurance, Decidio can *independently* read the source back (`source_confirmed`) where it holds a read connection.
+- **Confirmation integrity:** the wrapper runs in your process, so it captures the genuine API response — a materially stronger signal than an agent self-report, but it trusts the host. For high-assurance, Decidio can *independently* read the source back (`independently_reconciled`) where it holds a read connection.
 - **Zero-code alternative:** an agent that speaks MCP (e.g. Claude on the web) can reach the same gate via Decidio's `request_approval` MCP tool with no code at all.
 - **API surface:** the agent-gate REST contract this SDK speaks is described in [`openapi.yaml`](./openapi.yaml), shipped in the package.

package/dist/adapters/_gate.d.ts

@@ -1,4 +1,4 @@
-import { type GuardConfig, type ApprovalContext } from "../index.js";
+import { type GuardConfig, type ApprovalContext, type EvidenceOutcome } from "../index.js";
 /** The ONLY authorization verdicts this SDK understands. A gate answer outside this set means
  *  the SDK does not understand the decision — and an answer you do not understand means NO. */
 export declare const AUTHORIZE_VERDICTS: readonly ["proceed", "route", "block"];
@@ -16,7 +16,13 @@ export interface GateAuth {
  *  fourth verdict) is the realistic trigger, and it must never mean "run it". */
 export declare function assertAuthorizeVerdict(auth: unknown, fallbackDecisionId?: string): GateAuth;
 export declare function gateAuthorize(config: GuardConfig, ctx: ApprovalContext): Promise<GateAuth>;
-export declare function gateConfirm(config: GuardConfig, decisionId: string, result: unknown): Promise<void>;
+/** Report an adapter-path execution and RETURN what Decidio recorded.
+ *
+ *  Two 0.2.0 changes, both closing the same gap. It applies the caller's `evidence` mapper — the
+ *  warning below tells you to use that option, and on every engine adapter it did nothing, because
+ *  the mapper never reached this function. And it RETURNS the outcome instead of swallowing it, so
+ *  an adapter can hand its caller the same confirmation the core path now does. */
+export declare function gateConfirm(config: GuardConfig, decisionId: string, result: unknown, evidence?: (r: any) => unknown): Promise<EvidenceOutcome>;
 /** Normalize a resume payload ({verdict} | "approved" | ...) to a verdict string. */
 export declare function verdictFrom(payload: any): string;
 /** Throw the right error for a non-approving verdict; return for approved/auto_approved. */

package/dist/adapters/_gate.js

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { DecidioBlockedError, DecidioRejectedError, DecidioHttpError, signBoundProof, signConfirm, assertSafeTransport, canonicalize, readConfirmResponse, buildConfirmBody } from "../index.js";
+import { DecidioBlockedError, DecidioRejectedError, DecidioHttpError, signBoundProof, signConfirm, assertSafeTransport, carriesCredential, canonicalize, readConfirmResponse, buildConfirmBody, decisionIdProblem } from "../index.js";
 export const AUTHORIZE_VERDICTS = ["proceed", "route", "block"];
 export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
     const a = auth;
@@ -7,11 +7,15 @@ export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
     if (!a || !AUTHORIZE_VERDICTS.includes(a.decision)) {
         throw new DecidioBlockedError(`unrecognised authorization verdict ${JSON.stringify(a?.decision ?? null)} — refusing to execute. The gate answers ${AUTHORIZE_VERDICTS.join(" | ")}; anything else means this SDK version does not understand the decision (upgrade @decidio/sdk), and an answer you do not understand is never permission.`, decisionId);
     }
+    const idProblem = decisionIdProblem(a.decisionId);
+    if (idProblem) {
+        throw new DecidioBlockedError(`the gate answered "${a.decision}" with no usable decisionId (${JSON.stringify(a.decisionId ?? null)} — ${idProblem}) — refusing to execute. Every authorized action must be addressable: without an id it cannot be polled, resumed, confirmed or audited.`, decisionId);
+    }
     return a;
 }
 export async function gateAuthorize(config, ctx) {
     canonicalize(ctx, "describe(...)");
-    assertSafeTransport(config.apiUrl, !!config.apiToken);
+    assertSafeTransport(config.apiUrl, carriesCredential(config));
     const f = config.fetchImpl ?? fetch;
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;
     const requesterIdentity = (config.agentKey && config.agentDid)
@@ -37,20 +41,32 @@ export async function gateAuthorize(config, ctx) {
     }
     return assertAuthorizeVerdict(await res.json(), "unknown");
 }
-export async function gateConfirm(config, decisionId, result) {
+export async function gateConfirm(config, decisionId, result, evidence) {
     const f = config.fetchImpl ?? fetch;
+    const failed = (why, retryable = true) => ({
+        reportRecorded: false, executionConfirmed: false, confirmationRetryable: retryable, reportJournalled: false,
+        diagnostic: `your action RAN and Decidio does NOT have its execution report (${why}). Record the outcome from your own system; do NOT re-run the action.`,
+    });
     try {
-        assertSafeTransport(config.apiUrl, !!config.apiToken);
+        assertSafeTransport(config.apiUrl, carriesCredential(config));
     }
     catch (e) {
         console.warn(`[decidio] confirm failed (action succeeded): ${e.message}`);
-        return;
+        return failed(e.message, false);
+    }
+    let reported = null;
+    let evidenceProblem;
+    try {
+        reported = canonicalize((evidence ? evidence(result) : result) ?? null, evidence ? "evidence(result)" : "result");
+    }
+    catch (e) {
+        evidenceProblem = String(e?.message ?? e);
+        console.warn(`[decidio] ${decisionId}: the action SUCCEEDED but its result could not be reported as evidence (${evidenceProblem}). Reporting an empty captured response so the execution is still recorded — map the return value with the \`evidence\` option to earn a confirming tier. The action was NOT re-run.`);
     }
     try {
         const requesterIdentity = signConfirm(decisionId, config);
         if (!requesterIdentity)
             console.warn(`[decidio] execution evidence for ${decisionId} recorded as agent_asserted — no signing key configured, so the report can't be proven to come from this agent. Set DECIDIO_AGENT_KEY/DID to earn application_confirmed.`);
-        const reported = canonicalize(result ?? null, "result");
         const res = await f(config.apiUrl.replace(/\/$/, "") + "/agent/confirm", {
             method: "POST",
             headers: { "content-type": "application/json", ...(config.apiToken ? { authorization: `Bearer ${config.apiToken}` } : {}) },
@@ -58,16 +74,22 @@ export async function gateConfirm(config, decisionId, result) {
         });
         if (!res.ok) {
             console.warn(`[decidio] confirm returned ${res.status} (action succeeded)`);
-            return;
+            return { ...failed(`HTTP ${res.status}`, res.status === 408 || res.status === 429 || res.status >= 500), evidenceError: evidenceProblem };
         }
         const ev = readConfirmResponse(await res.json().catch(() => null), { signed: !!requesterIdentity, capturedResponse: reported });
         if (!ev.reportRecorded)
             console.warn(`[decidio] ${decisionId}: ${ev.diagnostic}`);
-        else if (!ev.executionConfirmed)
+        else if (!ev.executionConfirmed || ev.executionReportVerified === false)
             console.warn(`[decidio] execution evidence for ${decisionId} recorded as ${ev.evidenceTier} — ${ev.diagnostic}`);
+        if (evidenceProblem)
+            console.warn(`[decidio] ${decisionId}: the execution IS recorded, but with an empty captured response — see the evidence note above.`);
+        if (evidenceProblem)
+            ev.evidenceError = evidenceProblem;
+        return ev;
     }
     catch (e) {
         console.warn(`[decidio] confirm failed (action succeeded): ${e.message}`);
+        return { ...failed(e.message), evidenceError: evidenceProblem };
     }
 }
 export function verdictFrom(payload) {

package/dist/adapters/langgraph.d.ts

@@ -11,7 +11,9 @@ import { type GuardConfig, type ApprovalContext } from "../index.js";
  * (This wiring doc ships in the .d.ts — the README points here.)
  */
 /** Gate `run()` behind Decidio inside a LangGraph node. */
-export declare function decidioGate<R>(config: GuardConfig, ctx: ApprovalContext, run: () => Promise<R>): Promise<R>;
+export declare function decidioGate<R>(config: GuardConfig, ctx: ApprovalContext, run: () => Promise<R>, opts?: {
+    evidence?: (r: R) => unknown;
+}): Promise<R>;
 /** Translate Decidio's signed resume webhook into the LangGraph resume Command. The host
  *  maps decisionId → thread_id and passes this to graph.invoke/stream. */
 export declare function decidioResumeCommand(body: {

package/dist/adapters/langgraph.js

@@ -1,7 +1,7 @@
 import { interrupt, Command } from "@langchain/langgraph";
 import { DecidioBlockedError } from "../index.js";
 import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict, checkEngineVersion } from "./_gate.js";
-export async function decidioGate(config, ctx, run) {
+export async function decidioGate(config, ctx, run, opts) {
     const auth = await gateAuthorize(config, ctx);
     if (auth.decision === "block")
         throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
@@ -10,7 +10,7 @@ export async function decidioGate(config, ctx, run) {
         assertVerdict(verdictFrom(resumed), auth.decisionId, resumed?.reason);
     }
     const result = await run();
-    await gateConfirm(config, auth.decisionId, result);
+    await gateConfirm(config, auth.decisionId, result, opts?.evidence);
     return result;
 }
 export function decidioResumeCommand(body) {

package/dist/adapters/openai.d.ts

@@ -1,4 +1,4 @@
-import type { GuardConfig, ApprovalContext } from "../index.js";
+import { type GuardConfig, type ApprovalContext } from "../index.js";
 type ToolApprovalItem = any;
 interface RunStateLike {
     getInterruptions(): ToolApprovalItem[];
@@ -41,6 +41,11 @@ export declare function gateInterruptions(config: GuardConfig, state: RunStateLi
     resolved: Resolved[];
     pending: Pending[];
 }>;
-/** Apply a Decidio verdict to a resumed RunState (after RunState.fromString). */
+/** Apply a Decidio verdict to a resumed RunState (after RunState.fromString).
+ *
+ *  VALIDATES BEFORE MUTATING. `else state.reject(item)` treated every unrecognised string as a
+ *  rejection, so a garbled payload, a version-skew verdict or an empty string became a rejection
+ *  that a caller could not tell apart from a human deciding no — and the RunState was already
+ *  mutated by the time anyone could look. The recognised set is exactly the one `resume` uses. */
 export declare function applyResume(state: RunStateLike, item: ToolApprovalItem, verdict: string): void;
 export {};

package/dist/adapters/openai.js

@@ -1,4 +1,5 @@
 import { gateAuthorize, checkEngineVersion } from "./_gate.js";
+import { DecidioBlockedError } from "../index.js";
 export async function gateInterruptions(config, state, describe) {
     const resolved = [];
     const pending = [];
@@ -12,15 +13,22 @@ export async function gateInterruptions(config, state, describe) {
             state.reject(item);
             resolved.push({ item, verdict: "blocked", decisionId: auth.decisionId });
         }
-        else
+        else if (auth.decision === "route")
             pending.push({ item, decisionId: auth.decisionId });
+        else
+            throw new DecidioBlockedError(`unhandled authorization verdict ${JSON.stringify(auth.decision)}`, auth.decisionId);
     }
     return { resolved, pending };
 }
 export function applyResume(state, item, verdict) {
-    if (verdict === "approved" || verdict === "auto_approved")
+    if (verdict === "approved" || verdict === "auto_approved") {
         state.approve(item);
-    else
+        return;
+    }
+    if (verdict === "rejected" || verdict === "blocked") {
         state.reject(item);
+        return;
+    }
+    throw new DecidioBlockedError(`unrecognised resume verdict ${JSON.stringify(verdict)} — refusing to apply it. This SDK understands approved / auto_approved / rejected / blocked; anything else is a version skew, and guessing would turn "I do not understand" into a decision. The RunState was NOT modified.`, "");
 }
 checkEngineVersion("openai");

package/dist/adapters/temporal.d.ts

@@ -21,11 +21,15 @@ export declare function installDecidioSignal(): Map<string, {
     verdict: string;
     reason?: string;
 }>;
-export interface DecidioGateOpts {
+export interface DecidioGateOpts<R = unknown> {
     authorize?: () => Promise<GateAuth>;
     confirm?: (decisionId: string, result: unknown) => Promise<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. */
+    evidence?: (result: R) => unknown;
 }
 export declare function decidioGate<R>(config: GuardConfig, ctx: ApprovalContext, run: () => Promise<R>, verdicts: Map<string, {
     verdict: string;
     reason?: string;
-}>, opts?: DecidioGateOpts): Promise<R>;
+}>, opts?: DecidioGateOpts<R>): Promise<R>;

package/dist/adapters/temporal.js

@@ -22,6 +22,8 @@ export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
     }
     const result = await run();
     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);
         if (!confirmWarned) {
             confirmWarned = true;
@@ -29,7 +31,7 @@ export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
         }
     }
     else {
-        await gateConfirm(config, auth.decisionId, result);
+        await gateConfirm(config, auth.decisionId, result, opts?.evidence);
     }
     return result;
 }

package/dist/canonical.d.ts

@@ -15,4 +15,4 @@ export declare function canonicalize<T = JsonValue>(value: unknown, path?: strin
 export declare function canonicalizeArgs(args: readonly unknown[]): JsonValue[];
 /** RFC 8785-shaped canonical JSON of an already-canonical value — the exact bytes hashed for an
  *  execution report, so both languages produce the same digest. */
-export declare function canonicalJson(value: JsonValue): string;
+export declare function canonicalJson(value: JsonValue, path?: string): string;

package/dist/canonical.js

@@ -10,6 +10,22 @@ const NOT_ROUTED = "The decision was NOT routed; nothing reached Decidio.";
 function refuse(path, what, fix) {
     throw new DecidioUnsafeArgumentsError(`[decidio] ${path} ${what} — the approval payload must be plain JSON so that what a human approves is exactly what executes; ${fix} ${NOT_ROUTED}`);
 }
+function assertNoLoneSurrogate(s, p) {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff) {
+            const n = s.charCodeAt(i + 1);
+            if (n >= 0xdc00 && n <= 0xdfff) {
+                i++;
+                continue;
+            }
+            refuse(p, `contains an unpaired surrogate (U+${c.toString(16).toUpperCase()})`, "it cannot be encoded as UTF-8, so no wire or seal can carry it — repair the string (it is usually a split emoji or truncated UTF-16).");
+        }
+        else if (c >= 0xdc00 && c <= 0xdfff) {
+            refuse(p, `contains an unpaired surrogate (U+${c.toString(16).toUpperCase()})`, "it cannot be encoded as UTF-8, so no wire or seal can carry it — repair the string (it is usually a split emoji or truncated UTF-16).");
+        }
+    }
+}
 export function canonicalize(value, path = "args") {
     return walk(value, path, new Set());
 }
@@ -17,8 +33,12 @@ function walk(v, p, seen) {
     if (v === null)
         return null;
     const t = typeof v;
-    if (t === "boolean" || t === "string")
+    if (t === "boolean")
+        return v;
+    if (t === "string") {
+        assertNoLoneSurrogate(v, p);
         return v;
+    }
     if (t === "number") {
         const n = v;
         if (!Number.isFinite(n))
@@ -72,7 +92,11 @@ function walk(v, p, seen) {
                 refuse(`${p}.${key}`, "is a getter/setter", "an accessor is evaluated at serialization time, so the approved value could differ from the executed one — pass a plain data property.");
             if (!d.enumerable)
                 refuse(`${p}.${key}`, "is a non-enumerable property", "JSON drops it, so the approver would never see it — make it enumerable or remove it.");
-            out[key] = walk(d.value, `${p}.${key}`, seen);
+            assertNoLoneSurrogate(key, `${p}.${key}`);
+            Object.defineProperty(out, key, {
+                value: walk(d.value, `${p}.${key}`, seen),
+                writable: true, enumerable: true, configurable: true,
+            });
         }
         return out;
     }
@@ -90,15 +114,19 @@ function deepFreeze(v) {
 export function canonicalizeArgs(args) {
     return args.map((a, i) => deepFreeze(walk(a, `args[${i}]`, new Set())));
 }
-export function canonicalJson(value) {
+export function canonicalJson(value, path = "canonicalJson(...)") {
     if (value === null)
         return "null";
     if (typeof value === "boolean" || typeof value === "number")
         return JSON.stringify(value);
-    if (typeof value === "string")
+    if (typeof value === "string") {
+        assertNoLoneSurrogate(value, path);
         return JSON.stringify(value);
+    }
     if (Array.isArray(value))
-        return `[${value.map(canonicalJson).join(",")}]`;
+        return `[${value.map((v, i) => canonicalJson(v, `${path}[${i}]`)).join(",")}]`;
     const keys = Object.keys(value).sort();
-    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
+    for (const k of keys)
+        assertNoLoneSurrogate(k, `${path} key`);
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k], `${path}.${k}`)}`).join(",")}}`;
 }