@augurworks/augur 0.15.1

package/src/unit-object.mjs

@@ -0,0 +1,338 @@
+// src/unit-object.mjs — one Durable Object per unit: the authority on main, drafts,
+// landings and the landing lease. See docs/drafts-that-land.md §6.
+//
+// File BODIES never live here. A table row names a content hash; the bytes are in the
+// bundle store under `blobs/<hash>`, shared and content-addressed, exactly as a publish
+// leaves them. A table is stored as one JSON document per revision, well under the row
+// limit for any prototype this engine has met.
+//
+// THE OBJECT NEVER MERGES. `save` applies a batch of changes with per-file compare-and-set
+// or refuses the whole batch with the fresh hashes; `land` refuses when main moved since
+// the draft's base. What to do about a refusal is the client's, on its own disk.
+//
+// THE LANDING LEASE. Landing writes the space manifest, and that write happens in the
+// worker, outside this object's single thread. So `land` hands out a ten-second lease and
+// refuses every other landing while it is held; `landed` commits under that lease. A
+// worker that dies between the two leaves a lease that simply expires — nothing depends on
+// it being released, and `abandon-land` is a courtesy.
+import {
+  newDraftId, unitTable, sameTable, applyChanges, tableDelta, presenceOf, DRAFT_ID_RE,
+} from "./unit-core.mjs";
+
+export const LAND_LEASE_MS = 10_000;
+export const UNIT_SCHEMA_VERSION = 1;
+// A literal, not a constructed RegExp — its group mirrors DRAFT_ID_RE in unit-core.mjs.
+const DRAFT_ROUTE_RE = /^\/draft\/([a-z0-9]{6})$/;
+
+export const UNIT_SCHEMA = Object.freeze([
+  `CREATE TABLE IF NOT EXISTS meta (k TEXT PRIMARY KEY, v TEXT NOT NULL)`,
+  `CREATE TABLE IF NOT EXISTS landings (
+     revision      INTEGER PRIMARY KEY,
+     tbl           TEXT NOT NULL,
+     by            TEXT,
+     session       TEXT,
+     at            TEXT NOT NULL,
+     note          TEXT,
+     draft_id      TEXT,
+     restored_from INTEGER
+   )`,
+  `CREATE TABLE IF NOT EXISTS drafts (
+     id            TEXT PRIMARY KEY,
+     owner         TEXT NOT NULL,
+     session       TEXT,
+     opened_at     TEXT NOT NULL,
+     last_save_at  TEXT,
+     base_revision INTEGER NOT NULL,
+     revision      INTEGER NOT NULL,
+     tbl           TEXT NOT NULL,
+     closed_at     TEXT,
+     discarded     INTEGER NOT NULL DEFAULT 0
+   )`,
+  `CREATE TABLE IF NOT EXISTS draft_saves (
+     draft_id  TEXT NOT NULL,
+     revision  INTEGER NOT NULL,
+     tbl       TEXT NOT NULL,
+     at        TEXT NOT NULL,
+     PRIMARY KEY (draft_id, revision)
+   )`,
+]);
+
+export function applyUnitSchema(sql, workspace, unit) {
+  for (const stmt of UNIT_SCHEMA) sql.exec(stmt);
+  sql.exec(`INSERT INTO meta (k, v) VALUES ('schema_version', ?) ON CONFLICT(k) DO UPDATE SET v = excluded.v`, String(UNIT_SCHEMA_VERSION));
+  if (workspace) sql.exec(`INSERT INTO meta (k, v) VALUES ('workspace', ?) ON CONFLICT(k) DO NOTHING`, String(workspace));
+  if (unit) sql.exec(`INSERT INTO meta (k, v) VALUES ('unit', ?) ON CONFLICT(k) DO NOTHING`, String(unit));
+}
+
+const json = (obj, status = 200) => new Response(JSON.stringify(obj), { status, headers: { "content-type": "application/json" } });
+const rowDraft = (r) => r && ({
+  id: r.id, owner: r.owner, session: r.session || "", openedAt: r.opened_at, lastSaveAt: r.last_save_at || null,
+  baseRevision: Number(r.base_revision), revision: Number(r.revision), table: JSON.parse(r.tbl),
+  closedAt: r.closed_at || null, discarded: !!r.discarded,
+});
+
+export class UnitObject {
+  constructor(ctx, env) {
+    this.ctx = ctx;
+    this.env = env;
+    this.ready = false;
+  }
+
+  get sql() { return this.ctx.storage.sql; }
+
+  async init(workspace, unit) {
+    if (this.ready) return;
+    const run = () => { applyUnitSchema(this.sql, workspace, unit); this.ready = true; };
+    if (this.ctx.blockConcurrencyWhile) await this.ctx.blockConcurrencyWhile(async () => run());
+    else run();
+  }
+
+  // ── meta ──────────────────────────────────────────────────────────────────
+  metaGet(k) {
+    const rows = [...this.sql.exec(`SELECT v FROM meta WHERE k = ?`, k)];
+    return rows.length ? rows[0].v : null;
+  }
+  metaSet(k, v) {
+    if (v === null) this.sql.exec(`DELETE FROM meta WHERE k = ?`, k);
+    else this.sql.exec(`INSERT INTO meta (k, v) VALUES (?, ?) ON CONFLICT(k) DO UPDATE SET v = excluded.v`, k, String(v));
+  }
+  mainRevision() { return Number(this.metaGet("main_revision") || 0); }
+  landing(revision) {
+    const rows = [...this.sql.exec(`SELECT * FROM landings WHERE revision = ?`, revision)];
+    return rows.length ? rows[0] : null;
+  }
+  mainTable() {
+    const l = this.landing(this.mainRevision());
+    return l ? JSON.parse(l.tbl) : {};
+  }
+  draft(id) {
+    const rows = [...this.sql.exec(`SELECT * FROM drafts WHERE id = ?`, id)];
+    return rows.length ? rowDraft(rows[0]) : null;
+  }
+  openDrafts() {
+    return [...this.sql.exec(`SELECT * FROM drafts WHERE closed_at IS NULL ORDER BY opened_at`)].map(rowDraft);
+  }
+  lease(nowMs) {
+    const raw = this.metaGet("lease");
+    if (!raw) return null;
+    const l = JSON.parse(raw);
+    if (Number(l.until) <= nowMs) { this.metaSet("lease", null); return null; }
+    return l;
+  }
+  writeLanding({ table, by, session, at, note, draftId, restoredFrom }) {
+    const revision = this.mainRevision() + 1;
+    this.sql.exec(
+      `INSERT INTO landings (revision, tbl, by, session, at, note, draft_id, restored_from) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      revision, JSON.stringify(table), by || null, session || null, at, note || null, draftId || null, restoredFrom == null ? null : restoredFrom,
+    );
+    this.metaSet("main_revision", revision);
+    return revision;
+  }
+
+  // ── verbs ─────────────────────────────────────────────────────────────────
+  syncMain({ table, at }) {
+    const cur = this.mainTable();
+    if (this.mainRevision() > 0 && sameTable(cur, table)) return { revision: this.mainRevision() };
+    return { revision: this.writeLanding({ table, by: "live", at, note: "adopted from live" }) };
+  }
+
+  open({ owner, session, at }) {
+    let id = newDraftId();
+    while (this.draft(id)) id = newDraftId();
+    const base = this.mainRevision();
+    const table = this.mainTable();
+    this.sql.exec(
+      `INSERT INTO drafts (id, owner, session, opened_at, base_revision, revision, tbl) VALUES (?, ?, ?, ?, ?, 0, ?)`,
+      id, String(owner || ""), String(session || ""), at, base, JSON.stringify(table),
+    );
+    return { draftId: id, baseRevision: base, table, presence: presenceOf(this.openDrafts(), Date.parse(at)) };
+  }
+
+  save({ draftId, draftRevision, changes, baseRevision, at }) {
+    const d = this.draft(draftId);
+    if (!d || d.closedAt) return [404, { error: "unknown-draft" }];
+    const held = this.lease(Date.parse(at));
+    if (held && held.draftId === draftId) return [409, { error: "landing-in-progress" }];
+    if (Number(draftRevision) !== d.revision) return [409, { error: "stale-draft-revision", draftRevision: d.revision }];
+    if (baseRevision !== undefined) {
+      const b = Number(baseRevision);
+      if (!Number.isInteger(b) || b < d.baseRevision || b > this.mainRevision()) return [400, { error: "bad-base", mainRevision: this.mainRevision() }];
+    }
+    const r = applyChanges(d.table, Array.isArray(changes) ? changes : []);
+    if (!r.ok) return [409, { error: "stale-draft", stale: r.stale }];
+    const revision = d.revision + 1;
+    this.sql.exec(
+      `UPDATE drafts SET revision = ?, tbl = ?, last_save_at = ?, base_revision = ? WHERE id = ?`,
+      revision, JSON.stringify(r.table), at, baseRevision === undefined ? d.baseRevision : Number(baseRevision), draftId,
+    );
+    this.sql.exec(`INSERT INTO draft_saves (draft_id, revision, tbl, at) VALUES (?, ?, ?, ?)`, draftId, revision, JSON.stringify(r.table), at);
+    return [200, { draftRevision: revision, table: r.table }];
+  }
+
+  takeLease({ draftId, table, at, restoredFrom }) {
+    const nowMs = Date.parse(at);
+    const held = this.lease(nowMs);
+    if (held && held.draftId !== (draftId || null)) return [409, { error: "landing-in-progress" }];
+    const lease = newDraftId() + newDraftId();
+    const revision = this.mainRevision() + 1;
+    this.metaSet("lease", JSON.stringify({
+      token: lease, draftId: draftId || null, revision, until: nowMs + LAND_LEASE_MS,
+      table, restoredFrom: restoredFrom == null ? null : restoredFrom,
+    }));
+    const delta = tableDelta(this.mainTable(), table);
+    return [200, { lease, revision, table, ...delta }];
+  }
+
+  land({ draftId, baseRevision, at }) {
+    const d = this.draft(draftId);
+    if (!d || d.closedAt) return [404, { error: "unknown-draft" }];
+    const main = this.mainRevision();
+    if (d.baseRevision !== main || Number(baseRevision) !== main) {
+      const base = this.landing(d.baseRevision);
+      const delta = tableDelta(base ? JSON.parse(base.tbl) : {}, this.mainTable());
+      return [409, { error: "main-moved", mainRevision: main, ...delta }];
+    }
+    // AN EMPTIED DRAFT IS NOT AN UNPUBLISH REQUEST. A draft whose every file is gone lands
+    // a unit with nothing behind it: the URL goes dark for everyone, the prefix is left
+    // declared, and the landing reads as a success. The one thing that reliably produces
+    // it is a folder that failed to materialise — a killed open, a disk that filled — so
+    // the answer is a refusal rather than a confirmation the object has no way to ask for.
+    // Deleting a prototype is its own verb, with its own confirmation.
+    if (!Object.keys(d.table).length && Object.keys(this.mainTable()).length) {
+      return [409, { error: "would-unpublish" }];
+    }
+    return this.takeLease({ draftId, table: d.table, at });
+  }
+
+  restore({ revision, at }) {
+    const l = this.landing(Number(revision));
+    if (!l) return [404, { error: "unknown-revision" }];
+    return this.takeLease({ draftId: null, table: JSON.parse(l.tbl), at, restoredFrom: Number(revision) });
+  }
+
+  landed({ lease, draftId, note, by, session, at }) {
+    const held = this.lease(Date.parse(at));
+    if (!held || held.token !== lease) return [409, { error: "bad-lease" }];
+    const table = held.table;
+    const revision = this.writeLanding({
+      table, by, session, at, note, draftId: held.draftId || draftId || null, restoredFrom: held.restoredFrom,
+    });
+    if (held.draftId) this.sql.exec(`UPDATE drafts SET closed_at = ? WHERE id = ?`, at, held.draftId);
+    this.metaSet("lease", null);
+    return [200, { revision }];
+  }
+
+  abandonLand({ lease }) {
+    const raw = this.metaGet("lease");
+    if (raw && JSON.parse(raw).token === lease) this.metaSet("lease", null);
+    return [200, { ok: true }];
+  }
+
+  sync({ draftId }) {
+    const d = this.draft(draftId);
+    if (!d || d.closedAt) return [404, { error: "unknown-draft" }];
+    const base = this.landing(d.baseRevision);
+    const delta = tableDelta(base ? JSON.parse(base.tbl) : {}, this.mainTable());
+    return [200, { mainRevision: this.mainRevision(), baseRevision: d.baseRevision, ...delta }];
+  }
+
+  discard({ draftId, at }) {
+    const d = this.draft(draftId);
+    if (!d || d.closedAt) return [404, { error: "unknown-draft" }];
+    this.sql.exec(`UPDATE drafts SET closed_at = ?, discarded = 1 WHERE id = ?`, at, draftId);
+    return [200, { closed: true }];
+  }
+
+  history() {
+    const rows = [...this.sql.exec(`SELECT * FROM landings ORDER BY revision DESC`)];
+    return {
+      revision: this.mainRevision(),
+      landings: rows.map((r) => ({
+        revision: Number(r.revision), by: r.by || null, session: r.session || "", at: r.at, note: r.note || "",
+        draftId: r.draft_id || null, restoredFrom: r.restored_from == null ? null : Number(r.restored_from),
+        files: Object.keys(JSON.parse(r.tbl)).length,
+      })),
+    };
+  }
+
+  // ── live tabs ─────────────────────────────────────────────────────────────
+  // One socket per open tab, accepted with the Hibernation API so an idle unit with tabs
+  // on it costs nothing. A SOCKET CARRIES NO AUTHORITY: the worker authenticated the
+  // person before forwarding the Upgrade, and every message sent here is a fact any member
+  // may read anyway — a draft saved, a landing happened. Nothing about a socket is stored
+  // beyond its attachment, nothing waits for one, and a verb's answer never depends on a
+  // send having worked: `emit` is fire-and-forget and closes what it cannot reach.
+  socket(request, url) {
+    if ((request.headers.get("Upgrade") || "").toLowerCase() !== "websocket") return json({ error: "expected-websocket" }, 426);
+    const draft = url.searchParams.get("draft") || null;
+    if (draft && !DRAFT_ID_RE.test(draft)) return json({ error: "bad-draft" }, 400);
+    if (typeof WebSocketPair !== "function" || !this.ctx.acceptWebSocket) return json({ error: "sockets-unavailable" }, 501);
+    const pair = new WebSocketPair();
+    const [client, server] = Object.values(pair);
+    this.ctx.acceptWebSocket(server);
+    server.serializeAttachment({ draft, since: Date.now() });
+    return new Response(null, { status: 101, webSocket: client });
+  }
+  emit(msg) {
+    if (!this.ctx.getWebSockets) return;
+    const raw = JSON.stringify(msg);
+    for (const ws of this.ctx.getWebSockets()) {
+      try { ws.send(raw); } catch (e) { try { ws.close(1011, "send failed"); } catch (e2) { /* already gone */ } }
+    }
+  }
+  webSocketMessage(ws, raw) {
+    if (raw === "ping") { try { ws.send("pong"); } catch (e) { /* closing */ } }
+  }
+  webSocketClose() { /* the runtime owns the socket list; nothing to clean up */ }
+  webSocketError() { /* same */ }
+
+  // ── router ────────────────────────────────────────────────────────────────
+  async fetch(request) {
+    const url = new URL(request.url);
+    const route = url.pathname;
+    let body = {};
+    if (request.method === "POST") {
+      try { body = await request.json(); } catch (e) { return json({ error: "bad-json" }, 400); }
+    }
+    // Every verb but sync-main assumes the schema is there; sync-main is what the worker
+    // calls first on every request, carrying the names the schema is stamped with.
+    if (route === "/sync-main") {
+      await this.init(body.workspace, body.unit);
+      return json(this.syncMain({ table: unitTable(body.table || {}, body.unit || ""), at: body.at || new Date().toISOString() }));
+    }
+    if (route === "/socket") return this.socket(request, url);
+    await this.init(null, null);
+    if (request.method === "GET") {
+      if (route === "/presence") return json({ drafts: presenceOf(this.openDrafts(), Date.parse(url.searchParams.get("at") || "") || Date.now()) });
+      if (route === "/history") return json(this.history());
+      if (route === "/main") return json({ revision: this.mainRevision(), table: this.mainTable() });
+      const m = DRAFT_ROUTE_RE.exec(route);
+      if (m) {
+        const d = this.draft(m[1]);
+        if (!d || d.discarded) return json({ error: "unknown-draft" }, 404);
+        return json({ draftId: d.id, table: d.table, owner: d.owner, session: d.session, openedAt: d.openedAt, lastSaveAt: d.lastSaveAt, baseRevision: d.baseRevision, revision: d.revision, closedAt: d.closedAt });
+      }
+      return json({ error: "unknown-route" }, 404);
+    }
+    const at = body.at || new Date().toISOString();
+    const verbs = {
+      "/open": () => [200, this.open({ ...body, at })],
+      "/save": () => this.save({ ...body, at }),
+      "/land": () => this.land({ ...body, at }),
+      "/restore": () => this.restore({ ...body, at }),
+      "/landed": () => this.landed({ ...body, at }),
+      "/abandon-land": () => this.abandonLand(body),
+      "/sync": () => this.sync(body),
+      "/discard": () => this.discard({ ...body, at }),
+    };
+    if (!verbs[route]) return json({ error: "unknown-route" }, 404);
+    const [status, out] = verbs[route]();
+    if (status === 200) {
+      if (route === "/open") this.emit({ t: "open", draftId: out.draftId, at });
+      else if (route === "/save") this.emit({ t: "save", draftId: body.draftId, revision: out.draftRevision, at });
+      else if (route === "/landed") this.emit({ t: "land", revision: out.revision, draftId: body.draftId || null, at });
+      else if (route === "/discard") this.emit({ t: "discard", draftId: body.draftId, at });
+    }
+    return json(out, status);
+  }
+}

package/templates/README.md

@@ -0,0 +1,67 @@
+# Deploy templates
+
+Copy-paste workflows for a **deploy shell** — the private repo that pins this engine,
+holds the user list and the secrets, and ships the site. The engine deploys nothing
+itself.
+
+**The recipe that uses these files is [INSTALL.md](../INSTALL.md)** — read that first;
+this page is only the file index.
+
+```
+templates/shell/          → <shell-repo>/.github/workflows/
+├── deploy.yml            # REQUIRED. Build engine chrome → Pages → publish chrome to the store.
+├── engine-bump.yml       # REQUIRED in practice. Take engine updates on your own schedule.
+├── health.yml            # Canary: pushed-but-never-published drift, stale dirty publishes.
+├── store-backup.yml      # Weekly + monthly off-Cloudflare copies of the bundle store.
+├── kv-backup.yml         # Nightly copy of KV — the half store-backup does not cover.
+├── space-preflight.yml   # Probe that CI's PAT can read a space repo before you add it.
+└── roster-update.yml     # Commit Admin-panel invites/removals back to identity.json.
+
+templates/space/          → <space-repo>/.github/workflows/  (OPTIONAL — see below)
+└── publish.yml           # Auto-publish on push + keep baked chrome current with the engine.
+```
+
+Drift between a shell and these files is caught by `shell-lint` — run it from a shell
+(`node engine/scripts/shell-lint.mjs`), where the engine submodule IS that shell's
+pinned engine. `health.yml` runs it on every canary pass. Filled-in placeholders and
+reworded comments stay quiet; changed behaviour fails.
+
+Each file carries its own header explaining what it does and what it needs. Three of them
+have an instance value to fill in before first use — the Pages project name and site
+origin in `deploy.yml`, the site origin in `health.yml` and `store-backup.yml`.
+
+**The two backups do not overlap, and a shell needs both.** `store-backup.yml` copies
+published *content* out of the bundle store (R2). `kv-backup.yml` copies the mutable
+*state* the worker keeps alongside it — comment threads, statuses, pins, renames,
+canvases, and the identity records below. Neither store has point-in-time restore, and
+neither backup covers the other, so running only one is being half-backed-up while
+reading as backed-up.
+
+⚠️ `kv-backup.yml` commits the **whole** namespace to a branch on the shell repo, and
+that includes `users:secrets` (password hashes, and the tombstones that hold reset
+passwords out of service) and `publish:tokens` (live bearer tokens that can overwrite
+published content). **Do not enable it on a public shell.** Everything else here is
+safe on one; this is not.
+
+**Keeping baked chrome current is the SHELL's job, not the space's.** Page-level chrome
+(rail, overlays, layout) is baked into each page at publish time (`/_build.json`
+`builtWithEngine`), so an engine bump refreshes the *serving* engine but leaves
+already-published pages on older chrome until the space republishes. `deploy.yml` closes
+that with a `rebake` job: when the engine pin moves it clones each roster space and
+re-publishes it with the shell's own `*`-scoped `AUGUR_TOKEN` (the one it already uses for
+`--engine`). The star token therefore lives ONLY in the private shell — never in a
+(possibly public) space repo — and **no space needs a token or CI just to stay on the
+current chrome.** `health.yml` check (f) alarms if a space is ever left on chrome older
+than the deployed engine.
+
+**`templates/space/publish.yml` is optional and only for a PUBLIC auto-publish space** —
+a demo whose last pusher is often not the person who'd remember to publish. It joins
+push→publish so content goes live on push, running the same `augur publish` client with a
+token scoped to that space (not `*`, since the repo may be public). A working space needs
+none of this: it publishes deliberately from a terminal, and its chrome is re-baked by the
+shell above. A bare space repo is just a `space.json` and some `prototypes/` folders — no
+CI, no secret, no submodule mount.
+
+Engine missing something your instance needs? Don't patch your copy — **open a PR
+upstream** ([CONTRIBUTING.md](../CONTRIBUTING.md)) and take it back via pin bump. That
+keeps your instance on the update train and ships your fix to everyone.

package/templates/shell/deploy.yml

@@ -0,0 +1,145 @@
+name: Deploy to Cloudflare Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: # allow manual runs from the Actions tab
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-deploy
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      # A deploy shell composes ONLY the Augur ENGINE (submodule at engine/). No
+      # space repo is mounted here and none is checked out: space content reaches
+      # production exclusively through `augur publish` from a space clone, into the
+      # bundle store the worker serves from.
+      #
+      # If you are tempted to mount spaces here and build the whole site: that was
+      # the previous design, and it gave every page two sources of content with
+      # nothing to tell them apart. The store shadowed the built assets at serve
+      # time, so a submodule pin could sit weeks behind its space repo while the
+      # live URL served something else — and bumping the pin changed nothing,
+      # because pins were never the serving path. Keep the roster of space repos in
+      # deploy.config.json (`spaces`) for repo-side automation instead.
+      #
+      # The engine is public; SUBMODULE_PAT is only needed because actions/checkout
+      # uses one token for the host repo and its submodules, and this shell repo is
+      # private. (.gitmodules URLs must stay HTTPS — checkout cannot authenticate
+      # SSH URLs.)
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0          # the realtime step below diffs across the engine pin move
+          submodules: true        # the engine only
+          token: ${{ secrets.SUBMODULE_PAT }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      # GV_ENGINE_ONLY=1 builds the shared chrome and the worker with NO space on
+      # disk. That is the point: a build that never sees a space cannot emit one, so
+      # this job is structurally incapable of overwriting a direct publish however
+      # stale its checkout. build.js asserts the result really is chrome-only and
+      # fails the deploy if anything space-derived slipped in.
+      - name: Build engine chrome
+        run: node engine/build.js
+        env:
+          GV_ENGINE_ONLY: "1"
+          GV_IDENTITY_PATH: ${{ github.workspace }}/identity.json
+          GV_DEPLOY_CONFIG_PATH: ${{ github.workspace }}/deploy.config.json
+
+      # ── ONE FRONT DOOR OR THE OTHER, chosen by whether this shell has a wrangler.toml ──
+      #
+      # An instance is on Pages or on a plain Worker, and this template answers both so a
+      # shell can move on its own schedule. The `hashFiles` conditional is the pattern this
+      # very file already uses for the realtime worker below.
+      #
+      # Keeping BOTH here is deliberate. `scripts/shell-lint.mjs` compares a shell's
+      # workflows to these templates LINE BY LINE, so a template that knew only about
+      # Workers would red-line every shell still on Pages — and with them the health check
+      # that reads shell-lint — until the last one migrated. One template, both worlds,
+      # and cutover is adding one file to a shell while rollback is deleting it.
+
+      # PAGES. Carries the WORKER (_worker.js) plus the chrome as an assets-mode fallback.
+      # Content is not here.
+      - name: Deploy to Cloudflare Pages
+        if: ${{ hashFiles('wrangler.toml') == '' }}
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy engine/dist --project-name=your-pages-project --branch=main
+
+      # PLAIN WORKER. The preflight runs FIRST and the deploy is gated on it, because the
+      # config it checks is the difference between a gated site and a public one: Workers
+      # serves a matching static asset BEFORE invoking the worker unless
+      # `run_worker_first = true`, and the asset directory holds __config/instance.json —
+      # the roster, with seed passwords. A deploy that skips this check and gets it wrong
+      # passes every test, answers the health canary "healthy", and serves the roster.
+      - name: Preflight the worker config
+        if: ${{ hashFiles('wrangler.toml') != '' }}
+        run: node engine/scripts/wrangler-preflight.mjs -c wrangler.toml
+
+      - name: Deploy the Worker
+        if: ${{ hashFiles('wrangler.toml') != '' }}
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: deploy --config wrangler.toml
+
+      # The store's copy of the chrome, plus the instance config (identity + knobs)
+      # the worker reads at runtime. --engine sets GV_ENGINE_ONLY itself, so it
+      # cannot touch space content. Skips gracefully while AUGUR_TOKEN isn't
+      # configured (assets-mode setups, where Pages is the only source).
+      - name: Publish engine chrome to the bundle store
+        env:
+          AUGUR_TOKEN: ${{ secrets.AUGUR_TOKEN }}
+          AUGUR_ORIGIN: https://your-site-origin.example
+          GV_IDENTITY_PATH: ${{ github.workspace }}/identity.json
+          GV_DEPLOY_CONFIG_PATH: ${{ github.workspace }}/deploy.config.json
+        run: |
+          if [ -z "$AUGUR_TOKEN" ]; then echo "AUGUR_TOKEN not configured — skipping store publish"; exit 0; fi
+          cd engine && node scripts/publish.mjs --engine
+
+      # The realtime (canvas multiplayer) worker deploys separately from Pages; its
+      # instance config lives in THIS repo (realtime.wrangler.toml). Third parties
+      # forget manual redeploys, so: when the engine pin moved AND the move touched
+      # engine realtime code, redeploy it here. Skips gracefully when the shell has
+      # no realtime config, the pin didn't move, or realtime/ is untouched.
+      - name: Redeploy realtime if the engine bump changed it
+        if: ${{ hashFiles('realtime.wrangler.toml') != '' }}
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: |
+          set -euo pipefail
+          OLD="$(git rev-parse '${{ github.event.before }}:engine' 2>/dev/null \
+             || git rev-parse 'HEAD^:engine' 2>/dev/null || true)"
+          NEW="$(git rev-parse 'HEAD:engine')"
+          if [ -z "$OLD" ] || [ "$OLD" = "$NEW" ]; then echo "engine pin unmoved — skipping realtime."; exit 0; fi
+          # BOTH paths, and src/board-room.mjs is the one that is easy to forget: the
+          # BoardRoom class MOVED out of realtime/ into the engine's own module graph, so
+          # this worker's behaviour now lives mostly in a directory this diff used to
+          # ignore. Watching only realtime/ would ship a room fix to the engine worker and
+          # silently leave the standalone realtime workers on the old code.
+          if git -C engine diff --quiet "$OLD" "$NEW" -- realtime/ src/board-room.mjs 2>/dev/null; then
+            echo "engine bump didn't touch realtime/ or src/board-room.mjs — skipping."; exit 0
+          fi
+          echo "realtime code changed in ${OLD:0:12}..${NEW:0:12} — redeploying"
+          npx wrangler deploy -c realtime.wrangler.toml
+
+  # Drift-driven re-bake after every deploy; the same workflow also answers the
+  # worker's space-rebake dispatch the moment a stale-baked publish arrives.
+  # Full rationale + the script live in space-rebake.yml.
+  rebake:
+    needs: deploy
+    uses: ./.github/workflows/space-rebake.yml
+    secrets: inherit