@augurworks/augur 0.15.1

package/scripts/mark.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * augur mark — say what you are about to work on, and read what everyone else is.
+ *
+ *   augur mark                       what is being worked on right now
+ *   augur mark <path> [--ttl <s>]    leave a mark on it, then start
+ *   augur mark <path> --clear        take yours down early
+ *   augur mark … --json              the same answer, for a tool to read
+ *
+ * `F-presence-marks`. Nothing anywhere said what was already being worked on. Two agents
+ * on two machines, both told to improve the checkout flow, would each open the folder,
+ * each edit it, and find out at publish time — where the answer is a fork and a conflict
+ * file nobody asked for.
+ *
+ * ⚠️ THIS IS NOT A LOCK AND IT MUST NEVER BECOME ONE. Marking a path grants nothing and
+ * refuses nothing: a marked path can still be edited, published and shipped by anybody, and
+ * this command exits 0 whatever it finds. The protocol is social and it is one sentence —
+ * READ THE MARKS BEFORE YOU START, LEAVE ONE WHEN YOU DO. What happens when coordination
+ * fails anyway is the composed publish's problem, and it settles it on evidence rather than
+ * on a claim.
+ *
+ * ⚠️ AND IT EXPIRES BY ITSELF. A mark carries how long it is good for — ten minutes by
+ * default, an hour at the most — and the instance stops reporting it the moment that
+ * passes, whether or not anything ever clears it. That is the point rather than a detail:
+ * the thing leaving marks is a process that can be killed, and a claim that outlives the
+ * claimant is worse than no claim at all. `--clear` is a courtesy, never the guarantee.
+ *
+ * A path is a URL path (`/checkout/flow/`). A repo folder is accepted and translated, so
+ * `checkout/prototypes/flow` — the folder you were just editing — marks the URL it
+ * publishes to. The line printed back is always the instance's own spelling.
+ */
+import { target, apiClient } from "./lib/store.mjs";
+import { fetchMarks, markPathFor, othersOverlapping, markLine, forAnother } from "./lib/marks.mjs";
+
+const C = { dim: "\x1b[2m", ok: "\x1b[32m", warn: "\x1b[33m", off: "\x1b[0m" };
+const log = (m) => console.log(`\x1b[35m[mark]\x1b[0m ${m}`);
+const die = (m) => { console.error(`\x1b[31m[mark] ${m}\x1b[0m`); process.exit(1); };
+
+const argv = process.argv.slice(2);
+const flag = (n) => argv.includes(n);
+const opt = (n, d = null) => { const i = argv.indexOf(n); return i > -1 && argv[i + 1] ? argv[i + 1] : d; };
+const JSON_OUT = flag("--json");
+const CLEAR = flag("--clear");
+const positional = argv.filter((a, i) => !a.startsWith("--") && !(i > 0 && argv[i - 1] === "--ttl"));
+
+async function main() {
+  const { origin, token } = target({ needToken: true });
+  const req = apiClient(origin, token);
+
+  const raw = positional[0] || "";
+  const path = raw ? markPathFor(raw) : "";
+  if (raw && !path) die(`"${raw}" is not a path anything could be working on.`);
+
+  // ── list ──────────────────────────────────────────────────────────────────
+  if (!path) {
+    const marks = await fetchMarks(req);
+    if (JSON_OUT) { console.log(JSON.stringify({ origin, marks }, null, 2)); return; }
+    if (!marks.length) { log(`${C.dim}nobody is working on anything at ${origin} right now${C.off}`); return; }
+    log(`being worked on at ${origin}:`);
+    for (const m of marks) console.log(`  ${markLine(m)}`);
+    console.log(`\n${C.dim}Nothing here stops you. Pick a different path, or go ahead and expect to merge.${C.off}`);
+    return;
+  }
+
+  // ── clear ─────────────────────────────────────────────────────────────────
+  if (CLEAR) {
+    const r = await req("_marks/clear", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ path }),
+    });
+    const body = await r.json();
+    if (JSON_OUT) { console.log(JSON.stringify({ origin, path, ...body }, null, 2)); return; }
+    if (body.cleared) log(`${C.ok}${path} released${C.off}`);
+    else if (body.reason === "not-yours") log(`${C.dim}${path} is somebody else's mark — left alone. It expires on its own.${C.off}`);
+    else log(`${C.dim}no mark of yours on ${path}${C.off}`);
+    return;
+  }
+
+  // ── set ───────────────────────────────────────────────────────────────────
+  const ttlArg = opt("--ttl");
+  const ttl = ttlArg ? Math.round(Number(ttlArg) * 1000) : undefined;
+  if (ttlArg && !Number.isFinite(ttl)) die(`--ttl takes seconds, not "${ttlArg}".`);
+
+  // WHO ELSE IS ALREADY HERE — read BEFORE writing, because that is the whole protocol and
+  // an agent that only ever writes is an agent that has learned nothing. Taken before the
+  // write and not after: the write replaces the row for this path, so a read afterwards
+  // could no longer see the person this is worth telling you about.
+  const before = await fetchMarks(req);
+
+  const r = await req("_marks/set", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ path, ...(ttl ? { ttl } : {}) }),
+  });
+  const body = await r.json();
+  if (body.error) die(`${origin} refused the mark: ${body.error}`);
+
+  // Who was already here that is not you. The rule, and the trap inside it, are on
+  // `othersOverlapping` — it is a pure function precisely so the trap has a test.
+  const overlapping = othersOverlapping(before, body.mark.path, body.mark.personId);
+
+  if (JSON_OUT) { console.log(JSON.stringify({ origin, overlapping, ...body }, null, 2)); return; }
+  log(`${C.ok}${body.mark.path}${C.off} marked ${forAnother(body.mark.expiresIn)}`);
+  if (overlapping.length) {
+    console.log(`\n  ${C.warn}somebody is already working here${C.off}`);
+    for (const m of overlapping) console.log(`  ${markLine(m)}`);
+    console.log(`\n${C.dim}Your mark went down anyway — marks never refuse. Pick a different path, wait it out, or carry on knowing you will be merging.${C.off}`);
+  }
+}
+
+main().catch((e) => die(e && e.stack ? e.stack : String(e)));

package/scripts/migrate-board-keys.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * migrate-board-keys — give every board document in a KV namespace its workspace segment.
+ *
+ *   CLOUDFLARE_API_TOKEN=… CLOUDFLARE_ACCOUNT_ID=… AUGUR_KV_NS=… \
+ *     node scripts/migrate-board-keys.mjs --workspace <id> [--apply] [--json]
+ *
+ * A ONE-SHOT, and the least important half of the change it belongs to. `board:<path>`
+ * becomes `board:<workspace>:<path>` on the deploy that moves an instance's canvas rooms
+ * into its own worker; the worker READS THROUGH on a miss and writes the document back
+ * scoped, so every board migrates itself the first time anybody opens it and nothing is
+ * ever unreachable. What this script buys is that the migration finishes for the boards
+ * nobody opens — a board read once a quarter would otherwise keep a legacy key alive
+ * indefinitely, and the fallback can only be retired when nothing depends on it.
+ *
+ * ⚠️ DRY RUN IS THE DEFAULT. Writing needs `--apply`, spelled out, because the destination
+ * is a live namespace and the failure mode is silent: a wrong `--workspace` writes every
+ * board under a name nothing resolves to, and the site keeps working (the read-through
+ * still finds the legacy key) while a second, stale copy of every board accumulates.
+ *
+ * IT COPIES AND DOES NOT DELETE, on purpose. The legacy key is left exactly where it is:
+ * rolling the deploy back has to leave the boards reachable, and a migration that has
+ * removed the thing it migrated is not reversible. Sweeping the legacy keys is a separate
+ * decision for a separate day, once the read-through has been off for longer than anyone's
+ * memory of a board.
+ *
+ * WHAT IT REPORTS, and why the numbers are the point:
+ *   scanned    legacy `board:` keys found (a scoped key is not one)
+ *   identical  already present at the scoped key with the SAME bytes — nothing to do
+ *   differing  present at the scoped key with DIFFERENT bytes — SKIPPED and named. The
+ *              scoped copy is the newer one by construction (only the current code writes
+ *              it), so overwriting it with the legacy document would revert a live board.
+ *   copied     written (or, on a dry run, would be)
+ *
+ * A dry run that reports `differing: 0` is the acceptance test: it says the batch is a pure
+ * addition, that no board is about to be reverted, and that the read-through and the direct
+ * path resolve the same bytes for every board in the namespace.
+ *
+ * Values are copied VERBATIM as bytes — never parsed, never re-serialised. A board document
+ * is JSON today and a migration that parses is a migration that fails on the one document
+ * that is not what it expected.
+ */
+import { BOARD_PREFIX, boardKvKey } from "../src/board-key.mjs";
+
+const args = process.argv.slice(2);
+const flag = (f) => args.includes(f);
+const opt = (f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : null; };
+
+const WORKSPACE = (opt("--workspace") || process.env.AUGUR_WORKSPACE || "").trim();
+const APPLY = flag("--apply");
+const JSON_OUT = flag("--json");
+
+const ACC = process.env.CLOUDFLARE_ACCOUNT_ID;
+const TOK = process.env.CLOUDFLARE_API_TOKEN;
+const NS = process.env.AUGUR_KV_NS || process.env.KV_NAMESPACE_ID || process.env.GV_KV_NS;
+
+const log = (m) => console.error(`\x1b[36m[board-keys]\x1b[0m ${m}`);
+const die = (m) => { log(`\x1b[31m${m}\x1b[0m`); process.exit(1); };
+
+// Overridable so the whole run can be driven against a local stand-in: that a value comes
+// off the wire and back onto it unchanged is exactly what cannot be proven by reading the
+// code, and proving it must not need an account or a network.
+const API_ROOT = process.env.CLOUDFLARE_API_BASE || "https://api.cloudflare.com/client/v4";
+
+/**
+ * The migration itself, over an interface of four calls, so the same code runs against the
+ * REST API and against an in-memory namespace in the suite.
+ *
+ * `store` is `{ list(prefix) -> [names], get(name) -> ArrayBuffer|null, put(name, body) }`.
+ */
+export async function migrateBoardKeys(store, { workspace, apply = false, onProgress } = {}) {
+  if (!workspace) throw new Error("a workspace id is required — the segment is what this writes");
+  if (workspace.includes(":")) throw new Error("a workspace id may not contain ':' — it is the segment separator");
+  const scopedPrefix = boardKvKey(workspace, "");
+  const names = await store.list(BOARD_PREFIX);
+  // A scoped key matches the legacy prefix too, so the legacy set is what is left after
+  // this workspace's own scoped keys are taken out. Another workspace's scoped keys are
+  // NOT excluded here and must not be: a namespace holding two workspaces' boards has
+  // never had an unscoped key to migrate, so it will not reach this line with any.
+  const legacy = names.filter((n) => n.startsWith(BOARD_PREFIX) && !n.startsWith(scopedPrefix));
+  const out = { workspace, apply, scanned: legacy.length, identical: 0, differing: [], copied: [], vanished: [] };
+  for (const name of legacy) {
+    const path = name.slice(BOARD_PREFIX.length);
+    const target = boardKvKey(workspace, path);
+    const src = await store.get(name);
+    if (src === null || src === undefined) { out.vanished.push(name); continue; }
+    const dst = await store.get(target);
+    if (dst !== null && dst !== undefined) {
+      if (sameBytes(src, dst)) out.identical++;
+      else out.differing.push(path);
+      continue;
+    }
+    if (apply) await store.put(target, src);
+    out.copied.push(path);
+    if (onProgress) onProgress(path);
+  }
+  return out;
+}
+
+function sameBytes(a, b) {
+  const x = new Uint8Array(a), y = new Uint8Array(b);
+  if (x.length !== y.length) return false;
+  for (let i = 0; i < x.length; i++) if (x[i] !== y[i]) return false;
+  return true;
+}
+
+/** The REST-API namespace. Reads bytes, writes bytes. */
+export function apiStore({ root = API_ROOT, account, namespace, token }) {
+  const base = `${root}/accounts/${account}/storage/kv/namespaces/${namespace}`;
+  const H = { authorization: `Bearer ${token}` };
+  return {
+    async list(prefix) {
+      const names = [];
+      let cursor = "";
+      for (;;) {
+        const url = `${base}/keys?limit=1000&prefix=${encodeURIComponent(prefix)}${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`;
+        const res = await fetch(url, { headers: H });
+        const j = await res.json().catch(() => ({}));
+        if (!res.ok || !j.success) throw new Error(`list → ${res.status} ${JSON.stringify(j.errors || j).slice(0, 300)}`);
+        for (const k of j.result || []) names.push(k.name);
+        cursor = (j.result_info && j.result_info.cursor) || "";
+        if (!cursor) break;
+      }
+      return names;
+    },
+    async get(name) {
+      const res = await fetch(`${base}/values/${encodeURIComponent(name)}`, { headers: H });
+      if (res.status === 404) return null;
+      if (!res.ok) throw new Error(`get ${name} → ${res.status}`);
+      return await res.arrayBuffer();
+    },
+    async put(name, body) {
+      const res = await fetch(`${base}/values/${encodeURIComponent(name)}`, {
+        method: "PUT", headers: H, body,
+      });
+      if (!res.ok) throw new Error(`put ${name} → ${res.status}`);
+    },
+  };
+}
+
+// ---- CLI --------------------------------------------------------------------
+const invokedDirectly = process.argv[1] && process.argv[1].endsWith("migrate-board-keys.mjs");
+if (invokedDirectly) {
+  if (!ACC || !TOK) die("need CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID");
+  if (!NS) die("need AUGUR_KV_NS — the namespace id this instance's worker is bound to");
+  if (!WORKSPACE) die("need --workspace <id> — the segment to write. It is instance.json's tenantId, and getting it wrong writes a second copy of every board under a name nothing resolves to.");
+
+  const store = apiStore({ account: ACC, namespace: NS, token: TOK });
+  const res = await migrateBoardKeys(store, { workspace: WORKSPACE, apply: APPLY });
+
+  if (JSON_OUT) console.log(JSON.stringify({ ...res, copied: res.copied.length, differing: res.differing }, null, 2));
+  else {
+    log(`${APPLY ? "APPLY" : "DRY RUN"} · workspace "${WORKSPACE}"`);
+    log(`scanned ${res.scanned} legacy board keys`);
+    log(`identical ${res.identical} · ${APPLY ? "copied" : "would copy"} ${res.copied.length} · vanished ${res.vanished.length}`);
+    if (res.differing.length) {
+      log(`\x1b[31mdiffering ${res.differing.length} — SKIPPED, the scoped copy is newer:\x1b[0m`);
+      for (const p of res.differing.slice(0, 20)) log(`  ${p}`);
+    } else log("differing 0 — every legacy board matches its scoped copy or has none");
+  }
+  // A run that skipped something is not a success: the operator has to look before the
+  // read-through can be considered finished with.
+  if (res.differing.length) process.exit(2);
+}

package/scripts/migrate.mjs

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+/**
+ * augur migrate — move a workspace from one instance to another, and prove it arrived.
+ *
+ *   augur migrate --from https://old --to https://new [--freeze] [--out <dir>] [--dry-run]
+ *
+ * `MIG-do-rekey-run`. Five steps, and each one is a command that already exists and is
+ * already tested:
+ *
+ *   1. FREEZE the source (optional but you almost always want it). Writes stop; reads and
+ *      sign-in do not. See docs/migration-freeze.md for why that is a flag rather than a
+ *      DNS pull.
+ *   2. EXPORT everything — published content AND the roster, invites, publish tokens,
+ *      statuses, card names, comment threads, boards, pins, canvas images.
+ *   3. RESTORE it into the target, content and state.
+ *   4. VERIFY by reading the target back through its OWN export and diffing family by
+ *      family. This is the step that makes the run worth anything: a migration that
+ *      reports success without reading the far side back has only reported that it sent
+ *      some requests.
+ *   5. Leave the source frozen (deliberately — see below), and print the numbers.
+ *
+ * WHY IT SHELLS OUT rather than reimplementing any of it: a second copy of the export
+ * logic is a second thing that has to stay right, and the one that gets used less is the
+ * one that rots. Each step here is the command an operator would run by hand, in order,
+ * with its output on screen.
+ *
+ * RE-RUNNING IS SAFE, and that is the design rather than a happy accident. The export is
+ * content-addressed and skips blobs it already has; the restore replaces each family
+ * whole; the workspace object's import is one transaction. So a run that dies anywhere —
+ * mid-family, mid-blob, mid-anything — is fixed by running it again, and the end state is
+ * identical to an uninterrupted run. There is nothing to clean up first and nothing that
+ * double-writes.
+ *
+ * ⚠️ IT DOES NOT THAW THE SOURCE, and it does not touch DNS. Both are deliberate. The
+ * source stays read-only until a person has looked at the target and decided; thawing
+ * automatically would reopen writes to an instance that is about to stop being the one
+ * people reach. Cutting the hostname over is the step that needs a human and an account
+ * credential this script does not hold.
+ */
+import { spawn } from "node:child_process";
+import path from "node:path";
+import os from "node:os";
+import { mkdtempSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { resolveToken, apiClient } from "./lib/store.mjs";
+import { compareFamily } from "./lib/state-compare.mjs";
+
+const SCRIPTS = path.dirname(fileURLToPath(import.meta.url));
+const log = (m) => console.error(`\x1b[35m[migrate]\x1b[0m ${m}`);
+const die = (m) => { log(`\x1b[31m${m}\x1b[0m`); process.exit(1); };
+
+const args = process.argv.slice(2);
+const flag = (f) => args.includes(f);
+const opt = (f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : null; };
+
+const FROM = (opt("--from") || "").replace(/\/+$/, "");
+const TO = (opt("--to") || "").replace(/\/+$/, "");
+const DRY = flag("--dry-run");
+const FREEZE = flag("--freeze");
+if (!FROM || !TO) die("name both ends: --from https://old --to https://new");
+if (FROM === TO) die("--from and --to are the same instance.");
+
+// Tokens come from the same file `augur login` writes, one per host, so a migration needs
+// no new credential and no new place to keep one.
+const FROM_TOKEN = process.env.AUGUR_FROM_TOKEN || resolveToken(FROM);
+const TO_TOKEN = process.env.AUGUR_TO_TOKEN || resolveToken(TO);
+if (!FROM_TOKEN) die(`no token for ${FROM} — run \`augur login --origin ${FROM}\`. It needs STAR scope.`);
+if (!TO_TOKEN) die(`no token for ${TO} — run \`augur login --origin ${TO}\`. It needs STAR scope.`);
+
+const OUT = opt("--out") || mkdtempSync(path.join(os.tmpdir(), "augur-migrate-"));
+
+/** Run one of the existing commands, with its output on screen, and stop on failure. */
+function step(name, script, argv, env) {
+  return new Promise((resolve) => {
+    log(`\x1b[1m${name}\x1b[0m`);
+    const child = spawn(process.execPath, [path.join(SCRIPTS, script), ...argv], {
+      stdio: "inherit",
+      env: { ...process.env, ...env },
+    });
+    child.on("close", (code) => {
+      if (code !== 0) die(`${name} failed (exit ${code}). Nothing to clean up — fix it and run this again.`);
+      resolve();
+    });
+  });
+}
+
+const started = Date.now();
+log(`${FROM} → ${TO}${DRY ? "  [dry run]" : ""}`);
+log(`working directory: ${OUT}`);
+
+// 1. Freeze. Before the export, never after: a copy taken while writes are still landing
+//    is a copy that is already behind by the time it finishes.
+//
+//    ⚠️ AND THEN WAIT, because `freeze` returning is not the same as writes having stopped.
+//    The worker reads the freeze flag through a per-isolate cache with a 10-second life
+//    (`FREEZE_TTL_MS` in src/_worker.js), so an isolate that last looked 9 seconds ago goes
+//    on accepting writes for another second, and one that has not looked at all since the
+//    flag was set can accept them for the full ten. Those writes land in the workspace
+//    being copied AFTER the copy starts reading it — which is exactly the loss the freeze
+//    exists to prevent, arriving through the freeze itself.
+//
+//    Waiting the cache out is the whole fix and it costs eleven seconds of a migration
+//    somebody scheduled. Shortening the TTL instead would put a KV read in front of every
+//    write on every instance forever, to save eleven seconds on an operation run by hand.
+//
+//    ⚠️ AND A FREEZE DOES NOT STOP CANVAS EDITING. `isFrozenWrite` exempts GET, and a
+//    WebSocket upgrade is a GET, so `/__rt` stays open for the whole window: somebody with
+//    a board open can go on moving nodes, pasting images and renaming it while this runs,
+//    and every one of those edits lands in a room on the instance being retired. The `/__board`
+//    KV rail IS frozen, so what they cannot do is make the mirror this export reads catch
+//    up. That is why the board step below reads the ROOM and why it is allowed to refuse:
+//    an `unstable` read means somebody is editing right now, and the answer is to find them,
+//    not to force it.
+const FREEZE_SETTLE_MS = 11_000;
+if (FREEZE && !DRY) {
+  await step("freeze the source", "freeze.mjs",
+    ["--reason", `being moved to ${TO}`],
+    { AUGUR_ORIGIN: FROM, AUGUR_TOKEN: FROM_TOKEN });
+  log(`waiting ${FREEZE_SETTLE_MS / 1000}s for every isolate's freeze cache to expire — a write accepted now would be copied late or not at all`);
+  await new Promise((r) => setTimeout(r, FREEZE_SETTLE_MS));
+}
+
+// 2 + 3.
+await step("export everything", "export.mjs",
+  ["--out", OUT, "--full", "--history"],
+  { AUGUR_ORIGIN: FROM, AUGUR_TOKEN: FROM_TOKEN });
+
+await step("restore into the target", "restore.mjs",
+  [OUT, "--state", ...(DRY ? ["--dry-run"] : [])],
+  { AUGUR_ORIGIN: TO, AUGUR_TOKEN: TO_TOKEN });
+
+if (DRY) {
+  log("dry run — nothing was written to the target, and the source was not frozen");
+  process.exit(0);
+}
+
+// 4. THE STEP THAT MAKES THIS WORTH RUNNING. Read the target back through its own export
+//    and compare, family by family. A migration that reports success without reading the
+//    far side has reported that it sent some requests.
+log("\x1b[1mverify the target against the source\x1b[0m");
+const fromApi = apiClient(FROM, FROM_TOKEN);
+const toApi = apiClient(TO, TO_TOKEN);
+const [before, after] = await Promise.all([
+  (await fromApi("_state/export")).json(),
+  (await toApi("_state/export")).json(),
+]);
+
+// The judgement lives in lib/state-compare.mjs, where it can be tested without two
+// instances on the far side of a spawned runner. It is STRUCTURAL: the two ends answer
+// the same documents in different key orders (KV insertion order against the workspace
+// object's sorted read), so a bytewise comparison failed correct copies.
+
+const diffs = [];
+const blind = [];
+const ids = [...new Set([...Object.keys(before.families), ...Object.keys(after.families)])];
+for (const id of ids) {
+  const verdict = compareFamily(id, before.families[id], after.families[id]);
+  if (verdict === "differ") diffs.push(id);
+  if (verdict === "blind") blind.push(id);
+}
+const missingAssets = (before.assets || []).filter((h) => !(after.assets || []).includes(h));
+
+for (const id of ids) {
+  const n = Object.keys(before.families[id] || {}).length;
+  const bad = diffs.includes(id) || blind.includes(id);
+  const note = blind.includes(id)
+    ? "  \x1b[33mreported absent by one side — a set of documents, so an empty one is {}\x1b[0m"
+    : "";
+  console.log(`  ${bad ? "\x1b[31m✗\x1b[0m" : "\x1b[32m✓\x1b[0m"} ${id.padEnd(22)} ${n} key(s)${note}`);
+}
+console.log(`  ${missingAssets.length ? "\x1b[31m✗\x1b[0m" : "\x1b[32m✓\x1b[0m"} ${"canvas images".padEnd(22)} ${(before.assets || []).length}`);
+
+if (blind.length) {
+  die(`neither end can be judged on ${blind.join(", ")}: one side reported the family ABSENT rather than empty.\n`
+    + `  A family that is a set of documents reports an empty set as {}, so absent there means that\n`
+    + `  export could not enumerate it — not that it holds nothing. The copy may well be correct and\n`
+    + `  this run cannot say so. The source is untouched and still frozen.`);
+}
+if (diffs.length || missingAssets.length) {
+  die(`the target does not match the source: ${[...diffs, ...missingAssets.map((h) => `image ${h.slice(0, 8)}`)].join(", ")}.\n`
+    + `  The source is untouched and still frozen. Run this again — it is safe to repeat.`);
+}
+
+// 4b. THE ONE FAMILY THE COMPARISON ABOVE CANNOT JUDGE, and the reason it gets its own step.
+//
+// ⚠️ `board:` IS A MIRROR ON BOTH SIDES. The export reads the KV document a room writes on
+// a dirty alarm; the target's export reads the copy this migration just wrote there. So the
+// two agree the instant the restore lands, and they agree just as readily when the document
+// is nodes behind the room that owns it — which is the normal state of a live board, not an
+// edge case. Measured on a real instance with nobody editing: the mirror held 21 nodes and
+// the room held 24. A verification that says "every family matches" over that is telling the
+// truth about the copy and the wrong thing about the board, and it is the only step of this
+// command that can be green while data is being dropped.
+//
+// So the boards move over a SOCKET, from the room that owns them into the room that will.
+// `board-snapshot move` is that operation, it reads the truth and proves the seed landed,
+// and it never deletes the source. One process per board so a failure names its board.
+//
+// It can legitimately refuse: a board somebody is editing right now reads as `unstable`,
+// and the freeze does NOT stop that — a WebSocket upgrade is a GET, so `/__rt` is open for
+// the whole window. That refusal is the correct answer and it is why this is a step rather
+// than a footnote.
+//
+// AND IT IS SKIPPED, CORRECTLY, ON A DEPLOYMENT WITH NO ROOMS AT ALL. There, no room ever
+// wrote the mirror, so the KV document IS the board and the copy already carried the whole
+// of it. `/__rt` says which: 501 `realtime-not-configured` from a deployment that binds no
+// rooms and names no realtime origin, 426 `expected-websocket` from one that does. A plain
+// GET is enough to ask, which keeps this off the socket path entirely.
+const hasRooms = async (origin) => {
+  try {
+    const r = await fetch(`${origin}/__rt?path=/`, { headers: { Accept: "application/json" } });
+    return r.status !== 501;
+  } catch (e) { return true; } // cannot tell ⇒ do not skip the step that protects the data
+};
+
+const boardPaths = Object.keys((before.families || {})["board:"] || {});
+if (boardPaths.length && !(await hasRooms(FROM))) {
+  log(`${boardPaths.length} canvas board(s): ${FROM} serves no rooms, so the KV document is the `
+    + `whole board and the copy carried it. Nothing to move over a socket.`);
+} else if (boardPaths.length && !(await hasRooms(TO))) {
+  // The one case that is neither a pass nor a retry: the source's boards live in rooms and
+  // the target has nowhere to put them. Restoring the mirror leaves boards that are as
+  // stale as the mirror was and that no room will ever correct.
+  die(`${boardPaths.length} board(s) live in rooms on ${FROM}, and ${TO} has no realtime configured.\n`
+    + `  What landed there is the KV MIRROR, which is not the board. Configure realtime on the\n`
+    + `  target (a ROOMS binding, or rtOrigin in its deploy config) and run this again.`);
+} else if (boardPaths.length) {
+  log(`\x1b[1mmove ${boardPaths.length} canvas board(s) from the room, not the mirror\x1b[0m`);
+  const failedBoards = [];
+  for (const p of boardPaths) {
+    const code = await new Promise((resolve) => {
+      spawn(process.execPath, [path.join(SCRIPTS, "board-snapshot.mjs"), "move",
+        "--from", FROM, "--to", TO, "--path", p], { stdio: "inherit", env: process.env })
+        .on("close", resolve);
+    });
+    if (code !== 0) failedBoards.push(p);
+  }
+  if (failedBoards.length) {
+    die(`${failedBoards.length} board(s) did not move: ${failedBoards.join(", ")}.\n`
+      + `  The content and the state DID land — only these boards are still on the source, and\n`
+      + `  what ${TO} holds for them is the stale KV mirror, which is not the board. Fix and re-run;\n`
+      + `  a board move is safe to repeat and never removes the source.`);
+  }
+  console.log(`  \x1b[32m✓\x1b[0m ${"canvas boards".padEnd(22)} ${boardPaths.length} moved from the room`);
+}
+
+const mins = ((Date.now() - started) / 60000).toFixed(1);
+log(`\x1b[32mevery family matches\x1b[0m — ${Object.keys(before.families).length} famil(y/ies), ${(before.assets || []).length} image(s)`);
+console.log("");
+console.log(`  ${TO} now holds what ${FROM} holds.`);
+console.log(`  Copy took ${mins} minutes. The source is ${FREEZE ? "still FROZEN" : "still accepting writes"}.`);
+console.log("");
+// THE ONE THING THAT DID NOT COME, stated in the success report rather than in a doc.
+// A restore does not replay publish history, so the target starts at v1 per space; saying
+// it here is the difference between a known trade and a discovery mid-incident.
+console.log("\x1b[33m  Publish history did not come with it: every space on the target is at");
+console.log(`  version 1, so \`augur rollback\` there reaches nothing. The archive is on disk`);
+console.log(`  under ${OUT}/versions/ and ${FROM} still holds the live history until it is retired.\x1b[0m`);
+console.log("");
+console.log("  Next, in this order, by hand:");
+console.log(`    1. look at ${TO} and decide`);
+console.log("    2. point the hostname at it");
+console.log(`    3. \x1b[1maugur thaw\x1b[0m against whichever instance people now reach`);
+console.log("");
+console.log("\x1b[2m  Nothing here touches DNS, and nothing thaws the source: both need a person.\x1b[0m");