@junghanacs/entwurf 0.12.0

package/scripts/check-entwurf-v2-surface.ts

@@ -0,0 +1,352 @@
+/**
+ * check-entwurf-v2-surface — deterministic gate for the 5d-3a surface adapter
+ * (`entwurf-v2-surface.ts`) + the `entwurf-control.ts` wiring contract. It proves the PURE
+ * parts (the rest — production assembly — is check-entwurf-v2-production + the 5d-5 matrix):
+ *
+ *   1. toDispatchInput — `wants_reply`→`wantsReply` (snake→camel), `intent`/`message`/`target`
+ *      pass through, absent `mode`/`wants_reply` stay undefined (decider defaults, no double).
+ *   2. renderEntwurfV2Result — each result kind → the right `{ text, isError }`, surfacing the
+ *      carry-overs: reject reason + target-locked diagnostic / control N3 rejectReason /
+ *      spawn lock-retained diagnostic / N1 delivered-but-lock-dirty.
+ *   3. surface source guard — `entwurf-v2-surface.ts` is ctx-free (no ExtensionContext/API).
+ *   4. control wiring guard — `entwurf-control.ts` registers `entwurf_v2`, reaches the fence
+ *      ONLY via a NON-LITERAL dynamic import (a string-const specifier), NEVER a static import
+ *      of the fence v2 modules (which would break the emit-capable root tsc with TS5097), and
+ *      decorates the sender as `origin:"pi-session"` with HONEST replyability (SE-1 2e-a:
+ *      computeSelfAddressability + socket existsSync, not a hardcoded `replyable:true`).
+ */
+
+import assert from "node:assert/strict";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { EntwurfV2RunResult } from "../pi-extensions/lib/entwurf-v2-runner.ts";
+import {
+	actionableRejectHint,
+	ENTWURF_PREFIX_ROOTS_ENV,
+	parseEntwurfPrefixRootsEnv,
+	renderEntwurfV2Result,
+	type SurfaceEntwurfV2Params,
+	toDispatchInput,
+} from "../pi-extensions/lib/entwurf-v2-surface.ts";
+
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	assert.ok(cond, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.join(HERE, "..");
+const SURFACE_SRC = path.join(REPO, "pi-extensions/lib/entwurf-v2-surface.ts");
+const CONTROL_SRC = path.join(REPO, "pi-extensions/entwurf-control.ts");
+const MCP_SRC = path.join(REPO, "mcp/entwurf-bridge/src/index.ts");
+
+const GID = "20260613T100000-aaaaaa";
+const SUCCESS_RECEIPT = {
+	ok: true as const,
+	action: "send" as const,
+	transport: "control-socket" as const,
+	ownership: "ack-only" as const,
+	observedLiveness: "alive" as const,
+};
+
+async function main(): Promise<void> {
+	// ── 1: toDispatchInput mapping ────────────────────────────────────────────
+	{
+		const full: SurfaceEntwurfV2Params = {
+			target: GID,
+			intent: "owned-outcome",
+			message: "hi",
+			mode: "steer",
+			wants_reply: true,
+		};
+		const di = toDispatchInput(full);
+		ok(
+			"1: target/intent/message pass through",
+			di.target === GID && di.intent === "owned-outcome" && di.message === "hi",
+		);
+		ok("1: wants_reply → wantsReply (snake→camel)", di.wantsReply === true);
+		ok("1: mode passes through", di.mode === "steer");
+
+		const minimal: SurfaceEntwurfV2Params = { target: GID, intent: "fire-and-forget", message: "m" };
+		const dm = toDispatchInput(minimal);
+		ok("1: absent mode stays undefined (decider default)", dm.mode === undefined);
+		ok("1: absent wants_reply stays undefined (no double default)", dm.wantsReply === undefined);
+	}
+
+	// ── 2: renderEntwurfV2Result per kind ─────────────────────────────────────
+	{
+		// reject + target-locked diagnostic
+		const rejected: EntwurfV2RunResult = {
+			kind: "rejected",
+			receipt: { ok: false, reason: "target-locked", observedLiveness: null },
+			diagnostic: {
+				kind: "target-locked",
+				conflict: {
+					reason: "target-locked",
+					lockPath: "/locks/x.lock",
+					holder: {
+						gardenId: GID,
+						pid: 999,
+						hostname: "h",
+						createdAt: "2026-06-13T01:00:00.000Z",
+						nonce: "n",
+						owner: "entwurf_v2",
+						lockPath: "/locks/x.lock",
+					},
+					detail: "held by pid 999",
+				},
+			},
+		};
+		const rr = renderEntwurfV2Result(rejected);
+		ok(
+			"2: reject → isError + reason + diagnostic surfaced",
+			rr.isError && rr.text.includes("target-locked") && rr.text.includes("pid 999"),
+		);
+
+		// control sent → delivered
+		const sent: EntwurfV2RunResult = {
+			kind: "executed",
+			receipt: SUCCESS_RECEIPT,
+			transport: "control-socket",
+			outcome: { transport: "control-socket", outcome: "sent" },
+		};
+		ok(
+			"2: control sent → not error",
+			!renderEntwurfV2Result(sent).isError && renderEntwurfV2Result(sent).text.includes("sent"),
+		);
+
+		// control in-band rejected with N3 rejectReason → non-delivery
+		const ctlReject: EntwurfV2RunResult = {
+			kind: "executed",
+			receipt: SUCCESS_RECEIPT,
+			transport: "control-socket",
+			outcome: { transport: "control-socket", outcome: "rejected", rejectReason: "dormant-fire-forget-unsupported" },
+		};
+		const cr = renderEntwurfV2Result(ctlReject);
+		ok(
+			"2: control rejected → isError + N3 rejectReason surfaced",
+			cr.isError && cr.text.includes("dormant-fire-forget-unsupported"),
+		);
+
+		// spawn lock-retained → fail-closed diagnostic
+		const retained: EntwurfV2RunResult = {
+			kind: "executed",
+			receipt: { ...SUCCESS_RECEIPT, transport: "spawn-bg" },
+			transport: "spawn-bg",
+			outcome: {
+				transport: "spawn-bg",
+				result: {
+					kind: "lock-retained",
+					released: false,
+					reason: "observe-failed",
+					diagnostic: {
+						targetGardenId: GID,
+						lockPath: "/locks/x.lock",
+						expectedSocketPath: "/ctl/x.sock",
+						observeTimeoutMs: 30000,
+						killGraceMs: 5000,
+					},
+				},
+			},
+		};
+		const ret = renderEntwurfV2Result(retained);
+		ok(
+			"2: spawn lock-retained → isError + diagnostic surfaced",
+			ret.isError && ret.text.includes("LOCK RETAINED") && ret.text.includes("/locks/x.lock"),
+		);
+
+		// spawn socket-alive → delivered
+		const alive: EntwurfV2RunResult = {
+			kind: "executed",
+			receipt: { ...SUCCESS_RECEIPT, transport: "spawn-bg" },
+			transport: "spawn-bg",
+			outcome: { transport: "spawn-bg", result: { kind: "socket-alive", released: true, pid: 7 } },
+		};
+		ok("2: spawn socket-alive → not error", !renderEntwurfV2Result(alive).isError);
+
+		// meta-mailbox → enqueued
+		const mailbox: EntwurfV2RunResult = {
+			kind: "executed",
+			receipt: { ...SUCCESS_RECEIPT, transport: "meta-mailbox" },
+			transport: "meta-mailbox",
+			outcome: { transport: "meta-mailbox", success: true },
+		};
+		ok(
+			"2: meta-mailbox → not error + enqueued",
+			!renderEntwurfV2Result(mailbox).isError && renderEntwurfV2Result(mailbox).text.includes("enqueued"),
+		);
+
+		// N1: execution-failed with finalizedOutcome + releaseFailed → delivered-but-dirty
+		const n1: EntwurfV2RunResult = {
+			kind: "execution-failed",
+			receipt: SUCCESS_RECEIPT,
+			transport: "control-socket",
+			error: "release boom",
+			finalizedOutcome: "sent",
+			releaseFailed: true,
+			retrySafe: false,
+		};
+		const n1r = renderEntwurfV2Result(n1);
+		ok(
+			"2: N1 → isError + 'do NOT retry' + DIRTY surfaced",
+			n1r.isError && n1r.text.includes("DIRTY") && n1r.text.includes("do NOT retry"),
+		);
+
+		// plain execution-failed → error
+		const failed: EntwurfV2RunResult = {
+			kind: "execution-failed",
+			receipt: SUCCESS_RECEIPT,
+			transport: "control-socket",
+			error: "boom",
+			retrySafe: false,
+		};
+		ok("2: plain execution-failed → isError", renderEntwurfV2Result(failed).isError);
+
+		// Detour B (B-a): backend-liveness-unsupported reject → still a reject (isError),
+		// but the text carries the actionable "use fire-and-forget → mailbox" hint. The
+		// reject stays honest (reason unchanged, no auto-convert) — only the render guides.
+		const metaReject: EntwurfV2RunResult = {
+			kind: "rejected",
+			receipt: { ok: false, reason: "backend-liveness-unsupported", observedLiveness: "unsupported" },
+		};
+		const mr = renderEntwurfV2Result(metaReject);
+		ok(
+			"2: backend-liveness-unsupported reject → isError + actionable fire-and-forget/mailbox hint",
+			mr.isError &&
+				mr.text.includes("backend-liveness-unsupported") &&
+				mr.text.includes("fire-and-forget") &&
+				mr.text.includes("mailbox"),
+		);
+		ok(
+			"2B: actionableRejectHint guides meta-session owned → fire-and-forget mailbox",
+			(actionableRejectHint("backend-liveness-unsupported") ?? "").includes("fire-and-forget"),
+		);
+		ok(
+			"2B: actionableRejectHint guides owned-live → fire-and-forget",
+			(actionableRejectHint("owned-live-no-autosend") ?? "").includes("fire-and-forget"),
+		);
+		ok(
+			"2B: actionableRejectHint returns undefined for a reject with no next step",
+			actionableRejectHint("bad-target") === undefined,
+		);
+	}
+
+	// ── 6: parseEntwurfPrefixRootsEnv (5d-4b operator-policy SSOT) ─────────────
+	{
+		const D = path.delimiter;
+		ok("6: env name is ENTWURF_PREFIX_ROOTS", ENTWURF_PREFIX_ROOTS_ENV === "ENTWURF_PREFIX_ROOTS");
+		ok("6: undefined → [] (no prefix promotion)", parseEntwurfPrefixRootsEnv(undefined).length === 0);
+		ok("6: empty string → []", parseEntwurfPrefixRootsEnv("").length === 0);
+		ok("6: delimiters-only → []", parseEntwurfPrefixRootsEnv(`${D}${D}`).length === 0);
+		const two = parseEntwurfPrefixRootsEnv(`/repos/gh${D}/repos/work`);
+		ok("6: delimiter-separated → entries", two.length === 2 && two[0] === "/repos/gh" && two[1] === "/repos/work");
+		const trimmed = parseEntwurfPrefixRootsEnv(`  /a ${D} ${D} /b  `);
+		ok("6: trims + drops empty segments", trimmed.length === 2 && trimmed[0] === "/a" && trimmed[1] === "/b");
+		// A nonexistent/typo path is KEPT verbatim (no throw, no validation) — preflight's
+		// normalize handles it, and a typo must never broaden approve nor fail the dispatch.
+		const typo = parseEntwurfPrefixRootsEnv("/this/does/not/exist");
+		ok("6: nonexistent path kept verbatim (no throw)", typo.length === 1 && typo[0] === "/this/does/not/exist");
+	}
+
+	// ── 3: surface source guard — ctx-free ────────────────────────────────────
+	{
+		const src = await fs.readFile(SURFACE_SRC, "utf8");
+		const code = src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+		ok("3: surface is ctx-free — no ExtensionContext", !code.includes("ExtensionContext"));
+		ok("3: surface is ctx-free — no ExtensionAPI", !code.includes("ExtensionAPI"));
+	}
+
+	// ── 4: pi-native control wiring guard ─────────────────────────────────────
+	{
+		const src = await fs.readFile(CONTROL_SRC, "utf8");
+		const code = src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+		ok("4: pi-native — entwurf-control registers entwurf_v2", /name:\s*"entwurf_v2"/.test(src));
+		ok(
+			"4: pi-native — reaches the fence via a NON-LITERAL dynamic import (string-const specifier)",
+			/const ENTWURF_V2_SURFACE_MODULE\s*=/.test(code) && /await import\(ENTWURF_V2_SURFACE_MODULE\)/.test(code),
+		);
+		// The whole point of the dynamic import: NO static import of the fence v2 chain into the
+		// emit-capable root program (those literal `.ts` imports would be TS5097).
+		ok(
+			"4: pi-native — NO static import of the v2 fence (runner/production/surface) — TS5097 stays closed",
+			!/import[^;]*from\s*"\.\/lib\/entwurf-v2-(runner|production|surface)\.(js|ts)"/.test(code),
+		);
+		// SE-1 2e-a: senderProvider decorates origin:'pi-session' but `replyable` is now an
+		// HONEST fact (canonical socket existsSync via computeSelfAddressability), NOT a
+		// hardcoded true. The self-address fence lib is reached through the same non-literal
+		// dynamic import pattern as the v2 surface.
+		ok(
+			"4: pi-native — senderProvider decorates origin:'pi-session' (no hardcoded replyable:true)",
+			/origin:\s*"pi-session"/.test(code) && !/replyable:\s*true/.test(code),
+		);
+		ok(
+			"4: pi-native — replyability via computeSelfAddressability + existsSync, dynamic-imported",
+			/const ENTWURF_SELF_ADDRESS_MODULE\s*=/.test(code) &&
+				/await import\(ENTWURF_SELF_ADDRESS_MODULE\)/.test(code) &&
+				/computeSelfAddressability/.test(code) &&
+				/existsSync\(/.test(code),
+		);
+		ok(
+			"4: pi-native — NO static import of the self-address fence (TS5097 stays closed)",
+			!/import[^;]*from\s*"\.\/lib\/entwurf-self-address\.(js|ts)"/.test(code),
+		);
+		// Caller-intent steer (live-peer owned-outcome bug): the description must tell the model
+		// to use fire-and-forget for a LIVE/alive peer and that owned-outcome is dormant-only and
+		// NEVER auto-converted — the preventive fix (the decider must not auto-convert).
+		ok(
+			"4: pi-native — description steers live/alive peer → fire-and-forget",
+			/liveness=alive/.test(src) && /fire-and-forget/.test(src),
+		);
+		ok(
+			"4: pi-native — description says owned-outcome is dormant-only + never auto-converted",
+			/owned-outcome is ONLY for waking a DORMANT pi/.test(src) && /NEVER auto-converted/.test(src),
+		);
+	}
+
+	// ── 5: MCP bridge wiring guard ────────────────────────────────────────────
+	// The MCP bridge is a `.ts`-import fence consumer (mcp/tsconfig allowImportingTsExtensions),
+	// so it STATICALLY imports the surface adapter (no dynamic import). The v2 handler runs the
+	// production runner IN-PROCESS via runAndRenderEntwurfV2FromSurface — it does NOT route the
+	// v2 dispatch through legacy rpcCall/enqueueMetaMessage (those stay as the v2 runner's transport primitives).
+	{
+		const src = await fs.readFile(MCP_SRC, "utf8");
+		ok("5: MCP — registers entwurf_v2 server.tool", /server\.tool\(\s*"entwurf_v2"/.test(src));
+		ok(
+			"5: MCP — static imports runAndRenderEntwurfV2FromSurface from the surface fence module",
+			/import\s*\{[^}]*runAndRenderEntwurfV2FromSurface[^}]*\}\s*from\s*"[^"]*entwurf-v2-surface\.ts"/.test(src),
+		);
+		// Isolate the entwurf_v2 server.tool(...) block: from its name literal to the NEXT
+		// server.tool( registration. The v2 handler must build the sender + call the surface
+		// adapter, and must NOT itself reach for a legacy transport (the decider routes).
+		const v2Start = src.indexOf('"entwurf_v2"');
+		const after = src.indexOf("server.tool(", v2Start + 1);
+		const v2Block = src.slice(v2Start, after === -1 ? undefined : after);
+		ok("5: MCP — v2 handler builds buildSendSenderEnvelope()", /buildSendSenderEnvelope\(\)/.test(v2Block));
+		ok("5: MCP — v2 handler passes senderProvider: () => sender", /senderProvider:\s*\(\)\s*=>\s*sender/.test(v2Block));
+		ok(
+			"5: MCP — v2 handler calls runAndRenderEntwurfV2FromSurface",
+			/runAndRenderEntwurfV2FromSurface\(/.test(v2Block),
+		);
+		ok(
+			"5: MCP — v2 handler routes through the runner, NOT legacy rpcCall/enqueueMetaMessage",
+			!/\brpcCall\(/.test(v2Block) && !/\benqueueMetaMessage\(/.test(v2Block),
+		);
+		// Caller-intent steer — same preventive guidance on the MCP surface (a sibling reaching
+		// in over MCP reads this description, not the pi-native one).
+		ok(
+			"5: MCP — description steers live/alive peer → fire-and-forget",
+			/liveness=alive/.test(src) && /fire-and-forget/.test(src),
+		);
+		ok(
+			"5: MCP — description says owned-outcome is dormant-only + never auto-converted",
+			/owned-outcome is ONLY for waking a DORMANT pi/.test(src) && /NEVER auto-converted/.test(src),
+		);
+	}
+
+	console.log(`\ncheck-entwurf-v2-surface: ${passed} checks passed`);
+}
+
+await main();

package/scripts/check-keyset-overlap.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""check-keyset-overlap — guard the keyset-owner invariant across consumers.
+
+entwurf's meta-bridge install OWNS a fixed set of `~/.claude/settings.json`
+(+ `~/.claude.json`) keys (the SSOT is `meta-bridge-state.py managed-keys`).
+agent-config (and any future consumer) merges its OWN fragment into the same
+file. The invariant: each side sets only its own keys and never the other's —
+otherwise a later `agent-config` merge (jq `.[0] * .[1]`, which REPLACES arrays
+and overwrites scalars) silently clobbers pi-owned policy, or vice-versa.
+
+This is the PREVENTIVE half of the guard (doctor's `state.py check` is the
+after-the-fact survival half). It reads pi's owned key paths and one or more
+consumer fragment JSON files, and fails loud if any consumer key collides with a
+pi-owned key — exact match OR ancestor/descendant (a fragment that sets
+`statusLine.command` collides with pi's whole-`statusLine` ownership).
+
+Cross-repo and not hermetic (the fragment path is an argument), so it lives
+OUTSIDE `pnpm check` / release-gate — it is for agent-config CI and manual
+cross-checks. The synthetic-fixture regression of this script's own logic lives
+in `smoke-meta-keyset-guard.sh`, which IS in `pnpm check`.
+
+usage: check-keyset-overlap.py <consumer-fragment.json> [more.json ...]
+exit 0 = disjoint (invariant holds); exit 1 = overlap (invariant violated);
+exit 2 = usage / unreadable input.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+STATE = HERE / "meta-bridge-state.py"
+
+
+def die(msg: str, code: int = 2) -> "None":
+    print(f"check-keyset-overlap: {msg}", file=sys.stderr)
+    raise SystemExit(code)
+
+
+def pi_owned_paths() -> list[str]:
+    """Flat dotted key paths entwurf owns, from the state-manager SSOT."""
+    try:
+        out = subprocess.run(
+            [sys.executable, str(STATE), "managed-keys"],
+            check=True,
+            capture_output=True,
+            text=True,
+        ).stdout
+    except subprocess.CalledProcessError as exc:  # pragma: no cover - defensive
+        die(f"could not read pi managed-keys SSOT: {exc.stderr.strip() or exc}")
+    data = json.loads(out)
+    paths: list[str] = []
+    for scope in ("settings", "claudeRoot"):
+        for _kind, keys in data.get(scope, {}).items():
+            paths.extend(keys)
+    return paths
+
+
+def flatten(obj: object, prefix: str = "") -> list[str]:
+    """Leaf dotted paths of a JSON object. Arrays/scalars are leaves."""
+    if isinstance(obj, dict) and obj:
+        out: list[str] = []
+        for key, value in obj.items():
+            path = f"{prefix}.{key}" if prefix else key
+            out.extend(flatten(value, path))
+        return out
+    return [prefix] if prefix else []
+
+
+def collides(pi_path: str, frag_path: str) -> bool:
+    """True if the two key paths refer to the same key or a nested ancestor."""
+    return (
+        pi_path == frag_path
+        or frag_path.startswith(pi_path + ".")
+        or pi_path.startswith(frag_path + ".")
+    )
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        die("usage: check-keyset-overlap.py <consumer-fragment.json> [more.json ...]")
+
+    pi_paths = pi_owned_paths()
+    overlaps: list[str] = []
+    for raw in sys.argv[1:]:
+        path = Path(raw)
+        if not path.exists():
+            die(f"fragment not found: {path}")
+        try:
+            fragment = json.loads(path.read_text())
+        except (OSError, json.JSONDecodeError) as exc:
+            die(f"unreadable fragment {path}: {exc}")
+        if not isinstance(fragment, dict):
+            die(f"fragment {path} root must be a JSON object")
+        frag_paths = flatten(fragment)
+        for frag in frag_paths:
+            for pi in pi_paths:
+                if collides(pi, frag):
+                    overlaps.append(f"{path.name}: consumer key '{frag}' collides with pi-owned '{pi}'")
+
+    if overlaps:
+        print("KEYSET OVERLAP — keyset-owner invariant violated:", file=sys.stderr)
+        for line in overlaps:
+            print(f"  FAIL: {line}", file=sys.stderr)
+        print(
+            "  Fix: remove the colliding key(s) from the consumer fragment; "
+            "entwurf owns them (see ./run.sh meta-bridge-managed-keys).",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"keyset disjoint ok: {len(sys.argv) - 1} fragment(s) vs {len(pi_paths)} pi-owned key(s), no overlap")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/check-mailbox-receipt-state.ts

@@ -0,0 +1,170 @@
+/**
+ * check-mailbox-receipt-state — deterministic gate for 0.11 Stage 0 step 3B:
+ * the mailbox receipt state schema + store. A real temp mailbox dir; no backend,
+ * no network, no hook. Safe in the `pnpm check` static floor.
+ *
+ * Proves the new receipt authority's home (`<mailbox>/<gardenId>/state.json`):
+ * pure schema round-trip + crash-on-malformed + strict keyset, then the fs store
+ * (stamp → persist → read-back) including the observable result GPT named for
+ * 3B — "read receipt가 record.delivery가 아니라 mailbox state로: stamp 후 state를
+ * 보면 lastReadAt가 남는다". ENTWURF_META_MAILBOX_DIR / explicit mailboxDir keep this
+ * off the operator's real ~/.pi/agent/meta-mailbox.
+ *
+ * Scope is 3B ONLY: schema + store. The live enqueue/read dual-write and the
+ * record.delivery removal land in step 3D (NEXT.md 끊을 지점 ②) — no live-path
+ * assertions here, and wakeMode/deliveryLevel (capability, step 3C) are out.
+ */
+
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+	emptyMailboxReceiptState,
+	type MailboxReceiptField,
+	MetaRecordError,
+	mailboxReceiptStatePath,
+	parseMailboxReceiptState,
+	readMailboxReceiptState,
+	serializeMailboxReceiptState,
+	stampMailboxReceipt,
+} from "../pi-extensions/lib/meta-session.ts";
+
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	assert.ok(cond, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+function golden(label: string, actual: unknown, expected: unknown): void {
+	assert.deepStrictEqual(actual, expected, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+function throws(label: string, fn: () => unknown): void {
+	assert.throws(fn, MetaRecordError, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+const GID = "20260301T120000-abc123";
+const tmpRoot = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "psa-receipt-")));
+const mailboxDir = path.join(tmpRoot, "meta-mailbox");
+
+try {
+	// --- pure schema ---------------------------------------------------------
+	const empty = emptyMailboxReceiptState(GID);
+	golden("emptyMailboxReceiptState: schema v1, gardenId, all timestamps null", empty, {
+		schemaVersion: 1,
+		gardenId: GID,
+		lastEnqueuedAt: null,
+		lastDeliveredAt: null,
+		lastReadAt: null,
+	});
+
+	const seeded = { ...empty, lastEnqueuedAt: "2026-03-01T12:00:00.000Z", lastReadAt: "2026-03-01T12:05:00.000Z" };
+	golden(
+		"serialize → parse round-trips deep-equal",
+		parseMailboxReceiptState(serializeMailboxReceiptState(seeded)),
+		seeded,
+	);
+	ok(
+		"serialize: stable key order, 2-space indent, trailing newline",
+		serializeMailboxReceiptState(empty) ===
+			`{\n  "schemaVersion": 1,\n  "gardenId": "${GID}",\n  "lastEnqueuedAt": null,\n  "lastDeliveredAt": null,\n  "lastReadAt": null\n}\n`,
+	);
+
+	// --- crash, don't warn ---------------------------------------------------
+	throws("parse: invalid JSON throws", () => parseMailboxReceiptState("{not json"));
+	throws("parse: array (non-object) throws", () => parseMailboxReceiptState("[]"));
+	throws("parse: wrong schemaVersion throws", () =>
+		parseMailboxReceiptState(JSON.stringify({ ...empty, schemaVersion: 2 })),
+	);
+	throws("parse: malformed gardenId throws", () =>
+		parseMailboxReceiptState(JSON.stringify({ ...empty, gardenId: "nope" })),
+	);
+	throws("parse: non-string/non-null timestamp throws", () =>
+		parseMailboxReceiptState(JSON.stringify({ ...empty, lastReadAt: 123 })),
+	);
+	// strict keyset — wakeMode is CAPABILITY (step 3C), never receipt state.
+	throws("parse: capability field `wakeMode` is rejected (not receipt state)", () =>
+		parseMailboxReceiptState(JSON.stringify({ ...empty, wakeMode: "self-fetch" })),
+	);
+
+	// --- path derivation -----------------------------------------------------
+	ok(
+		"mailboxReceiptStatePath = <mailbox>/<gardenId>/state.json",
+		mailboxReceiptStatePath(mailboxDir, GID) === path.join(mailboxDir, GID, "state.json"),
+	);
+
+	// --- fs store ------------------------------------------------------------
+	// absent → empty, and reading must NOT create the file (no side effect).
+	golden(
+		"readMailboxReceiptState: absent → empty state",
+		readMailboxReceiptState({ gardenId: GID, mailboxDir }),
+		empty,
+	);
+	ok(
+		"readMailboxReceiptState: absent read leaves no state.json on disk",
+		!fs.existsSync(mailboxReceiptStatePath(mailboxDir, GID)),
+	);
+
+	// THE 3B observable: stamp lastReadAt → state.json exists, lastReadAt set.
+	const afterRead = stampMailboxReceipt({
+		gardenId: GID,
+		mailboxDir,
+		field: "lastReadAt",
+		now: new Date("2026-03-01T12:05:00.000Z"),
+	});
+	ok("stamp lastReadAt: state.json created on first stamp", fs.existsSync(mailboxReceiptStatePath(mailboxDir, GID)));
+	ok(
+		"stamp lastReadAt: only lastReadAt set, others null (읽음이 남는다)",
+		afterRead.lastReadAt === "2026-03-01T12:05:00.000Z" &&
+			afterRead.lastEnqueuedAt === null &&
+			afterRead.lastDeliveredAt === null,
+	);
+	golden(
+		"read-back equals the stamped state (persisted to disk)",
+		readMailboxReceiptState({ gardenId: GID, mailboxDir }),
+		afterRead,
+	);
+
+	// field isolation: a second stamp touches only its field, retains the first.
+	const afterEnqueue = stampMailboxReceipt({
+		gardenId: GID,
+		mailboxDir,
+		field: "lastEnqueuedAt",
+		now: new Date("2026-03-01T12:10:00.000Z"),
+	});
+	ok(
+		"stamp lastEnqueuedAt: retains lastReadAt, sets lastEnqueuedAt, lastDeliveredAt still null",
+		afterEnqueue.lastReadAt === "2026-03-01T12:05:00.000Z" &&
+			afterEnqueue.lastEnqueuedAt === "2026-03-01T12:10:00.000Z" &&
+			afterEnqueue.lastDeliveredAt === null,
+	);
+
+	// atomic write leaves no .tmp residue in the citizen dir.
+	const citizenDir = path.join(mailboxDir, GID);
+	ok("stamp is atomic: no .tmp residue left behind", !fs.readdirSync(citizenDir).some((f) => f.includes(".tmp-")));
+
+	// Blocker 1 — body/path gardenId drift is corruption (body is SSOT). Plant a
+	// state.json whose body claims a DIFFERENT citizen under GID's path; reading
+	// it back by GID must fail-fast, not silently return the wrong identity.
+	const OTHER = "20260301T120000-def456";
+	const driftFile = mailboxReceiptStatePath(mailboxDir, GID);
+	fs.writeFileSync(driftFile, serializeMailboxReceiptState(emptyMailboxReceiptState(OTHER)));
+	throws("readMailboxReceiptState: body/path gardenId drift is corruption", () =>
+		readMailboxReceiptState({ gardenId: GID, mailboxDir }),
+	);
+
+	// Blocker 2 — stamp field runtime validation (the TS type does not survive a
+	// JS/cast call site). An unknown field must crash, not create a stray key.
+	throws("stampMailboxReceipt rejects an unknown receipt field", () =>
+		// cast bypasses the TS field type on purpose, to prove the runtime guard
+		stampMailboxReceipt({ gardenId: OTHER, mailboxDir, field: "lastBogusAt" as unknown as MailboxReceiptField }),
+	);
+} finally {
+	fs.rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+console.log(`[check-mailbox-receipt-state] ${passed} assertions ok`);