@augurworks/augur 0.15.1

package/scripts/shoot.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+// shoot.mjs — capture optimized WebP poster screenshots for prototype/page/component
+// cards. Renders each entry index.html headlessly and writes preview.webp into its
+// folder (OVERWRITING any old one), optimized via cwebp. build.js then renders an
+// <img> poster instead of a live <iframe> preview — far cheaper — and falls back to
+// a live iframe for anything without a poster yet.
+//
+// Rendered from source over file:// so the injected companion/review overlay are
+// absent (their absolute /piti.js, /__review paths simply don't resolve) and the
+// poster is a clean shot of the prototype itself.
+//
+// Usage:
+//   npm run shoot                       # (re)shoot every card target
+//   npm run shoot -- --stale            # only targets whose source changed (or no poster)
+//   npm run shoot -- <path/to/folder>   # just one folder (must hold an entry .html)
+//
+// `--stale` is what `npm run posters` uses: it compares each folder's newest source
+// file against its preview.webp and reshoots only what actually changed. Posters are
+// COMMITTED IN THE SPACE REPOS — run this from a workspace of sibling clones (so targets
+// resolve to the editable sibling clones), then commit/push the space repo.
+//
+// Requires: playwright (devDep) + cwebp on PATH (`brew install webp`).
+
+import { chromium } from "playwright";
+import { promises as fs } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+const execFileP = promisify(execFile);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const VIEWPORT = { width: 1280, height: 800 }; // 16:10 — matches the card aspect ratio
+const WEBP_W = 768; // shown at ≤260px; 768px covers 2–3× DPR crisply
+const WEBP_Q = 72;
+
+async function exists(p) { try { await fs.access(p); return true; } catch { return false; } }
+async function isDir(p) { try { return (await fs.stat(p)).isDirectory(); } catch { return false; } }
+
+// Entry HTML for a folder: index.html, else the first .html.
+async function entry(dir) {
+  if (await exists(path.join(dir, "index.html"))) return path.join(dir, "index.html");
+  const es = await fs.readdir(dir, { withFileTypes: true });
+  const h = es.find((e) => e.isFile() && e.name.endsWith(".html"));
+  return h ? path.join(dir, h.name) : null;
+}
+
+// A canvas board can't be shot from source: its entry html is a thin shell that
+// loads /__canvas/canvas.js by absolute path (dead over file://) and the board
+// content lives in the instance's KV (GET /__board — a public route). Canvas
+// folders are shot from the LIVE page instead — strictly read-only: the room
+// socket is stubbed at the constructor (upgrades bypass route interception), in
+// EVERY frame, because a tile can embed another canvas which would join ITS room
+// and haunt presence; POST /__board is answered locally; the overlay/companion
+// scripts are blocked for the same clean-shot reason source shots use file://.
+// No siteOrigin, offline, or a gate answering the URL → skip, keeping whatever
+// poster is committed.
+async function isCanvasEntry(file) {
+  try { return /\/__canvas\/canvas\.js/.test(await fs.readFile(file, "utf8")); } catch { return false; }
+}
+
+// A card folder's live URL: walk up to its space root (space.json), mount the
+// default space at "/" and others at "/<id>/" (build.js's rule), and drop the
+// on-disk "prototypes/" segment (<opp>/prototypes/<name> ships at /<opp>/<name>/).
+async function liveUrl(dir) {
+  let root = dir;
+  while (root !== path.dirname(root) && !(await exists(path.join(root, "space.json")))) root = path.dirname(root);
+  let meta;
+  try { meta = JSON.parse(await fs.readFile(path.join(root, "space.json"), "utf8")); } catch { return null; }
+  const origin = typeof meta.siteOrigin === "string" ? meta.siteOrigin.replace(/\/+$/, "") : "";
+  if (!origin) return null;
+  const parts = path.relative(root, dir).split(path.sep);
+  if (parts[1] === "prototypes") parts.splice(1, 1);
+  const base = meta.default ? "" : `/${meta.id}`;
+  return `${origin}${base}/${parts.map(encodeURIComponent).join("/")}/`;
+}
+
+async function shootLiveCanvas(browser, dir, rel) {
+  const live = await liveUrl(dir);
+  if (!live) { console.log("· skip (canvas, no siteOrigin):", rel); return false; }
+  // Reachability first: the gate answers unknown or locked paths with its own
+  // login HTML, which must never become a poster.
+  let shell = "";
+  try { shell = await (await fetch(live)).text(); } catch {}
+  if (!/\/__canvas\/canvas\.js/.test(shell)) {
+    console.log("· skip (canvas gated/unpublished/offline):", rel, "→", live);
+    return false;
+  }
+  const tmp = path.join(os.tmpdir(), "shoot-" + rel.replace(/[^a-z0-9]+/gi, "-") + ".png");
+  const outWebp = path.join(dir, "preview.webp");
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    const page = await browser.newPage({ viewport: VIEWPORT });
+    try {
+      await page.addInitScript(() => {
+        window.WebSocket = class {
+          constructor() {
+            this.readyState = 3;
+            setTimeout(() => { if (this.onerror) this.onerror(new Event("error")); if (this.onclose) this.onclose(new Event("close")); }, 0);
+          }
+          addEventListener(type, fn) { if (type === "error" || type === "close") setTimeout(() => fn(new Event(type)), 0); }
+          removeEventListener() {} send() {} close() {}
+        };
+      });
+      await page.route("**/__board*", (r) =>
+        r.request().method() === "POST" ? r.fulfill({ status: 204, body: "" }) : r.continue());
+      await page.route("**/piti*", (r) => r.abort());
+      await page.route("**/__review/**", (r) => r.abort());
+      await page.goto(live, { waitUntil: "load", timeout: 30000 });
+      // Board fetch + node paint; an empty board is legitimate, so a miss just shoots.
+      await page.waitForFunction(() => window.GVCanvas && window.GVCanvas.nodes && window.GVCanvas.nodes().length > 0, { timeout: 15000 }).catch(() => {});
+      await page.waitForTimeout(2500); // tiles/images/fonts settle
+      // Editing chrome (toolbar/topbar/zoom — all inside #gvc-ui) is not board
+      // content; frame the whole board rather than whatever camera was saved last.
+      await page.addStyleTag({ content: "#gvc-ui { display: none !important; }" });
+      await page.evaluate(() => { try { window.GVCanvas.fit({ cover: true }); } catch {} });
+      await page.waitForTimeout(700); // fit() animates ~320ms; let tiles re-rasterize
+      await page.screenshot({ path: tmp, clip: { x: 0, y: 0, ...VIEWPORT } });
+      const png = await fs.stat(tmp).catch(() => null);
+      if (!png || png.size === 0) throw new Error("empty screenshot");
+      await execFileP("cwebp", ["-quiet", "-q", String(WEBP_Q), "-resize", String(WEBP_W), "0", tmp, "-o", outWebp]);
+      const kb = Math.round((await fs.stat(outWebp)).size / 1024);
+      console.log("✓", rel + "/preview.webp", kb + "KB (live canvas)");
+      return true;
+    } catch (e) {
+      const msg = e.message.split("\n")[0];
+      if (attempt < 2) { console.log("· retry", rel, "—", msg); continue; }
+      console.log("✗ FAIL", rel, "—", msg);
+      return false;
+    } finally {
+      await page.close().catch(() => {});
+      await fs.unlink(tmp).catch(() => {});
+    }
+  }
+  return false;
+}
+
+// Folders inside a space root that never hold card targets.
+// Extend via GV_SCAN_IGNORE (comma-separated dir names) for space-specific bulk dirs.
+const IGNORE = new Set(["node_modules", "skills", "scripts", "registry", ".git", ".github", ".claude",
+  ...(process.env.GV_SCAN_IGNORE || "").split(",").filter(Boolean)]);
+
+// Space roots to scan. One repo per space: card targets live inside each space repo.
+// Prefer the EDITABLE sibling clones (../<x> with a space.json at its root — a shot
+// poster can be committed + pushed from there); fall back to the pinned spaces/<id>
+// mirrors (posters shot there can't be pushed — run from the sibling-clone workspace).
+async function spaceRoots() {
+  const roots = [];
+  for (const base of [path.join(ROOT, ".."), path.join(ROOT, "spaces")]) {
+    try {
+      for (const e of await fs.readdir(base, { withFileTypes: true })) {
+        if (!e.isDirectory() || e.name.startsWith(".")) continue;
+        if (await exists(path.join(base, e.name, "space.json"))) roots.push(path.join(base, e.name));
+      }
+    } catch {}
+    if (roots.length) break; // siblings found → don't also scan the pinned mirrors
+  }
+  return roots;
+}
+
+// Every folder that appears as a card on a shell page: each opportunity's prototypes,
+// plus the pages/, components/, base/, patterns/, playground/ groups — per space.
+async function targets() {
+  const out = [];
+  for (const root of await spaceRoots()) {
+    for (const t of await fs.readdir(root, { withFileTypes: true })) {
+      if (!t.isDirectory() || IGNORE.has(t.name) || t.name.startsWith(".")) continue;
+      const pp = path.join(root, t.name, "prototypes");
+      if (await isDir(pp)) {
+        for (const p of await fs.readdir(pp, { withFileTypes: true })) {
+          if (p.isDirectory()) out.push(path.join(pp, p.name));
+        }
+      }
+    }
+    for (const group of ["pages", "components", "base", "patterns", "playground"]) {
+      const g = path.join(root, group);
+      if (await isDir(g)) {
+        for (const e of await fs.readdir(g, { withFileTypes: true })) {
+          if (e.isDirectory() && !e.name.startsWith(".")) out.push(path.join(g, e.name));
+        }
+      }
+    }
+  }
+  return out;
+}
+
+// Newest mtime (ms) of any file in a folder tree, ignoring the poster itself.
+async function newestMtime(dir, ignore) {
+  let latest = 0;
+  for (const e of await fs.readdir(dir, { withFileTypes: true })) {
+    if (e.name === ignore) continue;
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) latest = Math.max(latest, await newestMtime(p, ignore));
+    else if (e.isFile()) latest = Math.max(latest, (await fs.stat(p)).mtimeMs);
+  }
+  return latest;
+}
+
+// A folder needs reshooting when it has no poster, or its source is newer than one.
+async function needsShoot(dir) {
+  const poster = path.join(dir, "preview.webp");
+  if (!(await exists(poster))) return true;
+  return (await newestMtime(dir, "preview.webp")) > (await fs.stat(poster)).mtimeMs;
+}
+
+async function shoot(browser, dir) {
+  const file = await entry(dir);
+  const rel = path.relative(ROOT, dir);
+  if (!file) { console.log("· skip (no html):", rel); return false; }
+  if (await isCanvasEntry(file)) return shootLiveCanvas(browser, dir, rel);
+  const tmp = path.join(os.tmpdir(), "shoot-" + rel.replace(/[^a-z0-9]+/gi, "-") + ".png");
+  const outWebp = path.join(dir, "preview.webp");
+  // Up to 2 attempts. Headless captures occasionally produce an empty/corrupt PNG
+  // that cwebp then can't read; previously the unguarded cwebp rejection crashed the
+  // whole run (aborting `npm run deploy`). Now any single-poster failure is caught and
+  // logged — the run keeps going and the existing committed poster is left in place —
+  // and a retry clears the common transient case.
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    const page = await browser.newPage({ viewport: VIEWPORT });
+    try {
+      await page.goto("file://" + file, { waitUntil: "load", timeout: 20000 });
+      await page.waitForTimeout(900); // let fonts/layout settle
+      await page.screenshot({ path: tmp, clip: { x: 0, y: 0, ...VIEWPORT } });
+      const png = await fs.stat(tmp).catch(() => null);
+      if (!png || png.size === 0) throw new Error("empty screenshot");
+      await execFileP("cwebp", ["-quiet", "-q", String(WEBP_Q), "-resize", String(WEBP_W), "0", tmp, "-o", outWebp]);
+      const kb = Math.round((await fs.stat(outWebp)).size / 1024);
+      console.log("✓", rel + "/preview.webp", kb + "KB");
+      return true;
+    } catch (e) {
+      const msg = e.message.split("\n")[0];
+      if (attempt < 2) { console.log("· retry", rel, "—", msg); continue; }
+      console.log("✗ FAIL", rel, "—", msg);
+      return false;
+    } finally {
+      await page.close().catch(() => {});
+      await fs.unlink(tmp).catch(() => {});
+    }
+  }
+  return false;
+}
+
+const argv = process.argv.slice(2);
+const staleOnly = argv.includes("--stale");
+const pathArg = argv.find((a) => !a.startsWith("--"));
+let list = pathArg ? [path.resolve(pathArg)] : await targets();
+
+if (staleOnly) {
+  const fresh = [];
+  for (const d of list) if (await needsShoot(d)) fresh.push(d);
+  const skipped = list.length - fresh.length;
+  if (skipped) console.log(`stale: ${skipped} poster(s) up to date · ${fresh.length} to (re)shoot`);
+  list = fresh;
+}
+
+if (!list.length) {
+  console.log("nothing to shoot — all posters current");
+} else {
+  const browser = await chromium.launch();
+  let ok = 0;
+  for (const d of list) if (await shoot(browser, d)) ok++;
+  await browser.close();
+  console.log(`\nshot ${ok}/${list.length} posters`);
+}

package/scripts/smoke-invite.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/*
+ * smoke-invite.mjs — the whole invite lifecycle in one pass, against an in-memory KV.
+ * The unit tests check each piece; this checks the SEQUENCE, which is what an operator
+ * actually walks through: pending → invite → accepted → login → reset → locked out.
+ *
+ * Usage: npm run smoke
+ */
+import assert from "node:assert/strict";
+import { __testables as W } from "../src/_worker.js";
+
+function memKV() {
+  const store = new Map();
+  return {
+    async get(k) { return store.has(k) ? store.get(k) : null; },
+    async put(k, v) { store.set(k, v); },
+    async delete(k) { store.delete(k); },
+  };
+}
+
+const kv = memKV();
+const env = { COMMENTS: kv, SESSION_SECRET: "smoke-secret" };
+const ADMIN = { email: "admin@smoke.test", name: "Admin", role: "admin" };
+// pass: "leaked-seed-2026" stands in for the legacy roster password migration is
+// revoking. Without it, effectiveSecret has nothing to fall back to, so a tombstone
+// (ov[email] = null) and an outright `delete ov[email]` both collapse to "" — steps
+// 6 and 7 would pass identically either way, and the reset-regresses-to-a-leak bug
+// this script exists to catch would sail straight through. Do not remove this field.
+const USER = { email: "user@smoke.test", name: "User", pass: "leaked-seed-2026" };
+// A fresh entry with no legacy password and no passHash — represents a genuinely new,
+// never-invited person. Asserts that the pending state is actually derivable.
+const FRESH = { email: "fresh@smoke.test", name: "Fresh" };
+const ROSTER = [ADMIN, USER, FRESH];
+const ORIGIN = "https://smoke.test";
+
+const post = (body) => new Request(`${ORIGIN}/__admin/users`, {
+  method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body),
+});
+const redeem = (token, password) => new Request(`${ORIGIN}/__invite`, {
+  method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" },
+  body: new URLSearchParams({ token, password }).toString(),
+});
+
+let step = 0;
+const ok = (m) => console.log(`  ${++step}. ${m}`);
+
+console.log("invite lifecycle:");
+
+// 1. A roster entry with a legacy password reads as accepted — that's the leaked
+// password this whole migration exists to revoke. "reset" (step 2) is what moves
+// them to pending. A fresh entry with no password reads as pending — that state
+// derivation must not be broken.
+let res = await W.adminUsersApi(new Request(`${ORIGIN}/__admin/users`), new URL(`${ORIGIN}/__admin/users`), env, ADMIN, ROSTER);
+let body = await res.json();
+assert.equal(body.users.find((u) => u.email === USER.email).state, "accepted");
+assert.equal(body.users.find((u) => u.email === FRESH.email).state, "pending");
+ok("legacy roster entry reads as accepted, fresh never-invited entry reads as pending");
+
+// 2. Reset mints a link.
+res = await W.adminUsersApi(post({ op: "reset", email: USER.email }), new URL(`${ORIGIN}/__admin/users`), env, ADMIN, ROSTER);
+body = await res.json();
+assert.equal(body.ok, true);
+const token = new URL(body.url).searchParams.get("t");
+ok("reset returns a single-use invite link");
+
+// 3. Redeeming sets a hash and signs in.
+res = await W.invitePost(redeem(token, "a properly long password"), new URL(`${ORIGIN}/__invite`), env, ROSTER);
+assert.equal(res.status, 303);
+assert.match(res.headers.get("Set-Cookie") || "", /^__Host-augur_user=/);
+const stored = JSON.parse(await kv.get("users:secrets"))[USER.email];
+assert.ok(W.isPassHash(stored), "stored as a hash");
+ok("redemption stores a hash and issues a session");
+
+// 4. The link is dead, and the reuse attempt didn't touch the stored secret. A status-only
+// check would miss a future reordering that starts mutating state before the token check.
+res = await W.invitePost(redeem(token, "another long password"), new URL(`${ORIGIN}/__invite`), env, ROSTER);
+assert.equal(res.status, 400);
+assert.equal(JSON.parse(await kv.get("users:secrets"))[USER.email], stored);
+ok("the link cannot be reused, and the stored secret is untouched by the attempt");
+
+// 5. The user now reads as accepted.
+res = await W.adminUsersApi(new Request(`${ORIGIN}/__admin/users`), new URL(`${ORIGIN}/__admin/users`), env, ADMIN, ROSTER);
+body = await res.json();
+assert.equal(body.users.find((u) => u.email === USER.email).state, "accepted");
+assert.ok(!JSON.stringify(body).includes("pbkdf2$"), "no secret leaks through the admin API");
+ok("state flips to accepted, no secret in the API response");
+
+// 6. The chosen password verifies; the session cookie identifies.
+assert.equal(await W.verifyPassword("a properly long password", stored), true);
+const sessionToken = await W.userToken(env, USER);
+const identified = await W.identify(
+  new Request(ORIGIN, { headers: { Cookie: `__Host-augur_user=${USER.email}.${sessionToken}` } }), env, ROSTER);
+assert.equal(identified && identified.email, USER.email);
+ok("password verifies and the session identifies the user");
+
+// 7. Reset again: this must write a TOMBSTONE, not a delete. Both make the session stop
+// verifying, so that check alone can't tell them apart — a regression from
+// `ov[email] = null` to `delete ov[email]` would sail through it, because effectiveSecret
+// only falls back to USER.pass ("leaked-seed-2026") when the key is ABSENT, and a fallback
+// to that leaked roster password is exactly the bug this reset exists to prevent. Assert
+// the raw stored state directly, not just the session outcome.
+await W.adminUsersApi(post({ op: "reset", email: USER.email }), new URL(`${ORIGIN}/__admin/users`), env, ADMIN, ROSTER);
+const secretsMap = JSON.parse(await kv.get("users:secrets"));
+assert.ok(Object.prototype.hasOwnProperty.call(secretsMap, USER.email), "key still present: a tombstone, not a deletion");
+assert.ok(!secretsMap[USER.email], "tombstoned value is falsy");
+const revokedSecret = await W.effectiveSecret(env, USER);
+assert.equal(revokedSecret, "");
+assert.notEqual(revokedSecret, "leaked-seed-2026", "must not fall back to the leaked roster password");
+assert.equal(await W.identify(
+  new Request(ORIGIN, { headers: { Cookie: `__Host-augur_user=${USER.email}.${sessionToken}` } }), env, ROSTER), null);
+ok("reset writes a tombstone (not a deletion), revokes the password with no fallback, and kills the live session");
+
+console.log("\nall good.");

package/scripts/state-inventory.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+// state-inventory — the inventory stays true, or the build stops.
+//
+// WHY. `src/state-inventory.mjs` is the authoritative map from every stored key to
+// where it goes in the migration off shared KV. A list like that rots by default: five
+// families appeared between its first draft and its second reading, and nothing caught
+// them. A family nobody remembers is a family nobody exports, and the first anyone hears
+// of it is a workspace arriving on its new home missing something.
+//
+// TWO MODES, because the two questions are different and only one of them can run in CI.
+//
+//   SOURCE (default, and what `check` runs). Every key-shaped constant and every literal
+//   handed to a store call in the engine must be accounted for, and every inventory entry
+//   must still appear in the source. No credentials, so it runs anywhere — and it catches
+//   the rot that actually happens, which is somebody adding a family in code.
+//
+//   LIVE (`--live <file>`). Every key on a real instance must be accounted for. This is
+//   the one the plan item asks for and it needs a KV listing, which needs an account
+//   credential CI does not have:
+//
+//     npx wrangler kv key list --namespace-id <id> --remote > /tmp/keys.json
+//     node scripts/state-inventory.mjs --live /tmp/keys.json
+//
+//   Run it before a migration, not on a schedule. What it finds that the source scan
+//   cannot is a key written by something that is no longer in the engine at all.
+//
+// WHAT THIS IS NOT: a parser. It reads literals, so a key assembled at runtime from pieces
+// it cannot see is a key it cannot see either — the same floor `wrangler-preflight.mjs`
+// stands on, and stated for the same reason. The LIVE mode is what closes that gap.
+//
+// Usage: node scripts/state-inventory.mjs [--live <file>] [--print] [--quiet]
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { STATE_INVENTORY, accountsFor, inventoryEntry } from "../src/state-inventory.mjs";
+import { IDENTITY_KV_FAMILIES, UNMAPPED_WORKSPACE_FAMILIES } from "../src/kv-identity.mjs";
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const SOURCES = ["src/_worker.js", "src/mail.mjs"];
+
+const argv = process.argv.slice(2);
+const quiet = argv.includes("--quiet");
+const liveArg = argv[argv.indexOf("--live") + 1];
+const live = argv.includes("--live") ? liveArg : null;
+
+/**
+ * Every key-ish literal the engine names, as a set.
+ *
+ * Four shapes, and only four, because each is a place a key can be WRITTEN DOWN:
+ *   · a module-scope `const SOMETHING_KEY = "…"` or `_PREFIX`
+ *   · a `doc: "…"` inside the overlay's family table
+ *   · a string handed straight to a store call
+ *   · a template handed straight to a store call, with its holes blanked
+ * Anything else is a key built out of pieces, which the live mode is for.
+ */
+export function keysInSource(text) {
+  const found = new Map(); // literal -> the line it was found on
+  const add = (lit, line) => { if (lit && !found.has(lit)) found.set(lit, line); };
+  const lineOf = (idx) => text.slice(0, idx).split("\n").length;
+
+  for (const m of text.matchAll(/^const\s+([A-Z0-9_]*_(?:KEY|PREFIX))\s*=\s*"([^"]+)"/gm)) {
+    add(m[2], lineOf(m.index));
+  }
+  for (const m of text.matchAll(/^export const\s+([A-Z0-9_]*_(?:KEY|PREFIX))\s*=\s*"([^"]+)"/gm)) {
+    add(m[2], lineOf(m.index));
+  }
+  for (const m of text.matchAll(/\bdoc:\s*"([^"]+)"/g)) {
+    // The overlay family table stores the document NAME; the keys it composes are
+    // `<doc>:<something>`, so record the prefix form the inventory carries.
+    add(m[1] + ":", lineOf(m.index));
+    add(m[1], lineOf(m.index));
+  }
+  // The receiver has to be a STORE, or this reads every header name and query parameter in
+  // the file: `headers.get("Cookie")` is the same call shape as `kv.get("statuses")`.
+  // These four names are what the engine calls its stores, and a fifth would be caught by
+  // the live mode rather than silently skipped.
+  const RECEIVER = String.raw`(?:kv|r2|bundles|env\.BUNDLES|env\.COMMENTS)`;
+  for (const m of text.matchAll(new RegExp(RECEIVER + String.raw`\.(?:get|put|delete|head|getWithMetadata)\(\s*"([^"]+)"`, "g"))) {
+    add(m[1], lineOf(m.index));
+  }
+  for (const m of text.matchAll(new RegExp(RECEIVER + String.raw`\.(?:get|put|delete|head|getWithMetadata)\(\s*` + "`([^`]+)`", "g"))) {
+    add(m[1].replace(/\$\{[^}]*\}/g, "*"), lineOf(m.index));
+  }
+  for (const m of text.matchAll(new RegExp(RECEIVER + String.raw`\.list\(\{\s*prefix:\s*` + "[`\"]([^`\"]+)[`\"]", "g"))) {
+    add(m[1].replace(/\$\{[^}]*\}/g, "*"), lineOf(m.index));
+  }
+  for (const m of text.matchAll(/const\s+\w+\s*=\s*`([a-z][a-z0-9:_-]*:)\$\{/g)) {
+    // `const sentKey = \`rebake:sent:${id}\`` — a prefix written as a template.
+    add(m[1], lineOf(m.index));
+  }
+  return found;
+}
+
+/**
+ * The inventory entries a literal accounts for — plural, because one literal can.
+ *
+ * A trailing colon is not a distinction: `statuses` and `statuses:` are the same family
+ * written two ways, and the overlay's family table writes the second. A DOCUMENT NAME
+ * covers every key under it, which is how `pt` accounts for both `pt:view` and
+ * `pt:remarks`. And a composed key (`spaces/*​/manifest.json`) belongs to its prefix.
+ */
+function accountedBy(lit) {
+  const star = lit.indexOf("*");
+  const head = star === -1 ? lit : lit.slice(0, star);
+  const bare = head.replace(/:$/, "");
+  const out = new Set();
+  for (const f of [lit, head, lit.replace(/:$/, ""), bare, bare + ":"]) {
+    const direct = inventoryEntry(f);
+    if (direct) out.add(direct.id);
+  }
+  // A document name ALSO stands for every key beneath it, and it can do both at once:
+  // `pins` is a document AND a prefix, because a signed-out visitor's pins live under the
+  // bare name while everybody else's live under `pins:<address>`. Collecting both is what
+  // stops the second one being reported as an entry nothing names.
+  for (const e of STATE_INVENTORY) if (e.id.startsWith(bare + ":")) out.add(e.id);
+  if (out.size) return [...out];
+  const covering = accountsFor(head);
+  return covering ? [covering.id] : [];
+}
+
+const problems = [];
+
+if (live) {
+  const raw = fs.readFileSync(live === "-" ? 0 : live, "utf8");
+  let keys;
+  try {
+    const doc = JSON.parse(raw);
+    keys = (Array.isArray(doc) ? doc : doc.result || []).map((k) => (typeof k === "string" ? k : k.name));
+  } catch (e) {
+    keys = raw.split("\n").map((l) => l.trim()).filter(Boolean);
+  }
+  if (!keys.length) {
+    console.error("state-inventory: that listing is empty — a vacuous pass is not a pass");
+    process.exit(2);
+  }
+  const unaccounted = new Map();
+  for (const k of keys) {
+    if (accountsFor(k)) continue;
+    // Report the SHAPE, not every key: a thousand orphans under one prefix is one problem.
+    const shape = k.replace(/[0-9a-f]{8,}/gi, "<hash>").replace(/[^:/]+@[^:/]+/g, "<address>");
+    unaccounted.set(shape, (unaccounted.get(shape) || 0) + 1);
+  }
+  for (const [shape, n] of unaccounted) {
+    problems.push(`live key not in the inventory: ${shape}${n > 1 ? ` (${n} of them)` : ""}`);
+  }
+  if (!problems.length && !quiet) {
+    console.log(`state-inventory: OK — all ${keys.length} live key(s) are accounted for`);
+  }
+} else {
+  const seen = new Set();
+  for (const rel of SOURCES) {
+    const abs = path.join(ROOT, rel);
+    if (!fs.existsSync(abs)) continue;
+    for (const [lit, line] of keysInSource(fs.readFileSync(abs, "utf8"))) {
+      const ids = accountedBy(lit);
+      if (!ids.length) {
+        problems.push(`${rel}:${line}: "${lit}" is not in the inventory. Add it to src/state-inventory.mjs with a destination and a reason — including "not a store key", if that is what it is.`);
+        continue;
+      }
+      for (const id of ids) seen.add(id);
+    }
+  }
+  // And the other direction: an entry nothing names any more is an entry to delete, or a
+  // family that quietly stopped being written and is about to be forgotten.
+  for (const e of STATE_INVENTORY) {
+    if (!seen.has(e.id)) {
+      problems.push(`the inventory lists "${e.id}" but nothing in the engine names it. Delete the entry, or find out what stopped writing it.`);
+    }
+  }
+
+  // ── A THIRD DIRECTION: does what the inventory PROMISES actually have somewhere to go? ──
+  //
+  // The two checks above keep the list and the code agreeing about what EXISTS. Neither
+  // asks whether a family the inventory sends to the workspace object can actually be
+  // stored there. `mail:suppressed` was `to: "workspace"` for weeks with no table to land
+  // in, and its own entry says dropping it "breaks that promise silently" — a copy would
+  // have run, reported success, and left an instance ready to resume mailing addresses a
+  // provider had already told it to stop mailing.
+  //
+  // A family is landable when the overlay accessor knows it (content), when the identity
+  // translation reads it, or when it is declared unmapped WITH A REASON. The third is not
+  // a loophole: it is the difference between a decision somebody made and a gap nobody saw.
+  const overlayDocs = new Set();
+  {
+    const src = fs.readFileSync(path.join(ROOT, "src/_worker.js"), "utf8");
+    const block = /const OVERLAY_KV_KEYS = Object\.freeze\(\{([\s\S]*?)\n\}\);/.exec(src);
+    if (!block) {
+      problems.push("could not find OVERLAY_KV_KEYS in src/_worker.js — this check reads it to know which families the overlay accessor handles, so its shape moving is a problem in itself.");
+    } else {
+      for (const m of block[1].matchAll(/doc:\s*"([^"]+)"/g)) overlayDocs.add(m[1]);
+    }
+  }
+  const landsInOverlay = (id) =>
+    [...overlayDocs].some((d) => d === id || `${d}:` === id || id.startsWith(`${d}:`));
+
+  for (const e of STATE_INVENTORY) {
+    if (e.to !== "workspace") continue;
+    if (landsInOverlay(e.id)) continue;
+    if (IDENTITY_KV_FAMILIES.includes(e.id)) continue;
+    if (Object.prototype.hasOwnProperty.call(UNMAPPED_WORKSPACE_FAMILIES, e.id)) continue;
+    problems.push(
+      `"${e.id}" is to: "workspace" and has nowhere to land. It is not an overlay family, ` +
+      `src/kv-identity.mjs does not read it, and it is not declared in UNMAPPED_WORKSPACE_FAMILIES. ` +
+      `A copy would run, report success, and silently omit it. Give it a home or declare it unmapped with a reason.`,
+    );
+  }
+  if (!problems.length && !quiet) {
+    console.log(`state-inventory: OK — ${STATE_INVENTORY.length} entries, every one named by the engine and every named key accounted for`);
+  }
+}
+
+if (argv.includes("--print")) {
+  const w = Math.max(...STATE_INVENTORY.map((e) => e.id.length));
+  for (const e of STATE_INVENTORY) {
+    console.log(`${e.id.padEnd(w)}  ${e.store.padEnd(4)} ${e.kind.padEnd(6)} → ${e.to}`);
+  }
+}
+
+if (problems.length) {
+  for (const p of problems) console.log(`  ${p}`);
+  console.log(`\n${problems.length} problem(s). The inventory is the migration's only complete list of what exists; a family missing from it is a family nobody exports.`);
+  process.exit(1);
+}