@catalyst-cloud/schema 0.1.0

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@catalyst-cloud/schema",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Typed Drizzle schema = single source of truth for the per-tenant Mirror DO SQLite store (CTC-13 / ADR-0002). Shared by the mirror Worker, the host-sync replica, and the browser OPFS replica.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/coalesce-labs/catalyst-cloud.git",
+    "directory": "packages/schema"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "generate": "drizzle-kit generate",
+    "build:bundle": "bun scripts/build-bundle.ts && prettier --write src/migrations.generated.ts"
+  },
+  "dependencies": {
+    "drizzle-orm": "0.44.7"
+  },
+  "devDependencies": {
+    "@catalyst-cloud/typescript-config": "workspace:*",
+    "@types/node": "^25.9.3",
+    "drizzle-kit": "^0.31.0",
+    "prettier": "^3.8.4",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  }
+}

package/src/index.ts

@@ -0,0 +1,116 @@
+// @catalyst-cloud/schema — the typed Drizzle SSOT for the Mirror DO store (CTC-13 / ADR-0002).
+//
+// Re-exports every table plus two consumption surfaces:
+//   • `mirrorSchema` — all tables, to pass as `drizzle(storage, { schema: mirrorSchema })` in the DO
+//     (and `drizzle(bunSqlite, …)` in the host-sync replica, `drizzle(sqliteProxy, …)` in the browser).
+//   • `MIRROR_TABLE_META` — per-ENTITY `{ pk, softDelete }` DERIVED from the schema via getTableConfig.
+//     This is what packages/replicate's applyDelta consumes to fold a change_log delta into a replica
+//     — replacing the hand-maintained `TABLES` map in apps/host-sync/src/apply.ts (the ADR-0002 "4th
+//     hand-copy" this schema deletes). Because it is derived, it can never drift from the table defs.
+
+import { getTableConfig, type SQLiteTable } from "drizzle-orm/sqlite-core";
+import {
+  issues,
+  labels,
+  users,
+  issue_labels,
+  relations,
+  issue_history,
+  projects,
+  cycles,
+  initiatives,
+  project_initiatives,
+  comments,
+  pull_requests,
+  check_runs,
+  commit_statuses,
+  reviews,
+  processed_events,
+  change_log,
+  sync_cursors,
+} from "./mirror";
+
+export * from "./mirror";
+
+// The committed cross-surface migration bundle + the shared runner (CTC-41). Re-exported here so
+// every consumer imports from the one package entrypoint: `applyMigrations(adapter, MIRROR_MIGRATIONS)`.
+export { MIRROR_MIGRATIONS } from "./migrations.generated";
+export {
+  applyMigrations,
+  type MigrationDb,
+  type MigrationBundle,
+  type MigrationJournalEntry,
+} from "./migrate";
+
+/** Every table in the Mirror DO store — pass as `drizzle(storage, { schema: mirrorSchema })`. */
+export const mirrorSchema = {
+  issues,
+  labels,
+  users,
+  issue_labels,
+  relations,
+  issue_history,
+  projects,
+  cycles,
+  initiatives,
+  project_initiatives,
+  comments,
+  pull_requests,
+  check_runs,
+  commit_statuses,
+  reviews,
+  processed_events,
+  change_log,
+  sync_cursors,
+} as const;
+
+/**
+ * The domain-entity tables that flow over the change-feed (the keys are the wire `entity` names). The
+ * infra tables — processed_events / change_log / sync_cursors — are deliberately excluded: they never
+ * ride a delta.
+ */
+export const mirrorEntityTables = {
+  issues,
+  labels,
+  users,
+  issue_labels,
+  relations,
+  issue_history,
+  projects,
+  cycles,
+  initiatives,
+  project_initiatives,
+  comments,
+  pull_requests,
+  check_runs,
+  commit_statuses,
+  reviews,
+} as const;
+
+/** The wire `entity` name of a change-feed-carried table (keys of mirrorEntityTables). */
+export type MirrorEntityName = keyof typeof mirrorEntityTables;
+
+/** Per-table replication metadata — the PK columns and whether deletes are soft (removed_at) vs hard. */
+export interface TableMeta {
+  /** PK column SQL names, in declared order (composite PKs yield more than one). */
+  pk: string[];
+  /** True iff the table carries a soft-delete `removed_at` column (delete sets it; else hard-delete). */
+  softDelete: boolean;
+}
+
+/** Derive a table's PK columns + soft-delete posture from the Drizzle definition (no hand-maintenance). */
+export function tableMeta(table: SQLiteTable): TableMeta {
+  const cfg = getTableConfig(table);
+  // A single-column PK (`.primaryKey()`) marks the column `.primary`; a composite PK
+  // (`primaryKey({ columns })`) instead lands in cfg.primaryKeys. Cover both.
+  const singlePk = cfg.columns.filter((c) => c.primary).map((c) => c.name);
+  const compositePk = cfg.primaryKeys.flatMap((pk) => pk.columns.map((c) => c.name));
+  const pk = singlePk.length > 0 ? singlePk : compositePk;
+  const softDelete = cfg.columns.some((c) => c.name === "removed_at");
+  return { pk, softDelete };
+}
+
+/** Schema-derived replication metadata for every change-feed entity, keyed by wire `entity` name. */
+export const MIRROR_TABLE_META: Record<MirrorEntityName, TableMeta> = Object.fromEntries(
+  Object.entries(mirrorEntityTables).map(([name, table]) => [name, tableMeta(table)]),
+) as Record<MirrorEntityName, TableMeta>;

package/src/migrate.ts

@@ -0,0 +1,147 @@
+// migrate.ts — the ONE shared, runtime-agnostic migration runner for every SQLite read surface
+// (CTC-41). Pure and synchronous: it takes a thin `MigrationDb` adapter over a native SQL handle and
+// applies the committed bundle (src/migrations.generated.ts) idempotently.
+//
+// Each surface provides a ~3-line adapter over its own handle:
+//   • DO:          { exec: s => ctx.storage.sql.exec(s), query: s => ctx.storage.sql.exec(s).toArray() }
+//   • bun daemon:  { exec: s => db.exec(s),              query: s => db.query(s).all() }
+//   • browser:     same shape over sqlocal / sqlite-wasm
+//
+// Idempotency: a `__drizzle_migrations` ledger records each applied journal tag. On every boot we read
+// the applied tags and run only the journal entries (in `idx` order) not yet recorded — so a fresh DB
+// gets the full set, a live DB (already at the baseline schema) records the baseline tag as a no-op
+// (the baseline is `CREATE TABLE IF NOT EXISTS`), and a re-run applies nothing.
+//
+// CONTRACT for migration authors (the ledger key is the journal TAG, not drizzle-kit's content hash):
+//   1. The BASELINE (0000) MUST be `CREATE TABLE/INDEX IF NOT EXISTS` so it no-ops on an already-live
+//      DB that has the tables but no ledger row (existing DOs/daemons adopt the baseline cleanly).
+//   2. Every later migration runs EXACTLY ONCE per DB (it's recorded by tag the first time it runs), so
+//      a plain `ALTER TABLE ADD COLUMN` is correct as-is. But because the run-once guard is the only
+//      safety net, a migration that could be re-attempted on a partially-migrated DB should still be
+//      written defensively. Keep each migration small and independently replay-safe.
+//   3. Do NOT pre-seed a drizzle-kit-NATIVE `__drizzle_migrations` (which stores SHA256 hashes) — this
+//      runner keys on tags, so native-hash rows would be unrecognized and the baseline would re-run
+//      (safe only while the baseline stays IF NOT EXISTS). This runner owns the ledger end to end.
+
+import { MIRROR_MIGRATIONS } from "./migrations.generated";
+
+/** The minimal native SQLite surface the runner needs — one exec + one row-returning query. */
+export interface MigrationDb {
+  /** Execute one or more SQL statements for side effect (no rows returned). */
+  exec(sql: string): void;
+  /** Run a query and return its rows as plain objects (column name → value). */
+  query(sql: string): Array<Record<string, unknown>>;
+}
+
+/** A journal entry as emitted by drizzle-kit into meta/_journal.json (and our committed bundle). */
+export interface MigrationJournalEntry {
+  idx: number;
+  version: string;
+  when: number;
+  tag: string;
+  breakpoints: boolean;
+}
+
+/** The committed migration bundle shape: the drizzle journal + tag → SQL string map. */
+export interface MigrationBundle {
+  journal: {
+    version: string;
+    dialect: string;
+    entries: readonly MigrationJournalEntry[];
+  };
+  migrations: Readonly<Record<string, string>>;
+}
+
+/** The breakpoint marker drizzle-kit inserts between statements within one migration file. */
+const STATEMENT_BREAKPOINT = "--> statement-breakpoint";
+
+const LEDGER_DDL =
+  "CREATE TABLE IF NOT EXISTS __drizzle_migrations (" +
+  "id INTEGER PRIMARY KEY AUTOINCREMENT, hash TEXT NOT NULL, created_at INTEGER)";
+
+/**
+ * Apply every not-yet-applied migration in `bundle` to `db`, in journal `idx` order. Records each
+ * applied tag in `__drizzle_migrations` (the tag is the `hash` value). Pure, synchronous, and
+ * runtime-agnostic — every SQLite surface drives it through a thin `MigrationDb` adapter.
+ *
+ * @param now Optional timestamp (epoch ms) recorded as `created_at`. Defaults to `Date.now()` AT CALL
+ *   TIME (never at import time), so the module can be imported into a Worker without a clock read.
+ * @returns the tags applied during THIS call (empty if the DB was already up to date).
+ */
+export function applyMigrations(
+  db: MigrationDb,
+  bundle: MigrationBundle = MIRROR_MIGRATIONS,
+  now: number = Date.now(),
+): { appliedTags: string[] } {
+  // 1) Ensure the ledger exists.
+  db.exec(LEDGER_DDL);
+
+  // 2) Read already-applied tags (stored in the `hash` column).
+  const appliedRows = db.query("SELECT hash FROM __drizzle_migrations");
+  const applied = new Set<string>(
+    appliedRows.map((r) => String(r.hash)).filter((h) => h.length > 0),
+  );
+
+  // 3) Apply each journal entry not yet recorded, in idx order.
+  const entries = [...bundle.journal.entries].sort((a, b) => a.idx - b.idx);
+  const appliedTags: string[] = [];
+
+  for (const entry of entries) {
+    if (applied.has(entry.tag)) continue;
+
+    const sql = bundle.migrations[entry.tag];
+    if (sql === undefined) {
+      throw new Error(`applyMigrations: journal tag "${entry.tag}" has no SQL in the bundle`);
+    }
+
+    // Split on the breakpoint marker and exec each non-empty statement individually. (The DO's
+    // ctx.storage.sql.exec and bun:sqlite both accept multi-statement strings, but splitting keeps
+    // the runner portable to surfaces that don't, and matches drizzle-kit's own migrator.)
+    for (const raw of sql.split(STATEMENT_BREAKPOINT)) {
+      const stmt = raw.trim();
+      if (stmt.length === 0) continue;
+      execReplaySafe(db, stmt);
+    }
+
+    // Record the tag (as the hash). A parameterless INSERT keeps the adapter surface to exec-only.
+    db.exec(
+      `INSERT INTO __drizzle_migrations (hash, created_at) VALUES ('${escapeSqlLiteral(entry.tag)}', ${now})`,
+    );
+    appliedTags.push(entry.tag);
+  }
+
+  return { appliedTags };
+}
+
+/**
+ * Execute one migration statement, tolerating the three errors that make an additive migration
+ * non-replay-safe when the run-once ledger guard is bypassed — e.g. a crash between a statement
+ * succeeding and the tag being recorded, which reruns the whole migration on the next boot:
+ *   • "duplicate column name" on `ALTER TABLE ... ADD COLUMN` — the column is already present.
+ *   • "index ... already exists" on `CREATE INDEX` — the index is already present (drizzle-kit emits
+ *     bare `CREATE INDEX`, not `IF NOT EXISTS`, so the runner makes the replay idempotent here).
+ *   • "table ... already exists" on `CREATE TABLE` — a NEW entity table added in a LATER migration
+ *     (CTC-USERS): drizzle-kit emits a bare `CREATE TABLE` (no IF NOT EXISTS), so a live DB whose
+ *     tables were already created from a newer `schema.sql` (which carries the new table) would throw
+ *     on adoption. Swallowing the duplicate-table makes the fresh CREATE TABLE adopt as a no-op,
+ *     exactly mirroring the duplicate-column / duplicate-index cases below.
+ * All three are exactly the defensive replay-safety the CONTRACT (point #2) calls for. A live DB whose
+ * tables were created from a newer `schema.sql` likewise adopts these additive tags as no-ops rather
+ * than throwing. Only these idempotent cases are swallowed; any other SQL error still propagates.
+ */
+function execReplaySafe(db: MigrationDb, stmt: string): void {
+  try {
+    db.exec(stmt);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/duplicate column name/i.test(msg) && /\bADD\b/i.test(stmt)) return;
+    if (/already exists/i.test(msg) && /\bCREATE\s+INDEX\b/i.test(stmt)) return;
+    if (/already exists/i.test(msg) && /\bCREATE\s+TABLE\b/i.test(stmt)) return;
+    throw err;
+  }
+}
+
+/** Escape a string for use inside a single-quoted SQL literal (double any embedded single quote). */
+function escapeSqlLiteral(value: string): string {
+  return value.replace(/'/g, "''");
+}

package/src/migrations.generated.ts

@@ -0,0 +1,90 @@
+// AUTO-GENERATED by scripts/build-bundle.ts — DO NOT EDIT BY HAND.
+//
+// The committed Mirror migration bundle (CTC-41): the drizzle-kit journal + every migration SQL as a
+// string literal (NO `.sql`-as-import), so the SAME module imports cleanly in the DO (Workers), the
+// bun daemon, node tests, and the browser. Regenerate via `bun run --cwd packages/schema build:bundle`
+// (or the root `migration:generate`). The CI drift gate (`migration:check`) fails if this file is
+// stale vs drizzle/.
+
+export const MIRROR_MIGRATIONS = {
+  journal: {
+    version: "7",
+    dialect: "sqlite",
+    entries: [
+      {
+        idx: 0,
+        version: "6",
+        when: 1782051267561,
+        tag: "0000_baseline",
+        breakpoints: true,
+      },
+      {
+        idx: 1,
+        version: "6",
+        when: 1782110588498,
+        tag: "0001_short_glorian",
+        breakpoints: true,
+      },
+      {
+        idx: 2,
+        version: "6",
+        when: 1782179798312,
+        tag: "0002_many_captain_marvel",
+        breakpoints: true,
+      },
+      {
+        idx: 3,
+        version: "6",
+        when: 1782182056315,
+        tag: "0003_brainy_silver_samurai",
+        breakpoints: true,
+      },
+      {
+        idx: 4,
+        version: "6",
+        when: 1782183082087,
+        tag: "0004_fat_mindworm",
+        breakpoints: true,
+      },
+      {
+        idx: 5,
+        version: "6",
+        when: 1782184123941,
+        tag: "0005_blue_black_queen",
+        breakpoints: true,
+      },
+      {
+        idx: 6,
+        version: "6",
+        when: 1782186590417,
+        tag: "0006_lively_vector",
+        breakpoints: true,
+      },
+      {
+        idx: 7,
+        version: "6",
+        when: 1782229820186,
+        tag: "0007_rapid_logan",
+        breakpoints: true,
+      },
+    ],
+  },
+  migrations: {
+    "0000_baseline":
+      "CREATE TABLE IF NOT EXISTS `change_log` (\n\t`seq` integer PRIMARY KEY AUTOINCREMENT NOT NULL,\n\t`entity` text,\n\t`entity_id` text,\n\t`op` text,\n\t`payload` text,\n\t`ts` integer\n);\n--> statement-breakpoint\nCREATE TABLE IF NOT EXISTS `check_runs` (\n\t`repo_id` text NOT NULL,\n\t`check_run_id` text PRIMARY KEY NOT NULL,\n\t`head_sha` text,\n\t`name` text,\n\t`status` text,\n\t`conclusion` text,\n\t`check_suite_id` text,\n\t`updated_at` integer\n);\n--> statement-breakpoint\nCREATE INDEX IF NOT EXISTS `idx_check_runs_sha` ON `check_runs` (`head_sha`);--> statement-breakpoint\nCREATE TABLE IF NOT EXISTS `comments` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`issue_id` text,\n\t`body` text,\n\t`updated_at` integer,\n\t`removed_at` integer\n);\n--> statement-breakpoint\nCREATE TABLE IF NOT EXISTS `commit_statuses` (\n\t`repo_id` text NOT NULL,\n\t`sha` text NOT NULL,\n\t`context` text NOT NULL,\n\t`state` text,\n\t`target_url` text,\n\t`updated_at` integer,\n\tPRIMARY KEY(`repo_id`, `sha`, `context`)\n);\n--> statement-breakpoint\nCREATE TABLE IF NOT EXISTS `cycles` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`number` integer,\n\t`starts_at` integer,\n\t`ends_at` integer,\n\t`updated_at` integer\n);\n--> statement-breakpoint\nCREATE TABLE IF NOT EXISTS `issue_labels` (\n\t`issue_id` text NOT NULL,\n\t`label_id` text NOT NULL,\n\tPRIMARY KEY(`issue_id`, `label_id`)\n);\n--> statement-breakpoint\nCREATE TABLE IF NOT EXISTS `issues` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`identifier` text,\n\t`title` text,\n\t`state` text,\n\t`assignee` text,\n\t`priority` integer,\n\t`estimate` real,\n\t`project_id` text,\n\t`cycle_id` text,\n\t`team_id` text,\n\t`updated_at` integer,\n\t`archived_at` integer,\n\t`removed_at` integer,\n\t`raw` text\n);\n--> statement-breakpoint\nCREATE INDEX IF NOT EXISTS `idx_issues_team` ON `issues` (`team_id`);--> statement-breakpoint\nCREATE TABLE IF NOT EXISTS `labels` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`name` text,\n\t`updated_at` integer,\n\t`removed_at` integer\n);\n--> statement-breakpoint\nCREATE TABLE IF NOT EXISTS `processed_events` (\n\t`delivery_id` text PRIMARY KEY NOT NULL,\n\t`source` text,\n\t`event_type` text,\n\t`received_at` integer\n);\n--> statement-breakpoint\nCREATE TABLE IF NOT EXISTS `projects` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`name` text,\n\t`state` text,\n\t`updated_at` integer,\n\t`removed_at` integer\n);\n--> statement-breakpoint\nCREATE TABLE IF NOT EXISTS `pull_requests` (\n\t`repo_id` text NOT NULL,\n\t`number` integer NOT NULL,\n\t`node_id` text,\n\t`state` text,\n\t`draft` integer,\n\t`merged` integer,\n\t`merged_at` integer,\n\t`head_sha` text,\n\t`base_ref` text,\n\t`mergeable` integer,\n\t`mergeable_state` text,\n\t`auto_merge` integer,\n\t`updated_at` integer,\n\t`synced_at` integer,\n\tPRIMARY KEY(`repo_id`, `number`)\n);\n--> statement-breakpoint\nCREATE TABLE IF NOT EXISTS `relations` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`type` text,\n\t`issue_identifier` text,\n\t`related_identifier` text,\n\t`updated_at` integer\n);\n--> statement-breakpoint\nCREATE INDEX IF NOT EXISTS `idx_relations_issue` ON `relations` (`issue_identifier`);--> statement-breakpoint\nCREATE TABLE IF NOT EXISTS `reviews` (\n\t`repo_id` text NOT NULL,\n\t`pr_number` integer NOT NULL,\n\t`review_id` text PRIMARY KEY NOT NULL,\n\t`user_id` text,\n\t`state` text,\n\t`submitted_at` integer\n);\n--> statement-breakpoint\nCREATE TABLE IF NOT EXISTS `sync_cursors` (\n\t`source` text NOT NULL,\n\t`entity` text NOT NULL,\n\t`cursor` text,\n\t`last_run_at` integer,\n\tPRIMARY KEY(`source`, `entity`)\n);\n",
+    "0001_short_glorian":
+      "ALTER TABLE `comments` ADD `author_id` text;--> statement-breakpoint\nALTER TABLE `comments` ADD `author_name` text;--> statement-breakpoint\nALTER TABLE `comments` ADD `author_avatar_url` text;--> statement-breakpoint\nALTER TABLE `comments` ADD `is_bot` integer;--> statement-breakpoint\nALTER TABLE `comments` ADD `parent_id` text;--> statement-breakpoint\nALTER TABLE `issues` ADD `description` text;--> statement-breakpoint\nALTER TABLE `issues` ADD `delegate_id` text;--> statement-breakpoint\nALTER TABLE `issues` ADD `delegate_name` text;--> statement-breakpoint\nALTER TABLE `issues` ADD `bot_actor_name` text;--> statement-breakpoint\nALTER TABLE `issues` ADD `bot_actor_type` text;--> statement-breakpoint\nALTER TABLE `issues` ADD `bot_actor_sub_type` text;--> statement-breakpoint\nALTER TABLE `issues` ADD `parent_id` text;--> statement-breakpoint\nALTER TABLE `issues` ADD `parent_identifier` text;--> statement-breakpoint\nALTER TABLE `labels` ADD `color` text;",
+    "0002_many_captain_marvel":
+      "CREATE INDEX `idx_comments_issue` ON `comments` (`issue_id`,`removed_at`,`updated_at`);--> statement-breakpoint\nCREATE INDEX `idx_issues_updated` ON `issues` (`removed_at`,`updated_at`);--> statement-breakpoint\nCREATE INDEX `idx_issues_identifier` ON `issues` (`identifier`);--> statement-breakpoint\nCREATE INDEX `idx_pulls_updated` ON `pull_requests` (`updated_at`);",
+    "0003_brainy_silver_samurai":
+      "ALTER TABLE `pull_requests` ADD `title` text;--> statement-breakpoint\nALTER TABLE `pull_requests` ADD `body` text;--> statement-breakpoint\nALTER TABLE `pull_requests` ADD `author_login` text;--> statement-breakpoint\nALTER TABLE `pull_requests` ADD `author_avatar_url` text;--> statement-breakpoint\nALTER TABLE `pull_requests` ADD `created_at` integer;--> statement-breakpoint\nALTER TABLE `pull_requests` ADD `closed_at` integer;--> statement-breakpoint\nALTER TABLE `pull_requests` ADD `comment_count` integer;--> statement-breakpoint\nALTER TABLE `pull_requests` ADD `milestone_title` text;",
+    "0004_fat_mindworm":
+      "ALTER TABLE `comments` ADD `created_at` integer;--> statement-breakpoint\nALTER TABLE `issues` ADD `started_at` integer;--> statement-breakpoint\nALTER TABLE `issues` ADD `completed_at` integer;--> statement-breakpoint\nALTER TABLE `issues` ADD `canceled_at` integer;--> statement-breakpoint\nALTER TABLE `issues` ADD `created_at` integer;--> statement-breakpoint\nALTER TABLE `issues` ADD `due_date` text;--> statement-breakpoint\nALTER TABLE `issues` ADD `snoozed_until_at` integer;--> statement-breakpoint\nALTER TABLE `issues` ADD `url` text;--> statement-breakpoint\nALTER TABLE `issues` ADD `priority_label` text;--> statement-breakpoint\nALTER TABLE `issues` ADD `sort_order` real;--> statement-breakpoint\nALTER TABLE `issues` ADD `branch_name` text;--> statement-breakpoint\nCREATE INDEX `idx_issues_sort_order` ON `issues` (`sort_order`);",
+    "0005_blue_black_queen":
+      "CREATE TABLE `users` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`name` text,\n\t`display_name` text,\n\t`avatar_url` text,\n\t`type` text,\n\t`source` text,\n\t`updated_at` integer\n);\n--> statement-breakpoint\nALTER TABLE `issues` ADD `assignee_id` text;",
+    "0006_lively_vector":
+      "CREATE TABLE `initiatives` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`name` text,\n\t`description` text,\n\t`status` text,\n\t`target_date` text,\n\t`owner_id` text,\n\t`updated_at` integer\n);\n--> statement-breakpoint\nCREATE TABLE `project_initiatives` (\n\t`project_id` text NOT NULL,\n\t`initiative_id` text NOT NULL,\n\tPRIMARY KEY(`project_id`, `initiative_id`)\n);\n--> statement-breakpoint\nALTER TABLE `cycles` ADD `name` text;--> statement-breakpoint\nALTER TABLE `cycles` ADD `progress` real;--> statement-breakpoint\nALTER TABLE `cycles` ADD `completed_scope` real;--> statement-breakpoint\nALTER TABLE `cycles` ADD `scope` real;--> statement-breakpoint\nALTER TABLE `cycles` ADD `completed_issue_count` integer;--> statement-breakpoint\nALTER TABLE `cycles` ADD `issue_count` integer;--> statement-breakpoint\nALTER TABLE `projects` ADD `description` text;--> statement-breakpoint\nALTER TABLE `projects` ADD `lead_id` text;--> statement-breakpoint\nALTER TABLE `projects` ADD `target_date` text;--> statement-breakpoint\nALTER TABLE `projects` ADD `start_date` text;--> statement-breakpoint\nALTER TABLE `projects` ADD `progress` real;--> statement-breakpoint\nALTER TABLE `projects` ADD `health` text;--> statement-breakpoint\nALTER TABLE `projects` ADD `icon` text;--> statement-breakpoint\nALTER TABLE `projects` ADD `color` text;",
+    "0007_rapid_logan":
+      "CREATE TABLE `issue_history` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`issue_id` text NOT NULL,\n\t`actor_id` text,\n\t`created_at` integer,\n\t`updated_at` integer,\n\t`from_state` text,\n\t`to_state` text,\n\t`from_assignee_id` text,\n\t`to_assignee_id` text,\n\t`from_priority` integer,\n\t`to_priority` integer,\n\t`from_estimate` real,\n\t`to_estimate` real,\n\t`from_title` text,\n\t`to_title` text,\n\t`from_cycle_id` text,\n\t`to_cycle_id` text,\n\t`from_project_id` text,\n\t`to_project_id` text,\n\t`from_parent_id` text,\n\t`to_parent_id` text,\n\t`from_team_id` text,\n\t`to_team_id` text,\n\t`from_due_date` text,\n\t`to_due_date` text,\n\t`added_label_ids` text,\n\t`removed_label_ids` text,\n\t`updated_description` integer,\n\t`archived` integer,\n\t`auto_archived` integer,\n\t`auto_closed` integer,\n\t`trashed` integer,\n\t`raw` text\n);\n--> statement-breakpoint\nCREATE INDEX `idx_issue_history_issue_created` ON `issue_history` (`issue_id`,`created_at`);",
+  },
+} as const;

package/src/mirror.ts

@@ -0,0 +1,368 @@
+// The per-tenant Mirror Durable Object SQLite store, as typed Drizzle tables — the SINGLE SOURCE OF
+// TRUTH for the mirror schema (CTC-13 / ADR-0002). One DO per tenant, so the DO instance IS the
+// partition: there is NO tenant_id column. This mirrors apps/mirror/src/do/schema.sql column-for-
+// column; the fidelity test (test/schema.test.ts) pins them together so a drift is a test failure.
+//
+// COLUMN NAMING: the TS keys are snake_case and identical to the SQL column names. That is deliberate
+// — the change-feed wire rows, the /snapshot rows, and the read-model select() output are all
+// snake_case (apps/mirror/src/do/{changefeed,views}.ts), so a Drizzle select() over these tables
+// yields the SAME row shape the wire contract already uses, with no DTO/remap layer (the ADR-0002
+// "no mapping" payoff).
+//
+// LOAD-BEARING FOOTGUNS encoded here as types (so a wrong reference fails `tsc`, not a prod 500):
+//   • Soft-delete is PER-TABLE: only issues / labels / projects / comments carry `removed_at`. The
+//     other tables have none — filtering them on it throws "no such column" on the real DO.
+//   • `relations` join on issues.identifier (issue_identifier), NOT issues.id.
+//   • `check_runs` join a PR by head_sha, NOT PR number.
+//   • PR mergeable / mergeable_state are nullable until a reconcile resolves them.
+
+import { sqliteTable, text, integer, real, primaryKey, index } from "drizzle-orm/sqlite-core";
+
+// ── Linear ───────────────────────────────────────────────────────────────────────────────────────
+
+export const issues = sqliteTable(
+  "issues",
+  {
+    id: text("id").primaryKey(),
+    identifier: text("identifier"),
+    title: text("title"),
+    description: text("description"),
+    state: text("state"),
+    assignee: text("assignee"),
+    // CTC-USERS: the assignee's user id (FK → users.id), so the row JOINs to a name + avatar. The
+    // legacy `assignee` name string is KEPT for back-compat (the SSE list row still carries it).
+    assignee_id: text("assignee_id"),
+    priority: integer("priority"),
+    estimate: real("estimate"),
+    project_id: text("project_id"),
+    cycle_id: text("cycle_id"),
+    team_id: text("team_id"),
+    delegate_id: text("delegate_id"),
+    delegate_name: text("delegate_name"),
+    bot_actor_name: text("bot_actor_name"),
+    bot_actor_type: text("bot_actor_type"),
+    bot_actor_sub_type: text("bot_actor_sub_type"),
+    parent_id: text("parent_id"),
+    parent_identifier: text("parent_identifier"),
+    // Ticket field enrichment (CTC-TICKET-FIELDS): lifecycle timestamps + due date + snooze + url +
+    // human priority label + manual drag-rank + suggested branch. The DateTime fields are ms epochs
+    // (isoToMs, same as updated_at/archived_at). due_date is the ONE TEXT date — Linear `dueDate` is a
+    // TimelessDate ("YYYY-MM-DD", no time), stored AS-IS (NEVER through isoToMs — that's the trap).
+    started_at: integer("started_at"),
+    completed_at: integer("completed_at"),
+    canceled_at: integer("canceled_at"),
+    created_at: integer("created_at"),
+    due_date: text("due_date"),
+    snoozed_until_at: integer("snoozed_until_at"),
+    url: text("url"),
+    priority_label: text("priority_label"),
+    sort_order: real("sort_order"),
+    branch_name: text("branch_name"),
+    updated_at: integer("updated_at"),
+    archived_at: integer("archived_at"),
+    removed_at: integer("removed_at"),
+    raw: text("raw"),
+  },
+  (t) => [
+    index("idx_issues_team").on(t.team_id),
+    // CTC-59: the list query — `WHERE removed_at IS NULL ORDER BY updated_at DESC` (buildIssuesView).
+    // The composite lets SQLite seek the live rows then walk updated_at in order (no temp b-tree).
+    index("idx_issues_updated").on(t.removed_at, t.updated_at),
+    // CTC-59: the detail lookup — `WHERE identifier = ?` (buildIssueDetail).
+    index("idx_issues_identifier").on(t.identifier),
+    // CTC-TICKET-FIELDS: the manual-rank sort path (a future ORDER BY sort_order). Index lives in the
+    // Drizzle SSOT ONLY (NOT schema.sql) — migrate.ts swallows a duplicate CREATE INDEX on replay
+    // (CTC-59), so the generated `CREATE INDEX` is replay-safe; schema.sql would break the adoption test.
+    index("idx_issues_sort_order").on(t.sort_order),
+  ],
+);
+
+export const labels = sqliteTable("labels", {
+  id: text("id").primaryKey(),
+  name: text("name"),
+  color: text("color"),
+  updated_at: integer("updated_at"),
+  removed_at: integer("removed_at"),
+});
+
+// Teammate identities (CTC-USERS): resolves issue assignees + delegate AGENTS (and comment/PR
+// authors/reviewers) to a name + avatar so the UI never renders a gray "Unknown" chip. AGENT
+// identities are first-class: `type` is human | agent | bot | app. Populated three ways — a ROSTER
+// bootstrap leg (Linear org users + GitHub repo collaborators), upsert-from-ingest (assignee /
+// delegate / botActor / comment author / PR author), and (Linear has no User webhook) the reconcile.
+//
+// HARD-UPSERT, no soft delete: there is intentionally NO removed_at — a stale identity is overwritten
+// in place, never tombstoned (an avatar/name that goes missing just stops being referenced). `id` is
+// the source-native id: Linear's user node id, the bot actor id, or a `github:<login>` synthetic id.
+export const users = sqliteTable("users", {
+  id: text("id").primaryKey(),
+  name: text("name"),
+  display_name: text("display_name"),
+  avatar_url: text("avatar_url"),
+  type: text("type"), // human | agent | bot | app
+  source: text("source"), // linear | github
+  updated_at: integer("updated_at"),
+});
+
+export const issue_labels = sqliteTable(
+  "issue_labels",
+  {
+    issue_id: text("issue_id").notNull(),
+    label_id: text("label_id").notNull(),
+  },
+  (t) => [primaryKey({ columns: [t.issue_id, t.label_id] })],
+);
+
+// FULL-poll-and-diff every reconcile pass (Linear fires NO issueRelations webhooks). Delete-absent is
+// load-bearing — and there is intentionally NO removed_at: a stale edge is HARD-deleted, never soft.
+export const relations = sqliteTable(
+  "relations",
+  {
+    id: text("id").primaryKey(),
+    type: text("type"), // blocks | duplicate | related
+    issue_identifier: text("issue_identifier"),
+    related_identifier: text("related_identifier"),
+    updated_at: integer("updated_at"),
+  },
+  (t) => [index("idx_relations_issue").on(t.issue_identifier)],
+);
+
+// Linear IssueHistory events (CTC-14) — the per-issue change timeline. Captured INLINE on the issues
+// delta sweep (a nested history(last:100) connection), NOT a separate leg and NOT a webhook path. Each
+// node is IMMUTABLE with a stable `id`; HARD upsert keyed on `id` (NO removed_at — a history row never
+// changes and never vanishes). created_at is the timeline sort key; updated_at = created_at and drives
+// the last-write-wins guard. from_state/to_state are workflow state NAMES (issues store state as a
+// name — no states table). from_due_date/to_due_date are TimelessDate "YYYY-MM-DD" stored AS-IS as
+// TEXT (the trap), never a timestamp. added_label_ids/removed_label_ids are JSON array strings; the
+// boolean columns are the mirror's 0/1 ints. raw is the full node JSON (full fidelity / forward-compat).
+export const issue_history = sqliteTable(
+  "issue_history",
+  {
+    id: text("id").primaryKey(),
+    issue_id: text("issue_id").notNull(), // FK → issues.id
+    actor_id: text("actor_id"), // FK → users.id; nullable (system events have no actor)
+    created_at: integer("created_at"), // event time (ms epoch) — the timeline sort key
+    updated_at: integer("updated_at"), // = created_at (immutable) — drives the upsert guard
+    from_state: text("from_state"),
+    to_state: text("to_state"), // workflow state NAMES (no states table)
+    from_assignee_id: text("from_assignee_id"),
+    to_assignee_id: text("to_assignee_id"),
+    from_priority: integer("from_priority"),
+    to_priority: integer("to_priority"),
+    from_estimate: real("from_estimate"), // match issues.estimate (real)
+    to_estimate: real("to_estimate"),
+    from_title: text("from_title"),
+    to_title: text("to_title"),
+    from_cycle_id: text("from_cycle_id"),
+    to_cycle_id: text("to_cycle_id"),
+    from_project_id: text("from_project_id"),
+    to_project_id: text("to_project_id"),
+    from_parent_id: text("from_parent_id"),
+    to_parent_id: text("to_parent_id"),
+    from_team_id: text("from_team_id"),
+    to_team_id: text("to_team_id"),
+    from_due_date: text("from_due_date"), // TimelessDate AS-IS (the trap) — NEVER through isoToMs
+    to_due_date: text("to_due_date"), // TimelessDate AS-IS (the trap) — NEVER through isoToMs
+    added_label_ids: text("added_label_ids"), // JSON array string
+    removed_label_ids: text("removed_label_ids"), // JSON array string
+    updated_description: integer("updated_description"), // 0/1 boolean
+    archived: integer("archived"), // 0/1
+    auto_archived: integer("auto_archived"), // 0/1
+    auto_closed: integer("auto_closed"), // 0/1
+    trashed: integer("trashed"), // 0/1
+    raw: text("raw"), // JSON.stringify(node) — full fidelity / forward-compat (like issues.raw)
+  },
+  // The timeline index lives in the Drizzle SSOT ONLY (NOT schema.sql) — migrate.ts makes the generated
+  // CREATE INDEX replay-safe (same as the issues read-path indexes); putting it in schema.sql would
+  // break the adoption test.
+  (t) => [index("idx_issue_history_issue_created").on(t.issue_id, t.created_at)],
+);
+
+// CTC-HIERARCHY enriches the project row with the lead (FK → users.id), description, lifecycle dates,
+// progress, health, and presentation (icon/color). `target_date` / `start_date` are Linear
+// TimelessDates ("YYYY-MM-DD") — stored AS-IS as TEXT, NEVER through isoToMs (the same trap as
+// issues.due_date). `progress` is a Float (0..1).
+export const projects = sqliteTable("projects", {
+  id: text("id").primaryKey(),
+  name: text("name"),
+  state: text("state"),
+  description: text("description"),
+  lead_id: text("lead_id"), // FK → users.id (CTC-HIERARCHY); upserted from the project lead.
+  target_date: text("target_date"), // TimelessDate "YYYY-MM-DD" — TEXT AS-IS (the trap), not a ts.
+  start_date: text("start_date"), // TimelessDate "YYYY-MM-DD" — TEXT AS-IS (the trap), not a ts.
+  progress: real("progress"),
+  health: text("health"), // onTrack | atRisk | offTrack (null until a project update reports it).
+  icon: text("icon"),
+  color: text("color"),
+  updated_at: integer("updated_at"),
+  removed_at: integer("removed_at"),
+});
+
+// CTC-HIERARCHY enriches the cycle row with its display name + progress + current scope/issue counts.
+// Linear exposes scope/issue counts only as weekly history arrays (completedScopeHistory etc.); we
+// store the CURRENT value (the last array element) as a scalar — not the whole history.
+export const cycles = sqliteTable("cycles", {
+  id: text("id").primaryKey(),
+  number: integer("number"),
+  name: text("name"),
+  progress: real("progress"),
+  completed_scope: real("completed_scope"), // last(completedScopeHistory) — current completed points.
+  scope: real("scope"), // last(scopeHistory) — current total scope points.
+  completed_issue_count: integer("completed_issue_count"), // last(completedIssueCountHistory).
+  issue_count: integer("issue_count"), // last(issueCountHistory).
+  starts_at: integer("starts_at"),
+  ends_at: integer("ends_at"),
+  updated_at: integer("updated_at"),
+});
+
+// Linear initiatives (CTC-HIERARCHY) — the top of the HIERARCHY (initiative → project → cycle →
+// issue). PK `id` (Linear node id). `status` is the InitiativeStatus enum string; `target_date` is a
+// TimelessDate ("YYYY-MM-DD") stored AS-IS as TEXT (the trap). `owner_id` is the FK → users.id.
+// HARD upsert — NO removed_at (a vanished initiative just stops being referenced by the join table).
+export const initiatives = sqliteTable("initiatives", {
+  id: text("id").primaryKey(),
+  name: text("name"),
+  description: text("description"),
+  status: text("status"),
+  target_date: text("target_date"), // TimelessDate "YYYY-MM-DD" — TEXT AS-IS (the trap), not a ts.
+  owner_id: text("owner_id"), // FK → users.id (CTC-HIERARCHY); upserted from the initiative owner.
+  updated_at: integer("updated_at"),
+});
+
+// project↔initiative join (CTC-HIERARCHY) — Linear models this as many:many (a project belongs to
+// many initiatives), so it's an edge table modeled on issue_labels: composite PK, no updated_at, full
+// poll-and-diff per project leg in the reconcile (Linear fires no membership webhook for it).
+export const project_initiatives = sqliteTable(
+  "project_initiatives",
+  {
+    project_id: text("project_id").notNull(),
+    initiative_id: text("initiative_id").notNull(),
+  },
+  (t) => [primaryKey({ columns: [t.project_id, t.initiative_id] })],
+);
+
+export const comments = sqliteTable(
+  "comments",
+  {
+    id: text("id").primaryKey(),
+    issue_id: text("issue_id"),
+    body: text("body"),
+    author_id: text("author_id"),
+    author_name: text("author_name"),
+    author_avatar_url: text("author_avatar_url"),
+    is_bot: integer("is_bot"),
+    parent_id: text("parent_id"),
+    // CTC-TICKET-FIELDS: when Linear created the comment (DateTime → ms, isoToMs).
+    created_at: integer("created_at"),
+    updated_at: integer("updated_at"),
+    removed_at: integer("removed_at"),
+  },
+  // CTC-59: the detail comments fetch — `WHERE issue_id = ? AND removed_at IS NULL ORDER BY updated_at`.
+  // Composite covers the filter AND the sort, so SQLite seeks instead of building a temp b-tree.
+  (t) => [index("idx_comments_issue").on(t.issue_id, t.removed_at, t.updated_at)],
+);
+
+// ── GitHub ───────────────────────────────────────────────────────────────────────────────────────
+
+export const pull_requests = sqliteTable(
+  "pull_requests",
+  {
+    repo_id: text("repo_id").notNull(),
+    number: integer("number").notNull(),
+    node_id: text("node_id"),
+    // PR data tier 1 (CTC-PR-TIER1): high-value fields already riding the fetched PR list/object —
+    // ZERO extra GitHub API calls. `title` is the #1 complaint; body/author/dates/comments/milestone
+    // round out the card. All nullable (a pre-backfill row may lack them).
+    title: text("title"),
+    body: text("body"),
+    author_login: text("author_login"),
+    author_avatar_url: text("author_avatar_url"),
+    state: text("state"),
+    draft: integer("draft"),
+    merged: integer("merged"),
+    merged_at: integer("merged_at"),
+    head_sha: text("head_sha"),
+    base_ref: text("base_ref"),
+    mergeable: integer("mergeable"),
+    mergeable_state: text("mergeable_state"),
+    auto_merge: integer("auto_merge"),
+    // ms-epoch convention (same isoToMs-style parse as merged_at/updated_at). closed_at nullable.
+    created_at: integer("created_at"),
+    closed_at: integer("closed_at"),
+    comment_count: integer("comment_count"),
+    milestone_title: text("milestone_title"),
+    updated_at: integer("updated_at"),
+    synced_at: integer("synced_at"),
+  },
+  (t) => [
+    primaryKey({ columns: [t.repo_id, t.number] }),
+    // CTC-59: the pulls list — `ORDER BY updated_at DESC` (buildPullsView).
+    index("idx_pulls_updated").on(t.updated_at),
+  ],
+);
+
+export const check_runs = sqliteTable(
+  "check_runs",
+  {
+    repo_id: text("repo_id").notNull(),
+    check_run_id: text("check_run_id").primaryKey(),
+    head_sha: text("head_sha"),
+    name: text("name"),
+    status: text("status"),
+    conclusion: text("conclusion"),
+    check_suite_id: text("check_suite_id"),
+    updated_at: integer("updated_at"),
+  },
+  (t) => [index("idx_check_runs_sha").on(t.head_sha)],
+);
+
+export const commit_statuses = sqliteTable(
+  "commit_statuses",
+  {
+    repo_id: text("repo_id").notNull(),
+    sha: text("sha").notNull(),
+    context: text("context").notNull(),
+    state: text("state"),
+    target_url: text("target_url"),
+    updated_at: integer("updated_at"),
+  },
+  (t) => [primaryKey({ columns: [t.repo_id, t.sha, t.context] })],
+);
+
+export const reviews = sqliteTable("reviews", {
+  repo_id: text("repo_id").notNull(),
+  pr_number: integer("pr_number").notNull(),
+  review_id: text("review_id").primaryKey(),
+  user_id: text("user_id"),
+  state: text("state"),
+  submitted_at: integer("submitted_at"),
+});
+
+// ── Mirror infra (not domain entities — never ride the change-feed) ─────────────────────────────────
+
+export const processed_events = sqliteTable("processed_events", {
+  delivery_id: text("delivery_id").primaryKey(),
+  source: text("source"),
+  event_type: text("event_type"),
+  received_at: integer("received_at"),
+});
+
+export const change_log = sqliteTable("change_log", {
+  seq: integer("seq").primaryKey({ autoIncrement: true }),
+  entity: text("entity"),
+  entity_id: text("entity_id"),
+  op: text("op"), // upsert | delete
+  payload: text("payload"),
+  ts: integer("ts"),
+});
+
+export const sync_cursors = sqliteTable(
+  "sync_cursors",
+  {
+    source: text("source").notNull(),
+    entity: text("entity").notNull(),
+    cursor: text("cursor"),
+    last_run_at: integer("last_run_at"),
+  },
+  (t) => [primaryKey({ columns: [t.source, t.entity] })],
+);