@terminus-ai/cli 0.0.1

package/bin/dev-capsules.mjs

@@ -0,0 +1,1599 @@
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+import { LIMITS } from "./dev-contract.mjs";
+import { sha256 } from "./files.mjs";
+
+const CAPSULE_FORMAT_VERSION = 1;
+/** Rows kept per collection scope before older cursors expire — the
+ * backend's COLLECTION_CHANGE_RETENTION_ROWS. */
+export const CHANGE_RETENTION = 10_000;
+
+function safeSegment(value, fallback = "item") {
+  const normalized = String(value ?? "")
+    .normalize("NFKC")
+    .replace(/^@/, "")
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+  return normalized || fallback;
+}
+
+function appDirectoryName(appId) {
+  const digest = sha256(String(appId)).slice(0, 12);
+  return `${safeSegment(String(appId).split("/").at(-1), "app")}-${digest}`;
+}
+
+export function devCapsuleDirectory(rootDir, appId, member) {
+  return path.join(
+    rootDir,
+    "users",
+    safeSegment(member, "user"),
+    "apps",
+    appDirectoryName(appId),
+  );
+}
+
+function atomicWriteBytes(target, bytes) {
+  mkdirSync(path.dirname(target), { recursive: true });
+  const temporary = `${target}.tmp-${process.pid}-${crypto.randomUUID()}`;
+  const descriptor = openSync(temporary, "wx", 0o600);
+  try {
+    writeFileSync(descriptor, bytes);
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+  try {
+    renameSync(temporary, target);
+  } catch (error) {
+    rmSync(temporary, { force: true });
+    if (!existsSync(target)) throw error;
+  }
+  try {
+    const directory = openSync(path.dirname(target), "r");
+    try {
+      fsyncSync(directory);
+    } finally {
+      closeSync(directory);
+    }
+  } catch {
+    // Some platforms do not permit fsync on a directory. The file itself was
+    // still fsynced before its atomic rename.
+  }
+}
+
+function configure(db) {
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA synchronous = FULL");
+  db.exec("PRAGMA foreign_keys = ON");
+  db.exec("PRAGMA busy_timeout = 5000");
+}
+
+function transaction(db, task) {
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    const result = task();
+    db.exec("COMMIT");
+    return result;
+  } catch (error) {
+    try {
+      db.exec("ROLLBACK");
+    } catch {
+      // Preserve the original failure.
+    }
+    throw error;
+  }
+}
+
+function parseJson(value, fallback = null) {
+  if (value === null || value === undefined || value === "") return fallback;
+  return JSON.parse(String(value));
+}
+
+/** Add the columns a table declares that an older local database lacks, so a
+ * folder's fixtures outlive a CLI upgrade. The table's CREATE statement stays
+ * the one schema; this only closes the gap to it. */
+function ensureColumns(db, table, columns) {
+  const present = new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((row) => String(row.name)));
+  for (const [name, definition] of Object.entries(columns)) {
+    if (!present.has(name)) db.exec(`ALTER TABLE ${table} ADD COLUMN ${name} ${definition}`);
+  }
+}
+
+/** JSON values equal as values: objects as maps, arrays in order. */
+function jsonEqual(left, right) {
+  if (left === right) return true;
+  if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) return false;
+  if (Array.isArray(left) !== Array.isArray(right)) return false;
+  if (Array.isArray(left)) {
+    return left.length === right.length && left.every((item, index) => jsonEqual(item, right[index]));
+  }
+  const keys = Object.keys(left);
+  return keys.length === Object.keys(right).length
+    && keys.every((key) => Object.hasOwn(right, key) && jsonEqual(left[key], right[key]));
+}
+
+/** The top-level fields a change touched, as the platform lists them
+ * (`changed_record_fields`): none when nothing changed, `$` when either side
+ * is not an object or the record is past 64 fields, else the differing keys
+ * in byte order. */
+export function changedRecordFields(before, after) {
+  if (jsonEqual(before ?? null, after ?? null)) return [];
+  const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+  if (!object(before) || !object(after)) return ["$"];
+  const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])];
+  if (keys.length > 64) return ["$"];
+  return keys
+    .filter((key) => !jsonEqual(before[key], after[key]))
+    .sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+}
+
+function likePrefix(prefix) {
+  return `${prefix.replaceAll("\\", "\\\\").replaceAll("%", "\\%").replaceAll("_", "\\_")}%`;
+}
+
+export class DevSystemStore {
+  constructor(rootDir, appId) {
+    mkdirSync(rootDir, { recursive: true });
+    this.rootDir = rootDir;
+    this.appId = appId;
+    this.file = path.join(rootDir, "system.sqlite");
+    this.db = new DatabaseSync(this.file);
+    configure(this.db);
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS dev_spaces (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        members_json TEXT NOT NULL,
+        conversation_kind TEXT CHECK (conversation_kind IN ('direct', 'group')),
+        roles_json TEXT CHECK (roles_json IS NULL OR json_valid(roles_json)),
+        parent_id TEXT,
+        meta_json TEXT CHECK (meta_json IS NULL OR json_valid(meta_json)),
+        joined_json TEXT CHECK (joined_json IS NULL OR json_valid(joined_json)),
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS dev_user_blocks (
+        app_id TEXT NOT NULL,
+        blocker_id TEXT NOT NULL,
+        blocked_id TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (app_id, blocker_id, blocked_id),
+        CHECK (blocker_id <> blocked_id)
+      );
+
+      CREATE TABLE IF NOT EXISTS dev_space_invitations (
+        id TEXT PRIMARY KEY,
+        app_id TEXT NOT NULL,
+        space_id TEXT NOT NULL,
+        inviter_id TEXT NOT NULL,
+        invitee_id TEXT NOT NULL,
+        role TEXT NOT NULL,
+        status TEXT NOT NULL CHECK (status IN ('pending', 'accepted', 'declined')),
+        created_at TEXT NOT NULL,
+        expires_at TEXT NOT NULL,
+        resolved_at TEXT
+      );
+
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_dev_space_invitations_one_pending
+        ON dev_space_invitations (app_id, space_id, invitee_id)
+        WHERE status = 'pending';
+
+      CREATE INDEX IF NOT EXISTS idx_dev_space_invitations_invitee_pending
+        ON dev_space_invitations (app_id, invitee_id, created_at)
+        WHERE status = 'pending';
+
+      CREATE INDEX IF NOT EXISTS idx_dev_space_invitations_space_pending
+        ON dev_space_invitations (app_id, space_id, created_at)
+        WHERE status = 'pending';
+
+      CREATE TABLE IF NOT EXISTS collection_definitions (
+        app_id TEXT NOT NULL,
+        name TEXT NOT NULL,
+        definition_json TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (app_id, name)
+      );
+
+      CREATE TABLE IF NOT EXISTS space_delivery_sequences (
+        app_id TEXT NOT NULL,
+        space_id TEXT NOT NULL,
+        head_sequence INTEGER NOT NULL DEFAULT 0 CHECK (head_sequence >= 0),
+        PRIMARY KEY (app_id, space_id)
+      );
+
+      CREATE TABLE IF NOT EXISTS record_deliveries (
+        app_id TEXT NOT NULL,
+        space_id TEXT NOT NULL,
+        collection_name TEXT NOT NULL,
+        mutation_id TEXT NOT NULL,
+        record_id TEXT NOT NULL,
+        request_sha256 TEXT NOT NULL,
+        sequence INTEGER NOT NULL CHECK (sequence > 0),
+        recipients_json TEXT NOT NULL CHECK (json_valid(recipients_json)),
+        status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'committed')),
+        response_json TEXT CHECK (response_json IS NULL OR json_valid(response_json)),
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (app_id, space_id, collection_name, mutation_id)
+      );
+
+      CREATE TABLE IF NOT EXISTS space_member_cursors (
+        app_id TEXT NOT NULL,
+        space_id TEXT NOT NULL,
+        member_id TEXT NOT NULL,
+        delivered_through INTEGER NOT NULL DEFAULT 0 CHECK (delivered_through >= 0),
+        read_through INTEGER NOT NULL DEFAULT 0 CHECK (read_through >= 0),
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (app_id, space_id, member_id),
+        CHECK (read_through <= delivered_through)
+      );
+
+      CREATE TABLE IF NOT EXISTS collaboration_streams (
+        app_id TEXT NOT NULL,
+        scope_key TEXT NOT NULL,
+        document_id TEXT NOT NULL,
+        head_sequence INTEGER NOT NULL DEFAULT 0 CHECK (head_sequence >= 0),
+        retained_after_sequence INTEGER NOT NULL DEFAULT 0 CHECK (retained_after_sequence >= 0),
+        snapshot_sequence INTEGER NOT NULL DEFAULT 0 CHECK (snapshot_sequence >= 0),
+        snapshot_json TEXT CHECK (snapshot_json IS NULL OR json_valid(snapshot_json)),
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (app_id, scope_key, document_id)
+      );
+
+      CREATE TABLE IF NOT EXISTS collaboration_operations (
+        app_id TEXT NOT NULL,
+        scope_key TEXT NOT NULL,
+        document_id TEXT NOT NULL,
+        sequence INTEGER NOT NULL CHECK (sequence > 0),
+        actor_user_id TEXT NOT NULL,
+        actor_session_id TEXT NOT NULL,
+        operation_id TEXT NOT NULL,
+        operation_json TEXT NOT NULL CHECK (json_valid(operation_json)),
+        committed_at TEXT NOT NULL,
+        PRIMARY KEY (app_id, scope_key, document_id, sequence),
+        UNIQUE (app_id, scope_key, document_id, actor_user_id, operation_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_collaboration_operations_stream
+        ON collaboration_operations (app_id, scope_key, document_id, sequence);
+
+      -- An operation's receipt outlives it: compaction moves the operations
+      -- a snapshot covers here, so a retried id still answers its committed
+      -- position and never lands twice (the platform's operation receipts).
+      CREATE TABLE IF NOT EXISTS collaboration_receipts (
+        app_id TEXT NOT NULL,
+        scope_key TEXT NOT NULL,
+        document_id TEXT NOT NULL,
+        sequence INTEGER NOT NULL CHECK (sequence > 0),
+        actor_user_id TEXT NOT NULL,
+        actor_session_id TEXT NOT NULL,
+        operation_id TEXT NOT NULL,
+        operation_json TEXT NOT NULL CHECK (json_valid(operation_json)),
+        committed_at TEXT NOT NULL,
+        PRIMARY KEY (app_id, scope_key, document_id, actor_user_id, operation_id)
+      );
+
+      -- The records plane behind capabilities.server, as the platform keeps
+      -- it: only the app's server code reads or writes it. A global row's
+      -- installation_id is empty; an installation row names its install.
+      CREATE TABLE IF NOT EXISTS app_server_records (
+        app_id TEXT NOT NULL,
+        scope TEXT NOT NULL CHECK (scope IN ('global', 'installation')),
+        installation_id TEXT NOT NULL,
+        collection TEXT NOT NULL,
+        doc_id TEXT NOT NULL,
+        data_json TEXT NOT NULL CHECK (json_valid(data_json)),
+        stored_bytes INTEGER NOT NULL CHECK (stored_bytes >= 0),
+        version INTEGER NOT NULL CHECK (version > 0),
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (app_id, scope, installation_id, collection, doc_id),
+        CHECK ((scope = 'installation') = (installation_id <> ''))
+      );
+
+      CREATE TABLE IF NOT EXISTS app_server_record_totals (
+        app_id TEXT NOT NULL,
+        scope TEXT NOT NULL CHECK (scope IN ('global', 'installation')),
+        installation_id TEXT NOT NULL,
+        total_bytes INTEGER NOT NULL DEFAULT 0,
+        record_count INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY (app_id, scope, installation_id)
+      );
+
+      CREATE TABLE IF NOT EXISTS app_server_fetch_counters (
+        app_id TEXT NOT NULL,
+        installation_id TEXT NOT NULL,
+        day TEXT NOT NULL,
+        requests INTEGER NOT NULL,
+        PRIMARY KEY (app_id, installation_id, day)
+      );
+    `);
+    ensureColumns(this.db, "dev_spaces", {
+      conversation_kind: "TEXT CHECK (conversation_kind IN ('direct', 'group'))",
+      roles_json: "TEXT CHECK (roles_json IS NULL OR json_valid(roles_json))",
+      parent_id: "TEXT",
+      meta_json: "TEXT CHECK (meta_json IS NULL OR json_valid(meta_json))",
+      joined_json: "TEXT CHECK (joined_json IS NULL OR json_valid(joined_json))",
+    });
+  }
+
+  /** Spaces as the harness keeps them: `kind` direct or group, members by
+   * handle with their roles and when they joined, an optional parent and
+   * app-defined meta. */
+  loadSpaces() {
+    return this.db.prepare(`
+      SELECT id, name, members_json, conversation_kind, roles_json, parent_id, meta_json,
+             joined_json, created_at, updated_at
+      FROM dev_spaces ORDER BY created_at, id
+    `).all().map((row) => ({
+      id: String(row.id),
+      name: String(row.name),
+      members: parseJson(row.members_json, []),
+      kind: row.conversation_kind === null ? "group" : String(row.conversation_kind),
+      roles: parseJson(row.roles_json, {}),
+      parentId: row.parent_id === null ? null : String(row.parent_id),
+      meta: parseJson(row.meta_json, null),
+      joined: parseJson(row.joined_json, {}),
+      createdAt: String(row.created_at),
+      updatedAt: String(row.updated_at),
+    }));
+  }
+
+  saveSpaces(spaces) {
+    const now = new Date().toISOString();
+    transaction(this.db, () => {
+      const ids = spaces.map((space) => String(space.id));
+      if (ids.length) {
+        const placeholders = ids.map(() => "?").join(", ");
+        this.db.prepare(`DELETE FROM dev_spaces WHERE id NOT IN (${placeholders})`).run(...ids);
+      } else {
+        this.db.exec("DELETE FROM dev_spaces");
+      }
+      const upsert = this.db.prepare(`
+        INSERT INTO dev_spaces
+          (id, name, members_json, conversation_kind, roles_json, parent_id, meta_json,
+           joined_json, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (id) DO UPDATE SET
+          name = excluded.name,
+          members_json = excluded.members_json,
+          conversation_kind = excluded.conversation_kind,
+          roles_json = excluded.roles_json,
+          parent_id = excluded.parent_id,
+          meta_json = excluded.meta_json,
+          joined_json = excluded.joined_json,
+          updated_at = excluded.updated_at
+      `);
+      for (const space of spaces) {
+        upsert.run(
+          String(space.id),
+          String(space.name),
+          JSON.stringify(space.members ?? []),
+          space.kind ?? "group",
+          JSON.stringify(space.roles ?? {}),
+          space.parentId ?? null,
+          space.meta === null || space.meta === undefined ? null : JSON.stringify(space.meta),
+          JSON.stringify(space.joined ?? {}),
+          space.createdAt ?? now,
+          space.updatedAt ?? now,
+        );
+      }
+    });
+  }
+
+  loadSpaceInvitations() {
+    return this.db.prepare(`
+      SELECT id, space_id, inviter_id, invitee_id, role, status,
+             created_at, expires_at, resolved_at
+      FROM dev_space_invitations
+      WHERE app_id = ?
+      ORDER BY created_at, id
+    `).all(this.appId).map((row) => ({
+      id: String(row.id),
+      spaceId: String(row.space_id),
+      inviter: String(row.inviter_id),
+      invitee: String(row.invitee_id),
+      role: String(row.role),
+      status: String(row.status),
+      createdAt: String(row.created_at),
+      expiresAt: String(row.expires_at),
+      resolvedAt: row.resolved_at === null ? null : String(row.resolved_at),
+    }));
+  }
+
+  saveSpaceInvitations(invitations) {
+    transaction(this.db, () => {
+      this.db.prepare("DELETE FROM dev_space_invitations WHERE app_id = ?").run(this.appId);
+      const insert = this.db.prepare(`
+        INSERT INTO dev_space_invitations
+          (id, app_id, space_id, inviter_id, invitee_id, role, status,
+           created_at, expires_at, resolved_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+      for (const invitation of invitations) {
+        insert.run(
+          invitation.id,
+          this.appId,
+          invitation.spaceId,
+          invitation.inviter,
+          invitation.invitee,
+          invitation.role,
+          invitation.status,
+          invitation.createdAt,
+          invitation.expiresAt,
+          invitation.resolvedAt,
+        );
+      }
+    });
+  }
+
+  loadUserBlocks() {
+    return this.db.prepare(`
+      SELECT blocker_id, blocked_id
+      FROM dev_user_blocks
+      WHERE app_id = ?
+      ORDER BY blocker_id, blocked_id
+    `).all(this.appId).map((row) => ({
+      blocker: String(row.blocker_id),
+      blocked: String(row.blocked_id),
+    }));
+  }
+
+  saveUserBlocks(blocks) {
+    transaction(this.db, () => {
+      this.db.prepare("DELETE FROM dev_user_blocks WHERE app_id = ?").run(this.appId);
+      const insert = this.db.prepare(`
+        INSERT INTO dev_user_blocks (app_id, blocker_id, blocked_id, created_at)
+        VALUES (?, ?, ?, ?)
+      `);
+      const now = new Date().toISOString();
+      for (const block of blocks) {
+        insert.run(this.appId, block.blocker, block.blocked, now);
+      }
+    });
+  }
+
+  collectionDefinitions() {
+    return this.db.prepare(
+      "SELECT name, definition_json FROM collection_definitions WHERE app_id = ? ORDER BY name",
+    ).all(this.appId).map((row) => [String(row.name), parseJson(row.definition_json, {})]);
+  }
+
+  defineCollection(name, definition) {
+    const encoded = JSON.stringify(definition);
+    const row = this.db.prepare(`
+      SELECT definition_json FROM collection_definitions WHERE app_id = ? AND name = ?
+    `).get(this.appId, name);
+    if (row) return { existing: parseJson(row.definition_json, {}), created: false };
+    this.db.prepare(`
+      INSERT INTO collection_definitions (app_id, name, definition_json, created_at)
+      VALUES (?, ?, ?, ?)
+    `).run(this.appId, name, encoded, new Date().toISOString());
+    return { existing: definition, created: true };
+  }
+
+  /** Everything the system database keeps for one space, gone with it: its
+   * invitations, delivery sequence and cursors, and its collaboration
+   * journals. (The space row itself leaves with the next saveSpaces.) */
+  deleteSpace(spaceId) {
+    transaction(this.db, () => {
+      for (const table of ["dev_space_invitations", "space_delivery_sequences", "record_deliveries", "space_member_cursors"]) {
+        this.db.prepare(`DELETE FROM ${table} WHERE app_id = ? AND space_id = ?`).run(this.appId, spaceId);
+      }
+      for (const table of ["collaboration_operations", "collaboration_receipts", "collaboration_streams"]) {
+        this.db.prepare(`DELETE FROM ${table} WHERE app_id = ? AND scope_key = ?`)
+          .run(this.appId, `space:${spaceId}`);
+      }
+    });
+  }
+
+  /** The receipt a delivery left under `mutationId`, or null: what it named,
+   * its sequence and recipients, and its answer once it committed. */
+  deliveryReceipt({ spaceId, collection, mutationId }) {
+    const row = this.db.prepare(`
+      SELECT record_id, request_sha256, sequence, recipients_json, status, response_json
+      FROM record_deliveries
+      WHERE app_id = ? AND space_id = ? AND collection_name = ? AND mutation_id = ?
+    `).get(this.appId, spaceId, collection, mutationId);
+    return row
+      ? {
+          recordId: String(row.record_id),
+          requestSha256: String(row.request_sha256),
+          sequence: Number(row.sequence),
+          recipients: parseJson(row.recipients_json, []),
+          response: row.status === "committed" ? parseJson(row.response_json, {}) : null,
+        }
+      : null;
+  }
+
+  beginDelivery({ spaceId, collection, mutationId, recordId, requestSha256, recipients }) {
+    return transaction(this.db, () => {
+      const existing = this.deliveryReceipt({ spaceId, collection, mutationId });
+      if (existing) {
+        if (existing.recordId !== recordId || existing.requestSha256 !== requestSha256) {
+          return {
+            conflict: "Idempotency-Key was already used for a different delivery",
+            code: "idempotency_conflict",
+          };
+        }
+        return { sequence: existing.sequence, recipients: existing.recipients, response: existing.response };
+      }
+      this.db.prepare(`
+        INSERT INTO space_delivery_sequences (app_id, space_id, head_sequence)
+        VALUES (?, ?, 0) ON CONFLICT (app_id, space_id) DO NOTHING
+      `).run(this.appId, spaceId);
+      this.db.prepare(`
+        UPDATE space_delivery_sequences SET head_sequence = head_sequence + 1
+        WHERE app_id = ? AND space_id = ?
+      `).run(this.appId, spaceId);
+      const sequence = Number(this.db.prepare(`
+        SELECT head_sequence FROM space_delivery_sequences WHERE app_id = ? AND space_id = ?
+      `).get(this.appId, spaceId).head_sequence);
+      const now = new Date().toISOString();
+      this.db.prepare(`
+        INSERT INTO record_deliveries
+          (app_id, space_id, collection_name, mutation_id, record_id,
+           request_sha256, sequence, recipients_json, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        this.appId,
+        spaceId,
+        collection,
+        mutationId,
+        recordId,
+        requestSha256,
+        sequence,
+        JSON.stringify(recipients),
+        now,
+        now,
+      );
+      return { sequence, recipients, response: null };
+    });
+  }
+
+  commitDelivery({ spaceId, collection, mutationId, response }) {
+    transaction(this.db, () => {
+      const now = new Date().toISOString();
+      this.db.prepare(`
+        UPDATE record_deliveries
+        SET status = 'committed', response_json = ?, updated_at = ?
+        WHERE app_id = ? AND space_id = ? AND collection_name = ? AND mutation_id = ?
+      `).run(JSON.stringify(response), now, this.appId, spaceId, collection, mutationId);
+      const upsert = this.db.prepare(`
+        INSERT INTO space_member_cursors
+          (app_id, space_id, member_id, delivered_through, read_through, updated_at)
+        VALUES (?, ?, ?, ?, 0, ?)
+        ON CONFLICT (app_id, space_id, member_id) DO UPDATE SET
+          delivered_through = MAX(space_member_cursors.delivered_through, excluded.delivered_through),
+          updated_at = excluded.updated_at
+      `);
+      for (const member of response.recipients ?? []) {
+        upsert.run(this.appId, spaceId, member, response.sequence, now);
+      }
+    });
+  }
+
+  /** Delivery and read marks: current `members` (with `roles`), then any
+   * former member who still has a row, with role null. */
+  spaceCursors(spaceId, members, roles = {}) {
+    const head = Number(this.db.prepare(`
+      SELECT head_sequence FROM space_delivery_sequences WHERE app_id = ? AND space_id = ?
+    `).get(this.appId, spaceId)?.head_sequence ?? 0);
+    const rows = this.db.prepare(`
+      SELECT member_id, delivered_through, read_through FROM space_member_cursors
+      WHERE app_id = ? AND space_id = ?
+    `).all(this.appId, spaceId);
+    const byMember = new Map(rows.map((row) => [String(row.member_id), row]));
+    const participants = [...new Set([...members, ...byMember.keys()])];
+    return {
+      head_sequence: head,
+      members: participants.map((member) => {
+        const cursor = byMember.get(member) ?? {};
+        return {
+          user_id: member,
+          role: members.includes(member) ? (roles[member] ?? null) : null,
+          delivered_through: Number(cursor.delivered_through ?? 0),
+          read_through: Number(cursor.read_through ?? 0),
+        };
+      }),
+    };
+  }
+
+  /** Move a member's cursors forward (never back). Answers the door's body
+   * and, apart, whether either value actually increased — only a real move
+   * is worth telling the space about. */
+  updateSpaceCursor(spaceId, member, { deliveredThrough, readThrough }) {
+    return transaction(this.db, () => {
+      const state = this.spaceCursors(spaceId, [member]);
+      const current = state.members[0];
+      const delivered = Math.max(current.delivered_through, deliveredThrough ?? current.delivered_through);
+      const read = Math.max(current.read_through, readThrough ?? current.read_through);
+      if (delivered > state.head_sequence || read > delivered) {
+        return { conflict: "cursor cannot pass the delivered space frontier" };
+      }
+      const advanced = delivered > current.delivered_through || read > current.read_through;
+      this.db.prepare(`
+        INSERT INTO space_member_cursors
+          (app_id, space_id, member_id, delivered_through, read_through, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?)
+        ON CONFLICT (app_id, space_id, member_id) DO UPDATE SET
+          delivered_through = excluded.delivered_through,
+          read_through = excluded.read_through,
+          updated_at = excluded.updated_at
+      `).run(this.appId, spaceId, member, delivered, read, new Date().toISOString());
+      return {
+        cursor: {
+          delivered_through: delivered,
+          read_through: read,
+          head_sequence: state.head_sequence,
+        },
+        advanced,
+      };
+    });
+  }
+
+  appendCollaboration({ scopeKey, documentId, actor, sessionId, operations }) {
+    return transaction(this.db, () => {
+      const now = new Date().toISOString();
+      this.db.prepare(`
+        INSERT INTO collaboration_streams
+          (app_id, scope_key, document_id, updated_at)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT (app_id, scope_key, document_id) DO NOTHING
+      `).run(this.appId, scopeKey, documentId, now);
+      for (const item of operations) {
+        const encoded = JSON.stringify(item.operation);
+        const committed = (table) => this.db.prepare(`
+          SELECT operation_json FROM ${table}
+          WHERE app_id = ? AND scope_key = ? AND document_id = ?
+            AND actor_user_id = ? AND operation_id = ?
+        `).get(this.appId, scopeKey, documentId, actor, item.id);
+        const existing = committed("collaboration_operations") ?? committed("collaboration_receipts");
+        if (existing) {
+          if (String(existing.operation_json) !== encoded) {
+            return {
+              conflict: `operation id '${item.id}' was reused with different content`,
+              code: "idempotency_conflict",
+            };
+          }
+          continue;
+        }
+        this.db.prepare(`
+          UPDATE collaboration_streams
+          SET head_sequence = head_sequence + 1, updated_at = ?
+          WHERE app_id = ? AND scope_key = ? AND document_id = ?
+        `).run(now, this.appId, scopeKey, documentId);
+        const sequence = Number(this.db.prepare(`
+          SELECT head_sequence FROM collaboration_streams
+          WHERE app_id = ? AND scope_key = ? AND document_id = ?
+        `).get(this.appId, scopeKey, documentId).head_sequence);
+        this.db.prepare(`
+          INSERT INTO collaboration_operations
+            (app_id, scope_key, document_id, sequence, actor_user_id,
+             actor_session_id, operation_id, operation_json, committed_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(
+          this.appId,
+          scopeKey,
+          documentId,
+          sequence,
+          actor,
+          sessionId,
+          item.id,
+          encoded,
+          now,
+        );
+      }
+      return this.listCollaboration({ scopeKey, documentId, actor, operationIds: operations.map((item) => item.id) });
+    });
+  }
+
+  listCollaboration({ scopeKey, documentId, after = 0, limit = LIMITS.page_size, actor, operationIds }) {
+    const stream = this.db.prepare(`
+      SELECT head_sequence, retained_after_sequence, snapshot_sequence, snapshot_json
+      FROM collaboration_streams
+      WHERE app_id = ? AND scope_key = ? AND document_id = ?
+    `).get(this.appId, scopeKey, documentId) ?? {
+      head_sequence: 0,
+      retained_after_sequence: 0,
+      snapshot_sequence: 0,
+      snapshot_json: null,
+    };
+    let rows;
+    if (actor && operationIds) {
+      if (!operationIds.length) rows = [];
+      else {
+        // An append's answer: where each of its ids committed, compacted or not.
+        const placeholders = operationIds.map(() => "?").join(", ");
+        const select = (table) => `
+          SELECT sequence, actor_user_id, actor_session_id, operation_id,
+                 operation_json, committed_at
+          FROM ${table}
+          WHERE app_id = ? AND scope_key = ? AND document_id = ?
+            AND actor_user_id = ? AND operation_id IN (${placeholders})`;
+        const bind = [this.appId, scopeKey, documentId, actor, ...operationIds];
+        rows = this.db.prepare(`
+          ${select("collaboration_operations")}
+          UNION ALL ${select("collaboration_receipts")}
+          ORDER BY sequence
+        `).all(...bind, ...bind);
+      }
+    } else {
+      rows = this.db.prepare(`
+        SELECT sequence, actor_user_id, actor_session_id, operation_id,
+               operation_json, committed_at
+        FROM collaboration_operations
+        WHERE app_id = ? AND scope_key = ? AND document_id = ? AND sequence > ?
+        ORDER BY sequence LIMIT ?
+      `).all(this.appId, scopeKey, documentId, after, Math.max(1, Math.min(LIMITS.page_size, limit)) + 1);
+    }
+    return {
+      head: Number(stream.head_sequence),
+      retainedAfter: Number(stream.retained_after_sequence),
+      snapshotSequence: Number(stream.snapshot_sequence),
+      snapshot: parseJson(stream.snapshot_json, null),
+      hasMore: !operationIds && rows.length > Math.max(1, Math.min(LIMITS.page_size, limit)),
+      operations: rows.slice(0, operationIds ? rows.length : Math.max(1, Math.min(LIMITS.page_size, limit))).map((row) => ({
+        cursor: Number(row.sequence),
+        actor_user_id: String(row.actor_user_id),
+        actor_session_id: String(row.actor_session_id),
+        id: String(row.operation_id),
+        operation: parseJson(row.operation_json, null),
+        committed_at: String(row.committed_at),
+      })),
+    };
+  }
+
+  /**
+   * The platform's collaboration compactor (terminus-backend
+   * services/app_collaboration.rs): for up to `streams` journals whose
+   * snapshot has moved past their reset frontier, the operations the
+   * snapshot covers — at most `operations` each — leave the journal for its
+   * receipts, and the frontier moves up to them, so a reader behind it gets
+   * the snapshot and the tail. Answers how many operations moved.
+   */
+  compactCollaboration({ streams = 20, operations = 2000 } = {}) {
+    return transaction(this.db, () => {
+      const due = this.db.prepare(`
+        SELECT scope_key, document_id, snapshot_sequence FROM collaboration_streams
+        WHERE app_id = ? AND snapshot_json IS NOT NULL
+          AND snapshot_sequence > retained_after_sequence
+        ORDER BY updated_at LIMIT ?
+      `).all(this.appId, streams);
+      let moved = 0;
+      for (const stream of due) {
+        const key = [this.appId, stream.scope_key, stream.document_id];
+        const through = this.db.prepare(`
+          SELECT MAX(sequence) AS through FROM (
+            SELECT sequence FROM collaboration_operations
+            WHERE app_id = ? AND scope_key = ? AND document_id = ? AND sequence <= ?
+            ORDER BY sequence LIMIT ?
+          )
+        `).get(...key, stream.snapshot_sequence, operations)?.through;
+        if (through === null || through === undefined) continue;
+        this.db.prepare(`
+          INSERT OR IGNORE INTO collaboration_receipts
+            (app_id, scope_key, document_id, sequence, actor_user_id,
+             actor_session_id, operation_id, operation_json, committed_at)
+          SELECT app_id, scope_key, document_id, sequence, actor_user_id,
+                 actor_session_id, operation_id, operation_json, committed_at
+          FROM collaboration_operations
+          WHERE app_id = ? AND scope_key = ? AND document_id = ? AND sequence <= ?
+        `).run(...key, through);
+        moved += Number(this.db.prepare(`
+          DELETE FROM collaboration_operations
+          WHERE app_id = ? AND scope_key = ? AND document_id = ? AND sequence <= ?
+        `).run(...key, through).changes);
+        this.db.prepare(`
+          UPDATE collaboration_streams
+          SET retained_after_sequence = MAX(retained_after_sequence, ?), updated_at = ?
+          WHERE app_id = ? AND scope_key = ? AND document_id = ?
+        `).run(through, new Date().toISOString(), ...key);
+      }
+      return moved;
+    });
+  }
+
+  snapshotCollaboration({ scopeKey, documentId, through, snapshot }) {
+    return transaction(this.db, () => {
+      const stream = this.db.prepare(`
+        SELECT head_sequence, snapshot_sequence FROM collaboration_streams
+        WHERE app_id = ? AND scope_key = ? AND document_id = ?
+      `).get(this.appId, scopeKey, documentId);
+      if (!stream || through < Number(stream.snapshot_sequence) || through > Number(stream.head_sequence)) {
+        return { conflict: "snapshot cursor is behind the current snapshot or ahead of the stream" };
+      }
+      this.db.prepare(`
+        UPDATE collaboration_streams
+        SET snapshot_sequence = ?, snapshot_json = ?, updated_at = ?
+        WHERE app_id = ? AND scope_key = ? AND document_id = ?
+      `).run(
+        through,
+        JSON.stringify(snapshot),
+        new Date().toISOString(),
+        this.appId,
+        scopeKey,
+        documentId,
+      );
+      return { head: Number(stream.head_sequence), through };
+    });
+  }
+
+  /** One app-server record, or null. */
+  serverRecord({ scope, installationId, collection, docId }) {
+    const row = this.db.prepare(`
+      SELECT data_json, version FROM app_server_records
+      WHERE app_id = ? AND scope = ? AND installation_id = ? AND collection = ? AND doc_id = ?
+    `).get(this.appId, scope, installationId ?? "", collection, docId);
+    return row ? { data: JSON.parse(String(row.data_json)), version: Number(row.version) } : null;
+  }
+
+  /** Every record in one collection of one pool, in no order: the caller
+   * filters and orders them the way the platform's query does. */
+  serverRecords({ scope, installationId, collection }) {
+    return this.db.prepare(`
+      SELECT doc_id, data_json, version FROM app_server_records
+      WHERE app_id = ? AND scope = ? AND installation_id = ? AND collection = ?
+    `).all(this.appId, scope, installationId ?? "", collection).map((row) => ({
+      docId: String(row.doc_id),
+      data: JSON.parse(String(row.data_json)),
+      version: Number(row.version),
+    }));
+  }
+
+  /**
+   * Write one record the platform's way. `ifVersion`: null = unconditional,
+   * 0 = must not exist, n = must be at n; a mismatch is a conflict, never a
+   * clobber. The pool's byte total moves as the platform's does — a new
+   * document at `newBytes`, the one it replaces at the size it was stored
+   * at — and a write that would cross `quotaBytes` never happens.
+   * Answers `{version}`, `{conflict}` or `{overQuota}`.
+   */
+  putServerRecord({ scope, installationId, collection, docId, dataJson, newBytes, storedBytes, ifVersion, quotaBytes }) {
+    const installation = installationId ?? "";
+    try {
+      return transaction(this.db, () => {
+        const existing = this.db.prepare(`
+          SELECT version, stored_bytes FROM app_server_records
+          WHERE app_id = ? AND scope = ? AND installation_id = ? AND collection = ? AND doc_id = ?
+        `).get(this.appId, scope, installation, collection, docId);
+        const conflict = serverVersionConflict(ifVersion, existing ? Number(existing.version) : null);
+        if (conflict) return { conflict };
+        const now = new Date().toISOString();
+        let version;
+        let byteDelta;
+        let countDelta;
+        if (existing) {
+          version = Number(existing.version) + 1;
+          byteDelta = newBytes - Number(existing.stored_bytes);
+          countDelta = 0;
+          this.db.prepare(`
+            UPDATE app_server_records
+            SET data_json = ?, stored_bytes = ?, version = ?, updated_at = ?
+            WHERE app_id = ? AND scope = ? AND installation_id = ? AND collection = ? AND doc_id = ?
+          `).run(dataJson, storedBytes, version, now, this.appId, scope, installation, collection, docId);
+        } else {
+          version = 1;
+          byteDelta = newBytes;
+          countDelta = 1;
+          this.db.prepare(`
+            INSERT INTO app_server_records
+              (app_id, scope, installation_id, collection, doc_id, data_json, stored_bytes, version, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, 1, ?, ?)
+          `).run(this.appId, scope, installation, collection, docId, dataJson, storedBytes, now, now);
+        }
+        const total = this.bumpServerRecordTotals(scope, installation, byteDelta, countDelta);
+        if (total > quotaBytes) throw new ServerQuotaExceeded(total);
+        return { version };
+      });
+    } catch (error) {
+      if (error instanceof ServerQuotaExceeded) return { overQuota: error.total };
+      throw error;
+    }
+  }
+
+  /** Delete one record under the same version rules. Answers `{deleted}` or `{conflict}`. */
+  deleteServerRecord({ scope, installationId, collection, docId, ifVersion }) {
+    const installation = installationId ?? "";
+    return transaction(this.db, () => {
+      const existing = this.db.prepare(`
+        SELECT version, stored_bytes FROM app_server_records
+        WHERE app_id = ? AND scope = ? AND installation_id = ? AND collection = ? AND doc_id = ?
+      `).get(this.appId, scope, installation, collection, docId);
+      const conflict = serverVersionConflict(ifVersion, existing ? Number(existing.version) : null);
+      if (conflict) return { conflict };
+      if (!existing) return { deleted: false };
+      this.db.prepare(`
+        DELETE FROM app_server_records
+        WHERE app_id = ? AND scope = ? AND installation_id = ? AND collection = ? AND doc_id = ?
+      `).run(this.appId, scope, installation, collection, docId);
+      this.bumpServerRecordTotals(scope, installation, -Number(existing.stored_bytes), -1);
+      return { deleted: true };
+    });
+  }
+
+  /** The pool's running totals, floored at zero like the platform's. */
+  bumpServerRecordTotals(scope, installationId, byteDelta, countDelta) {
+    const row = this.db.prepare(`
+      INSERT INTO app_server_record_totals (app_id, scope, installation_id, total_bytes, record_count)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT (app_id, scope, installation_id) DO UPDATE SET
+        total_bytes = MAX(total_bytes + excluded.total_bytes, 0),
+        record_count = MAX(record_count + excluded.record_count, 0)
+      RETURNING total_bytes
+    `).get(this.appId, scope, installationId, byteDelta, countDelta);
+    return Number(row.total_bytes);
+  }
+
+  /** Count one server web fetch against an installation's UTC day; answers the day's count. */
+  bumpServerFetches(installationId, day) {
+    const row = this.db.prepare(`
+      INSERT INTO app_server_fetch_counters (app_id, installation_id, day, requests)
+      VALUES (?, ?, ?, 1)
+      ON CONFLICT (app_id, installation_id, day) DO UPDATE SET requests = requests + 1
+      RETURNING requests
+    `).get(this.appId, installationId, day);
+    return Number(row.requests);
+  }
+
+  close() {
+    this.db.close();
+  }
+}
+
+class ServerQuotaExceeded extends Error {
+  constructor(total) {
+    super("server records quota exceeded");
+    this.total = total;
+  }
+}
+
+/** The platform's optimistic check (records.rs `check_version`), word for word:
+ * apps match on "reread and retry" and "requires absence". */
+function serverVersionConflict(expected, actual) {
+  if (expected === null || expected === undefined) return null;
+  if (expected === 0) {
+    return actual === null ? null : "the record already exists (if_version 0 requires absence)";
+  }
+  if (actual === null) return "the record no longer exists — reread and retry";
+  return expected === actual ? null : `the record changed (version is now ${actual}) — reread and retry`;
+}
+
+export class DevCapsuleStore {
+  constructor(rootDir, appId, member) {
+    this.appId = appId;
+    this.member = member;
+    this.directory = devCapsuleDirectory(rootDir, appId, member);
+    this.objectsDirectory = path.join(this.directory, "objects");
+    mkdirSync(this.objectsDirectory, { recursive: true });
+    this.file = path.join(this.directory, "data.sqlite");
+    this.db = new DatabaseSync(this.file);
+    configure(this.db);
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS _terminus_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS _terminus_collection_scopes (
+        scope_key TEXT PRIMARY KEY,
+        head_cursor INTEGER NOT NULL DEFAULT 0 CHECK (head_cursor >= 0),
+        retained_after_cursor INTEGER NOT NULL DEFAULT 0 CHECK (retained_after_cursor >= 0),
+        CHECK (retained_after_cursor <= head_cursor)
+      );
+
+      CREATE TABLE IF NOT EXISTS _terminus_records (
+        scope_key TEXT NOT NULL,
+        collection_name TEXT NOT NULL,
+        record_id TEXT NOT NULL,
+        value_json TEXT NOT NULL CHECK (json_valid(value_json)),
+        version INTEGER NOT NULL CHECK (version > 0),
+        created_by_user_id TEXT NOT NULL,
+        updated_by_user_id TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        delivery_sequence INTEGER CHECK (delivery_sequence IS NULL OR delivery_sequence > 0),
+        delivery_recipients_json TEXT CHECK (
+          delivery_recipients_json IS NULL OR json_valid(delivery_recipients_json)
+        ),
+        PRIMARY KEY (scope_key, collection_name, record_id)
+      );
+
+      CREATE TABLE IF NOT EXISTS _terminus_mutations (
+        scope_key TEXT NOT NULL,
+        collection_name TEXT NOT NULL,
+        mutation_id TEXT NOT NULL,
+        request_sha256 TEXT NOT NULL,
+        response_json TEXT NOT NULL CHECK (json_valid(response_json)),
+        committed_at TEXT NOT NULL,
+        PRIMARY KEY (scope_key, collection_name, mutation_id)
+      );
+
+      CREATE TABLE IF NOT EXISTS _terminus_transactions (
+        transaction_scope TEXT NOT NULL,
+        transaction_id TEXT NOT NULL,
+        request_sha256 TEXT NOT NULL,
+        response_json TEXT NOT NULL CHECK (json_valid(response_json)),
+        committed_at TEXT NOT NULL,
+        PRIMARY KEY (transaction_scope, transaction_id)
+      );
+
+      CREATE TABLE IF NOT EXISTS _terminus_changes (
+        scope_key TEXT NOT NULL,
+        cursor INTEGER NOT NULL CHECK (cursor > 0),
+        change_json TEXT NOT NULL CHECK (json_valid(change_json)),
+        committed_at TEXT NOT NULL,
+        PRIMARY KEY (scope_key, cursor)
+      );
+
+      CREATE TABLE IF NOT EXISTS _terminus_object_refs (
+        bucket_name TEXT NOT NULL,
+        object_path TEXT NOT NULL,
+        content_sha256 TEXT NOT NULL,
+        size_bytes INTEGER NOT NULL CHECK (size_bytes >= 0),
+        media_type TEXT,
+        version INTEGER NOT NULL DEFAULT 1,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (bucket_name, object_path)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_capsule_records_collection
+        ON _terminus_records (scope_key, collection_name, record_id);
+      CREATE INDEX IF NOT EXISTS idx_capsule_changes_scope_cursor
+        ON _terminus_changes (scope_key, cursor);
+      CREATE INDEX IF NOT EXISTS idx_capsule_objects_bucket_path
+        ON _terminus_object_refs (bucket_name, object_path);
+    `);
+    ensureColumns(this.db, "_terminus_records", {
+      delivery_sequence: "INTEGER",
+      delivery_recipients_json: "TEXT",
+    });
+    ensureColumns(this.db, "_terminus_object_refs", { version: "INTEGER NOT NULL DEFAULT 1" });
+    this.db.prepare(`
+      INSERT INTO _terminus_meta (key, value) VALUES ('capsule_format_version', ?)
+      ON CONFLICT (key) DO UPDATE SET value = excluded.value
+    `).run(String(CAPSULE_FORMAT_VERSION));
+    this.writeManifest();
+  }
+
+  writeManifest() {
+    const manifestPath = path.join(this.directory, "manifest.json");
+    let createdAt = new Date().toISOString();
+    try {
+      createdAt = JSON.parse(readFileSync(manifestPath, "utf8")).created_at ?? createdAt;
+    } catch {
+      // First creation.
+    }
+    atomicWriteBytes(manifestPath, Buffer.from(`${JSON.stringify({
+      capsule_format_version: CAPSULE_FORMAT_VERSION,
+      app_id: this.appId,
+      owner_user_id: this.member,
+      database: "data.sqlite",
+      objects: "objects/",
+      created_at: createdAt,
+      updated_at: new Date().toISOString(),
+    }, null, 2)}\n`, "utf8"));
+  }
+
+  scopeWindow(scopeKey) {
+    const row = this.db.prepare(`
+      SELECT head_cursor, retained_after_cursor
+      FROM _terminus_collection_scopes WHERE scope_key = ?
+    `).get(scopeKey);
+    return row
+      ? { head: Number(row.head_cursor), retainedAfter: Number(row.retained_after_cursor) }
+      : { head: 0, retainedAfter: 0 };
+  }
+
+  listRecords(scopeKey, collection) {
+    return this.db.prepare(`
+      SELECT record_id, value_json, version, created_by_user_id, updated_by_user_id,
+             created_at, updated_at, delivery_sequence, delivery_recipients_json
+      FROM _terminus_records
+      WHERE scope_key = ? AND collection_name = ?
+      ORDER BY record_id
+    `).all(scopeKey, collection).map((row) => ({
+      id: String(row.record_id),
+      value: parseJson(row.value_json, {}),
+      version: Number(row.version),
+      created_by_user_id: String(row.created_by_user_id),
+      updated_by_user_id: String(row.updated_by_user_id),
+      created_at: String(row.created_at),
+      updated_at: String(row.updated_at),
+      delivery_sequence: row.delivery_sequence === null ? null : Number(row.delivery_sequence),
+      delivery_recipients: parseJson(row.delivery_recipients_json, null),
+    }));
+  }
+
+  getRecord(scopeKey, collection, recordId) {
+    const row = this.db.prepare(`
+      SELECT value_json, version, created_by_user_id, updated_by_user_id,
+             created_at, updated_at, delivery_sequence, delivery_recipients_json
+      FROM _terminus_records
+      WHERE scope_key = ? AND collection_name = ? AND record_id = ?
+    `).get(scopeKey, collection, recordId);
+    if (!row) return null;
+    return {
+      id: recordId,
+      value: parseJson(row.value_json, {}),
+      version: Number(row.version),
+      created_by_user_id: String(row.created_by_user_id),
+      updated_by_user_id: String(row.updated_by_user_id),
+      created_at: String(row.created_at),
+      updated_at: String(row.updated_at),
+      delivery_sequence: row.delivery_sequence === null ? null : Number(row.delivery_sequence),
+      delivery_recipients: parseJson(row.delivery_recipients_json, null),
+    };
+  }
+
+  /** The receipt a record write left under `mutationId`, or null. */
+  mutationReceipt(scopeKey, collection, mutationId) {
+    const row = this.db.prepare(`
+      SELECT request_sha256, response_json
+      FROM _terminus_mutations
+      WHERE scope_key = ? AND collection_name = ? AND mutation_id = ?
+    `).get(scopeKey, collection, mutationId);
+    return row
+      ? { requestSha256: String(row.request_sha256), response: parseJson(row.response_json, {}) }
+      : null;
+  }
+
+  /** The receipt a transaction left under `transactionId`, or null. */
+  transactionReceipt(transactionScope, transactionId) {
+    const row = this.db.prepare(`
+      SELECT request_sha256, response_json
+      FROM _terminus_transactions
+      WHERE transaction_scope = ? AND transaction_id = ?
+    `).get(transactionScope, transactionId);
+    return row
+      ? { requestSha256: String(row.request_sha256), response: parseJson(row.response_json, {}) }
+      : null;
+  }
+
+  mutateRecord(input) {
+    return transaction(this.db, () => this._mutateRecord(input));
+  }
+
+  _mutateRecord({
+    scopeKey,
+    collection,
+    recordId,
+    mutationId,
+    requestSha256,
+    operation,
+    expectedVersion,
+    value,
+    actor,
+    deliverySequence = null,
+    deliveryRecipients = null,
+  }) {
+    const replay = this.mutationReceipt(scopeKey, collection, mutationId);
+      if (replay) {
+        if (replay.requestSha256 !== requestSha256) {
+          return {
+            conflict: "Idempotency-Key was already used for a different mutation",
+            code: "idempotency_conflict",
+          };
+        }
+        return { response: { ...replay.response, replayed: true }, changes: [] };
+      }
+
+      const prior = this.getRecord(scopeKey, collection, recordId);
+      const currentVersion = prior?.version ?? 0;
+      if (
+        (expectedVersion === 0 && prior !== null)
+        || (expectedVersion !== null && expectedVersion > 0 && expectedVersion !== currentVersion)
+      ) {
+        return {
+          conflict: `record version changed (current ${currentVersion}); refresh before retrying`,
+          code: "version_conflict",
+        };
+      }
+
+      const now = new Date().toISOString();
+      const version = currentVersion + 1;
+      const createdBy = prior?.created_by_user_id ?? actor;
+      const createdAt = prior?.created_at ?? now;
+      if (operation === "put") {
+        this.db.prepare(`
+          INSERT INTO _terminus_records
+            (scope_key, collection_name, record_id, value_json, version,
+             created_by_user_id, updated_by_user_id, created_at, updated_at,
+             delivery_sequence, delivery_recipients_json)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          ON CONFLICT (scope_key, collection_name, record_id) DO UPDATE SET
+            value_json = excluded.value_json,
+            version = excluded.version,
+            updated_by_user_id = excluded.updated_by_user_id,
+            updated_at = excluded.updated_at,
+            delivery_sequence = excluded.delivery_sequence,
+            delivery_recipients_json = excluded.delivery_recipients_json
+        `).run(
+          scopeKey,
+          collection,
+          recordId,
+          JSON.stringify(value),
+          version,
+          createdBy,
+          actor,
+          createdAt,
+          now,
+          deliverySequence,
+          deliveryRecipients === null ? null : JSON.stringify(deliveryRecipients),
+        );
+      } else {
+        this.db.prepare(`
+          DELETE FROM _terminus_records
+          WHERE scope_key = ? AND collection_name = ? AND record_id = ?
+        `).run(scopeKey, collection, recordId);
+      }
+
+      this.db.prepare(`
+        INSERT INTO _terminus_collection_scopes (scope_key, head_cursor, retained_after_cursor)
+        VALUES (?, 0, 0) ON CONFLICT (scope_key) DO NOTHING
+      `).run(scopeKey);
+      const window = this.scopeWindow(scopeKey);
+      const cursor = window.head + 1;
+      const change = {
+        operation,
+        record_id: recordId,
+        mutation_id: mutationId,
+        committed_version: version,
+        version: operation === "put" ? version : null,
+        value: operation === "put" ? value : null,
+        actor_user_id: actor,
+        created_by_user_id: operation === "put" ? createdBy : null,
+        updated_by_user_id: operation === "put" ? actor : null,
+        policy_record: operation === "put" ? value : prior?.value ?? null,
+        policy_created_by_user_id: prior?.created_by_user_id ?? (operation === "put" ? actor : null),
+        policy_updated_by_user_id: operation === "put" ? actor : prior?.updated_by_user_id ?? null,
+        delivery_sequence: operation === "put" ? deliverySequence : null,
+        delivery_recipients: operation === "put" ? deliveryRecipients : null,
+        changed_fields: changedRecordFields(prior?.value, operation === "put" ? value : undefined),
+        // The platform's clock beside the change's own commit time: when the
+        // record was first written, so a live projection can keep it.
+        created_at: operation === "put" ? createdAt : null,
+        committed_at: now,
+        cursor,
+      };
+      this.db.prepare(`
+        INSERT INTO _terminus_changes (scope_key, cursor, change_json, committed_at)
+        VALUES (?, ?, ?, ?)
+      `).run(scopeKey, cursor, JSON.stringify(change), now);
+
+      const retainedAfter = Math.max(window.retainedAfter, cursor - CHANGE_RETENTION);
+      if (retainedAfter > window.retainedAfter) {
+        this.db.prepare(`
+          DELETE FROM _terminus_changes WHERE scope_key = ? AND cursor <= ?
+        `).run(scopeKey, retainedAfter);
+      }
+      this.db.prepare(`
+        UPDATE _terminus_collection_scopes
+        SET head_cursor = ?, retained_after_cursor = ?
+        WHERE scope_key = ?
+      `).run(cursor, retainedAfter, scopeKey);
+
+      const response = operation === "put"
+        ? {
+            id: recordId,
+            value,
+            version,
+            mutation_id: mutationId,
+            sync_cursor: `c1_${cursor}`,
+            created_at: createdAt,
+            updated_at: now,
+            created_by_user_id: createdBy,
+            updated_by_user_id: actor,
+            delivery_sequence: deliverySequence,
+            delivery_recipients: deliveryRecipients,
+          }
+        : { ok: true, mutation_id: mutationId, sync_cursor: `c1_${cursor}` };
+      this.db.prepare(`
+        INSERT INTO _terminus_mutations
+          (scope_key, collection_name, mutation_id, request_sha256, response_json, committed_at)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `).run(scopeKey, collection, mutationId, requestSha256, JSON.stringify(response), now);
+    return { response, changes: [change] };
+  }
+
+  transactRecords({ transactionScope, transactionId, requestSha256, operations, actor }) {
+    return transaction(this.db, () => {
+      const replay = this.transactionReceipt(transactionScope, transactionId);
+      if (replay) {
+        if (replay.requestSha256 !== requestSha256) {
+          return {
+            conflict: "Idempotency-Key was already used for a different transaction",
+            code: "idempotency_conflict",
+          };
+        }
+        return { response: { ...replay.response, replayed: true }, changes: [] };
+      }
+
+      for (const operation of operations) {
+        const prior = this.getRecord(operation.scopeKey, operation.collection, operation.recordId);
+        const currentVersion = prior?.version ?? 0;
+        if (
+          (operation.expectedVersion === 0 && prior !== null)
+          || (operation.expectedVersion !== null
+            && operation.expectedVersion > 0
+            && operation.expectedVersion !== currentVersion)
+        ) {
+          return {
+            conflict: `record '${operation.collection}/${operation.recordId}' changed (current ${currentVersion}); refresh before retrying`,
+            code: "version_conflict",
+          };
+        }
+      }
+
+      const results = [];
+      const cascaded = [];
+      const changes = [];
+      for (const [index, operation] of operations.entries()) {
+        const mutationId = operation.mutationId ?? `tx:${sha256(
+          `${transactionId}:${index}:${operation.operation}:${operation.collection}:${operation.recordId}`,
+        )}`;
+        const mutationSignature = sha256(JSON.stringify({
+          transactionId,
+          index,
+          operation: operation.operation,
+          collection: operation.collection,
+          recordId: operation.recordId,
+          expectedVersion: operation.expectedVersion,
+          value: operation.value,
+        }));
+        const result = this._mutateRecord({
+          ...operation,
+          mutationId,
+          requestSha256: mutationSignature,
+          actor,
+        });
+        if (result.conflict) throw Object.assign(new Error(result.conflict), { conflictCode: result.code });
+        if (operation.cascaded) {
+          cascaded.push({
+            collection: operation.collection,
+            id: operation.recordId,
+            mutation_id: result.response.mutation_id,
+            sync_cursor: result.response.sync_cursor,
+          });
+        } else {
+          // TransactionOperationResult: which write, and its receipt.
+          results.push({
+            action: operation.operation,
+            collection: operation.collection,
+            id: operation.recordId,
+            ...result.response,
+          });
+        }
+        changes.push(...result.changes);
+      }
+      const response = {
+        transaction_id: transactionId,
+        replayed: false,
+        results,
+        cascaded,
+      };
+      this.db.prepare(`
+        INSERT INTO _terminus_transactions
+          (transaction_scope, transaction_id, request_sha256, response_json, committed_at)
+        VALUES (?, ?, ?, ?, ?)
+      `).run(
+        transactionScope,
+        transactionId,
+        requestSha256,
+        JSON.stringify(response),
+        new Date().toISOString(),
+      );
+      return { response, changes };
+    });
+  }
+
+  appendReset(scopeKey, collection, actor, recordCount) {
+    return transaction(this.db, () => {
+      this.db.prepare(`
+        INSERT INTO _terminus_collection_scopes (scope_key, head_cursor, retained_after_cursor)
+        VALUES (?, 0, 0) ON CONFLICT (scope_key) DO NOTHING
+      `).run(scopeKey);
+      const window = this.scopeWindow(scopeKey);
+      const cursor = window.head + 1;
+      const now = new Date().toISOString();
+      const change = {
+        operation: "reset",
+        record_id: "*",
+        mutation_id: `rebuild-${crypto.randomUUID()}`,
+        committed_version: null,
+        version: null,
+        value: null,
+        actor_user_id: actor,
+        created_by_user_id: null,
+        updated_by_user_id: null,
+        delivery_sequence: null,
+        delivery_recipients: null,
+        changed_fields: [],
+        created_at: null,
+        committed_at: now,
+        cursor,
+      };
+      this.db.prepare(`
+        INSERT INTO _terminus_changes (scope_key, cursor, change_json, committed_at)
+        VALUES (?, ?, ?, ?)
+      `).run(scopeKey, cursor, JSON.stringify(change), now);
+      const retainedAfter = Math.max(window.retainedAfter, cursor - CHANGE_RETENTION);
+      this.db.prepare(`
+        DELETE FROM _terminus_changes WHERE scope_key = ? AND cursor <= ?
+      `).run(scopeKey, retainedAfter);
+      this.db.prepare(`
+        UPDATE _terminus_collection_scopes
+        SET head_cursor = ?, retained_after_cursor = ? WHERE scope_key = ?
+      `).run(cursor, retainedAfter, scopeKey);
+      return { change, rebuilt: recordCount };
+    });
+  }
+
+  /** One page of a scope's changes after `after`: the contract's
+   * `changes_batch` rows at most (the backend's MAX_COLLECTION_CHANGE_BATCH). */
+  changes(scopeKey, after, limit = LIMITS.changes_batch) {
+    const window = this.scopeWindow(scopeKey);
+    if (after < window.retainedAfter) {
+      return { window, changes: [], resetRequired: true, hasMore: false };
+    }
+    const rows = this.db.prepare(`
+      SELECT cursor, change_json FROM _terminus_changes
+      WHERE scope_key = ? AND cursor > ? ORDER BY cursor LIMIT ?
+    `).all(scopeKey, after, limit + 1);
+    const hasMore = rows.length > limit;
+    const page = rows.slice(0, limit).map((row) => ({
+      ...parseJson(row.change_json, {}),
+      cursor: Number(row.cursor),
+    }));
+    return { window, changes: page, resetRequired: false, hasMore };
+  }
+
+  objectPath(contentSha256) {
+    return path.join(
+      this.objectsDirectory,
+      "sha256",
+      contentSha256.slice(0, 2),
+      contentSha256.slice(2, 4),
+      contentSha256,
+    );
+  }
+
+  /** Store one bucket object → its WriteReceipt (FileEntry of what was written). */
+  putObject(bucket, objectPath, bytes, mediaType = "application/octet-stream") {
+    const body = Buffer.from(bytes);
+    const hash = sha256(body);
+    const physical = this.objectPath(hash);
+    if (!existsSync(physical)) atomicWriteBytes(physical, body);
+    const prior = this.db.prepare(`
+      SELECT version FROM _terminus_object_refs WHERE bucket_name = ? AND object_path = ?
+    `).get(bucket, objectPath);
+    const version = (prior ? Number(prior.version) : 0) + 1;
+    const updatedAt = new Date().toISOString();
+    this.db.prepare(`
+      INSERT INTO _terminus_object_refs
+        (bucket_name, object_path, content_sha256, size_bytes, media_type, version, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT (bucket_name, object_path) DO UPDATE SET
+        content_sha256 = excluded.content_sha256,
+        size_bytes = excluded.size_bytes,
+        media_type = excluded.media_type,
+        version = excluded.version,
+        updated_at = excluded.updated_at
+    `).run(bucket, objectPath, hash, body.length, mediaType, version, updatedAt);
+    return {
+      path: objectPath,
+      size_bytes: body.length,
+      sha256: hash,
+      media_type: mediaType,
+      version,
+      updated_at: updatedAt,
+    };
+  }
+
+  /** One bucket object's FileEntry, without its bytes; null when absent. */
+  objectEntry(bucket, objectPath) {
+    const row = this.db.prepare(`
+      SELECT content_sha256, size_bytes, media_type, version, updated_at
+      FROM _terminus_object_refs WHERE bucket_name = ? AND object_path = ?
+    `).get(bucket, objectPath);
+    return row ? objectEntry(objectPath, row) : null;
+  }
+
+  getObject(bucket, objectPath) {
+    const entry = this.objectEntry(bucket, objectPath);
+    if (!entry) return null;
+    return { bytes: readFileSync(this.objectPath(entry.sha256)), entry };
+  }
+
+  /** `{files, next_cursor}`: a bucket's FileEntries under `prefix` in path
+   * order, `limit` after `after`. */
+  listObjects(bucket, prefix = "", { after = null, limit = 100 } = {}) {
+    const rows = this.db.prepare(`
+      SELECT object_path, content_sha256, size_bytes, media_type, version, updated_at
+      FROM _terminus_object_refs
+      WHERE bucket_name = ? AND object_path LIKE ? ESCAPE '\\' AND (? IS NULL OR object_path > ?)
+      ORDER BY object_path
+      LIMIT ?
+    `).all(bucket, likePrefix(prefix), after || null, after || null, limit + 1);
+    const page = rows.slice(0, limit).map((row) => objectEntry(String(row.object_path), row));
+    return { files: page, next_cursor: rows.length > limit ? page.at(-1).path : null };
+  }
+
+  deleteObject(bucket, objectPath) {
+    const prior = this.db.prepare(`
+      SELECT content_sha256 FROM _terminus_object_refs WHERE bucket_name = ? AND object_path = ?
+    `).get(bucket, objectPath);
+    this.db.prepare(`
+      DELETE FROM _terminus_object_refs WHERE bucket_name = ? AND object_path = ?
+    `).run(bucket, objectPath);
+    if (prior) {
+      const references = Number(this.db.prepare(`
+        SELECT COUNT(*) AS n FROM _terminus_object_refs WHERE content_sha256 = ?
+      `).get(prior.content_sha256).n);
+      if (references === 0) rmSync(this.objectPath(String(prior.content_sha256)), { force: true });
+    }
+    return { ok: true };
+  }
+
+  /** Everything this capsule keeps for one space: the space's own records
+   * and a member's records in it, their receipts and change logs, and the
+   * space's buckets. */
+  deleteSpace(spaceId) {
+    transaction(this.db, () => {
+      for (const prefix of [`space:${spaceId}:`, `member:${spaceId}:`]) {
+        for (const table of ["_terminus_records", "_terminus_mutations", "_terminus_changes", "_terminus_collection_scopes"]) {
+          this.db.prepare(`DELETE FROM ${table} WHERE scope_key LIKE ? ESCAPE '\\'`).run(likePrefix(prefix));
+        }
+      }
+      for (const scope of [`space:${spaceId}`, `member:${spaceId}`]) {
+        this.db.prepare("DELETE FROM _terminus_transactions WHERE transaction_scope = ?").run(scope);
+      }
+      const orphans = this.db.prepare(`
+        SELECT DISTINCT content_sha256 FROM _terminus_object_refs WHERE bucket_name LIKE ? ESCAPE '\\'
+      `).all(likePrefix(`spaces/${spaceId}/`)).map((row) => String(row.content_sha256));
+      this.db.prepare("DELETE FROM _terminus_object_refs WHERE bucket_name LIKE ? ESCAPE '\\'")
+        .run(likePrefix(`spaces/${spaceId}/`));
+      for (const hash of orphans) {
+        const references = Number(this.db.prepare(
+          "SELECT COUNT(*) AS n FROM _terminus_object_refs WHERE content_sha256 = ?",
+        ).get(hash).n);
+        if (references === 0) rmSync(this.objectPath(hash), { force: true });
+      }
+    });
+  }
+
+  integrityCheck() {
+    return String(this.db.prepare("PRAGMA integrity_check").get().integrity_check);
+  }
+
+  close() {
+    this.writeManifest();
+    this.db.close();
+  }
+}
+
+/** A bucket object's FileEntry. */
+function objectEntry(objectPath, row) {
+  return {
+    path: objectPath,
+    size_bytes: Number(row.size_bytes),
+    sha256: String(row.content_sha256),
+    media_type: row.media_type === null ? "application/octet-stream" : String(row.media_type),
+    version: Number(row.version ?? 1),
+    updated_at: String(row.updated_at),
+  };
+}