@catalyst-cloud/schema 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/schema",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "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",

package/src/index.ts

@@ -44,6 +44,12 @@ import {
   pr_events,
   pr_ancillary_backfill,
   push_subscriptions,
+  pushes,
+  push_events,
+  deployments,
+  deployment_statuses,
+  pr_review_threads,
+  check_suites,
 } from "./mirror.js";
 
 export * from "./mirror.js";
@@ -117,13 +123,33 @@ export const mirrorSchema = {
   pr_commits,
   pr_events,
   pr_ancillary_backfill,
-  // CTC-619: a member's Web Push subscription. Rides the change feed like any other entity — a
-  // member-facing settings UI can reflect subscribe/unsubscribe reactively.
+  // CTC-619: a member's Web Push subscription. ⚠️ Whether it rides the change feed is DISPUTED —
+  // see mirrorEntityTables below and CTC-671.
   push_subscriptions,
+  // CTC-667: the current head of a pushed git ref — the orchestrator's rebase-detection signal.
+  pushes,
+  // CTC-704: one row per push DELIVERY, append-only next to the per-ref row above — what lets the
+  // feed emit an edge per push instead of collapsing two pushes to one ref into one.
+  push_events,
+  // CTC-667: a GitHub deployment, its status transitions, and a PR review thread's resolution state
+  // — the remaining payload types host dispatch consumes (CTL-1929's last smee tunnel).
+  deployments,
+  deployment_statuses,
+  pr_review_threads,
+  // CTC-667 item 4: the check SUITE's own rollup — the highest-volume signal in CTL's census and the
+  // one every phase agent's CI wait blocks on.
+  check_suites,
 } as const;
 
 /**
- * The domain-entity tables that flow over the change-feed (the keys are the wire `entity` names). The
+ * ⭐ CTC-671 — THE SINGLE DEFINITION OF CHANGE-FEED MEMBERSHIP. The keys are the wire `entity`
+ * names, and everything that answers "is this row safe for every reader of the account's feed"
+ * derives from this object: `FEED_ENTITY_NAMES` below, `@catalyst-cloud/types`' `EntityName`,
+ * `SNAPSHOT_TABLES`, and the SDK's published `ENTITY_NAMES`. A table that is mirrored but must NEVER
+ * be broadcast account-wide goes in `nonFeedEntityTables` instead — see its doc for the reason that
+ * distinction exists at all.
+ *
+ * The
  * infra tables — processed_events / change_log / event_log / sync_cursors — are deliberately excluded:
  * they never ride a delta.
  *
@@ -137,7 +163,7 @@ export const mirrorSchema = {
  * into a 200k/7-day ring — the ring would hold under a day and every replica cursor would fall off
  * the end. The arithmetic and the rest of the posture live on the table definition in ./mirror.ts.
  */
-export const mirrorEntityTables = {
+export const feedEntityTables = {
   issues,
   labels,
   users,
@@ -168,10 +194,96 @@ export const mirrorEntityTables = {
   pr_conversation_comments,
   pr_commits,
   pr_events,
-  // CTC-619: a member's Web Push subscription.
+  // CTC-667: the current head of a pushed git ref (one row per repo+ref) — the orchestrator's
+  // rebase-detection signal, and the first of the four payload types CTL's dispatch consumes that
+  // the mirror did not carry (CTL-1929's last smee tunnel).
+  pushes,
+  // CTC-704: the per-DELIVERY push row. ⛔ A feed entity precisely because `pushes` cannot be one
+  // faithfully — a producer emits one edge per row, so a per-ref row caps the feed at one edge per
+  // ref per tick (CTL-48: 101 of 138 unmatched smee events were pushes).
+  push_events,
+  // CTC-667: a GitHub deployment and its status history — what `phase-monitor-deploy` and the deploy
+  // state machine key on (`environment`, `state`, `target_url`, `environment_url`).
+  deployments,
+  deployment_statuses,
+  // CTC-667: a PR review thread's RESOLUTION state — the merge gate AGENTS.md names, and the one
+  // fact `pr_review_comments` cannot express (it has no resolution column).
+  pr_review_threads,
+  // CTC-667 item 4: GitHub's OWN check-suite rollup. ⛔ The row is contractual; a derivation from
+  // `check_runs` is NOT — see the table's own header for the two reasons it cannot agree with GitHub.
+  check_suites,
+} as const;
+
+/**
+ * CTC-671 — mirrored tables that must NEVER ride the ACCOUNT-WIDE change feed.
+ *
+ * ⛔ THIS OBJECT IS THE EXCLUSION, AND IT IS STRUCTURAL RATHER THAN SUBTRACTIVE ON PURPOSE. A table
+ * listed here is a real mirror table — the DO creates it, migrations produce it, `MIRROR_TABLE_META`
+ * carries it (so `@catalyst-cloud/replicate`'s `knownColumns` forward-compat path is unchanged) — but
+ * it is not a member of `feedEntityTables`, so no list derived from that object can contain it. There
+ * is no filter to forget and no exclusion array to quietly drop: to put a table on the feed you must
+ * type its name into `feedEntityTables`, which is a deliberate act.
+ *
+ * ⭐ WHY, in one case's words. `push_subscriptions` rows are `endpoint` + `p256dh` + `auth` — together
+ * the complete capability to push arbitrary notifications to that person's browser. CTC-641 found
+ * them being appended to `change_log` and broadcast account-wide to every host replica and every
+ * OTHER member's browser OPFS DB. It fixed the leak by narrowing `MirrorDO.appendAndBroadcast` to
+ * `@catalyst-cloud/types`' `EntityName` — but left this table inside `mirrorEntityTables`, next to a
+ * comment asserting it "rides the change feed like any other entity". The repo then stated two
+ * incompatible things about one table and the MACHINE-READABLE one was the wrong one, so the SDK had
+ * to carry a hand-written exclusion list to avoid republishing it (CTC-643 / sdk#24). CTC-671 is that
+ * second list being deleted: feed membership now has exactly one definition, `feedEntityTables`.
+ *
+ * ⚠️ A table belongs here, not merely out of `mirrorEntityTables`, when it must still REPLICATE to
+ * the surfaces that legitimately hold it while never being broadcast account-wide. Bookkeeping that
+ * no consumer should ever see (`pull_sweeps`, `pr_review_backfill`, `fleet_activity_pruned`) stays
+ * out of BOTH objects — see their own table docs.
+ */
+export const nonFeedEntityTables = {
   push_subscriptions,
 } as const;
 
+/**
+ * Every mirrored ENTITY table — the feed-safe ones plus the deliberately-excluded ones.
+ *
+ * ⚠️ THIS IS NOT THE FEED LIST. It exists so `MIRROR_TABLE_META` keeps describing every replicable
+ * table (PKs, soft-delete posture, and the `columns` set that `@catalyst-cloud/replicate` uses as its
+ * forward-compat `knownColumns` default). Deriving "safe for every reader of the account feed" from
+ * THIS object is the CTC-671 defect; derive it from `feedEntityTables` / `FEED_ENTITY_NAMES`.
+ */
+export const mirrorEntityTables = {
+  ...feedEntityTables,
+  ...nonFeedEntityTables,
+} as const;
+
+/**
+ * ⭐ CTC-671 — THE ONE LIST THAT GOVERNS FEED MEMBERSHIP, as a runtime array.
+ *
+ * `@catalyst-cloud/types`' `EntityName` is a type alias of `FeedEntityName`, `SNAPSHOT_TABLES` is
+ * typed `EntityName`, and `@catalyst-cloud/sdk`'s published `ENTITY_NAMES` is pinned to this array by
+ * `test/entity-names-drift.test.ts`. Add a table to `feedEntityTables` and all three follow; leave it
+ * out and none of them can name it.
+ */
+export const FEED_ENTITY_NAMES: readonly FeedEntityName[] = keysOf(feedEntityTables);
+
+/** The excluded set as a runtime array — so a test can assert the exclusion still DOES something. */
+export const NON_FEED_ENTITY_NAMES: readonly NonFeedEntityName[] = keysOf(nonFeedEntityTables);
+
+/**
+ * `Object.keys` with the key type preserved. TypeScript types `Object.keys` as `string[]` because an
+ * object may carry extra keys at runtime; these two objects are `as const` literals declared in this
+ * file, so the narrowing is sound. Contained here so it is the only such assertion in the module.
+ */
+function keysOf<T extends object>(o: T): (keyof T & string)[] {
+  return Object.keys(o) as (keyof T & string)[];
+}
+
+/** The wire `entity` name of a FEED-CARRIED table (keys of feedEntityTables) — the contract. */
+export type FeedEntityName = keyof typeof feedEntityTables;
+
+/** The name of a mirrored-but-never-broadcast table (keys of nonFeedEntityTables). */
+export type NonFeedEntityName = keyof typeof nonFeedEntityTables;
+
 /** The wire `entity` name of a change-feed-carried table (keys of mirrorEntityTables). */
 export type MirrorEntityName = keyof typeof mirrorEntityTables;
 

package/src/migrations.generated.ts

@@ -186,6 +186,27 @@ export const MIRROR_MIGRATIONS = {
         tag: "0024_long_spencer_smythe",
         breakpoints: true,
       },
+      {
+        idx: 25,
+        version: "6",
+        when: 1787013352521,
+        tag: "0025_outgoing_morgan_stark",
+        breakpoints: true,
+      },
+      {
+        idx: 26,
+        version: "6",
+        when: 1787014505223,
+        tag: "0026_curvy_micromacro",
+        breakpoints: true,
+      },
+      {
+        idx: 27,
+        version: "6",
+        when: 1787034085255,
+        tag: "0027_closed_miek",
+        breakpoints: true,
+      },
     ],
   },
   migrations: {
@@ -237,5 +258,11 @@ export const MIRROR_MIGRATIONS = {
       "CREATE TABLE `push_subscriptions` (\n\t`endpoint` text PRIMARY KEY NOT NULL,\n\t`member_id` text NOT NULL,\n\t`p256dh` text NOT NULL,\n\t`auth` text NOT NULL,\n\t`created_at` integer,\n\t`last_used_at` integer\n);\n--> statement-breakpoint\nCREATE INDEX `idx_push_subscriptions_member` ON `push_subscriptions` (`member_id`);",
     "0024_long_spencer_smythe":
       "CREATE TABLE `team_workflow_mapping` (\n\t`team_id` text NOT NULL,\n\t`slot` text NOT NULL,\n\t`linear_state_id` text NOT NULL,\n\t`linear_state_name` text,\n\t`linear_state_type` text,\n\t`workflow_rev` integer,\n\t`updated_at` integer,\n\t`removed_at` integer,\n\tPRIMARY KEY(`team_id`, `slot`)\n);\n",
+    "0025_outgoing_morgan_stark":
+      "CREATE TABLE `pushes` (\n\t`repo_id` text NOT NULL,\n\t`ref` text NOT NULL,\n\t`before` text,\n\t`after` text,\n\t`forced` integer,\n\t`created` integer,\n\t`deleted` integer,\n\t`base_ref` text,\n\t`pusher_id` text,\n\t`head_commit_sha` text,\n\t`updated_at` integer,\n\tPRIMARY KEY(`repo_id`, `ref`)\n);\n",
+    "0026_curvy_micromacro":
+      "CREATE TABLE `deployment_statuses` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`repo_id` text NOT NULL,\n\t`deployment_id` text NOT NULL,\n\t`state` text,\n\t`environment` text,\n\t`target_url` text,\n\t`environment_url` text,\n\t`description` text,\n\t`creator_id` text,\n\t`created_at` integer,\n\t`updated_at` integer\n);\n--> statement-breakpoint\nCREATE INDEX `idx_deployment_statuses_deployment` ON `deployment_statuses` (`deployment_id`,`created_at`);--> statement-breakpoint\nCREATE TABLE `deployments` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`repo_id` text NOT NULL,\n\t`ref` text,\n\t`sha` text,\n\t`task` text,\n\t`environment` text,\n\t`production_environment` integer,\n\t`transient_environment` integer,\n\t`description` text,\n\t`creator_id` text,\n\t`created_at` integer,\n\t`updated_at` integer\n);\n--> statement-breakpoint\nCREATE INDEX `idx_deployments_repo_env` ON `deployments` (`repo_id`,`environment`,`created_at`);--> statement-breakpoint\nCREATE TABLE `pr_review_threads` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`repo_id` text NOT NULL,\n\t`pr_number` integer NOT NULL,\n\t`resolved` integer,\n\t`resolved_at` integer,\n\t`resolver_id` text,\n\t`first_comment_id` text,\n\t`comment_count` integer,\n\t`updated_at` integer\n);\n--> statement-breakpoint\nCREATE INDEX `idx_pr_review_threads_pr` ON `pr_review_threads` (`repo_id`,`pr_number`);",
+    "0027_closed_miek":
+      "CREATE TABLE `check_suites` (\n\t`repo_id` text NOT NULL,\n\t`check_suite_id` text PRIMARY KEY NOT NULL,\n\t`head_sha` text,\n\t`head_branch` text,\n\t`status` text,\n\t`conclusion` text,\n\t`app_slug` text,\n\t`latest_check_runs_count` integer,\n\t`updated_at` integer\n);\n--> statement-breakpoint\nCREATE INDEX `idx_check_suites_sha` ON `check_suites` (`head_sha`);--> statement-breakpoint\nCREATE TABLE `push_events` (\n\t`delivery_id` text PRIMARY KEY NOT NULL,\n\t`repo_id` text NOT NULL,\n\t`ref` text NOT NULL,\n\t`before` text,\n\t`after` text,\n\t`forced` integer,\n\t`created` integer,\n\t`deleted` integer,\n\t`base_ref` text,\n\t`pusher_id` text,\n\t`head_commit_sha` text,\n\t`updated_at` integer\n);\n--> statement-breakpoint\nCREATE INDEX `idx_push_events_repo_ref` ON `push_events` (`repo_id`,`ref`,`updated_at`);--> statement-breakpoint\nALTER TABLE `pull_requests` ADD `merge_commit_sha` text;",
   },
 } as const;

package/src/mirror.ts

@@ -465,6 +465,11 @@ export const pull_requests = sqliteTable(
     // is gated at READ time (a false-positive parse never surfaces because no issue matches it).
     head_ref: text("head_ref"),
     linear_issue_identifier: text("linear_issue_identifier"),
+    // CTC-691: the merge commit SHA GitHub assigns when a PR merges — the join key the host uses
+    // to match a github.pr.merged event to its deployment (setFilterStateMerged). Nullable: GitHub
+    // also sends a throwaway test-merge SHA on UNMERGED PRs, and pre-backfill rows lack it; stored
+    // verbatim because the host discriminates on `merged`, not on SHA presence.
+    merge_commit_sha: text("merge_commit_sha"),
   },
   (t) => [
     primaryKey({ columns: [t.repo_id, t.number] }),
@@ -647,6 +652,353 @@ export const pr_events = sqliteTable(
   (t) => [index("idx_pr_events_pr").on(t.repo_id, t.pr_number, t.created_at)],
 );
 
+/**
+ * CTC-667 — the CURRENT head of a pushed git ref, one row per `(repo_id, ref)`.
+ *
+ * ⛔ WHY THIS EXISTS. `github.push` is the orchestrator's REBASE-DETECTION signal (broker/router.mjs
+ * :1582) and the mirror did not ingest it at all, so the last GitHub smee tunnel cannot be retired
+ * without a host going blind on branch movement (CTL-1929). Live volume on mini-2 for 2026-08: 3,746
+ * push events.
+ *
+ * ⭐ CURRENT STATE, NOT AN EVENT LOG — the same modelling choice every other table here makes, and it
+ * is deliberate rather than lossy. Rebase detection asks "has this ref moved since I last looked",
+ * which a per-ref head answers exactly; the ORDERED sequence of pushes, for anyone who genuinely
+ * needs it, is already the raw passthrough feed's job (`event_log` / `/events/stream`, ADR-0017).
+ * Modelling pushes as rows-per-event would make this table unbounded on a busy repo for a question
+ * nobody in the census asks.
+ *
+ * `before`/`after` are kept even though `after` duplicates the ref head: the PAIR is what
+ * distinguishes a fast-forward from a force-push when read alongside `forced`, and a consumer that
+ * only ever sees the latest row would otherwise have to infer it.
+ *
+ * ⚠️ WEBHOOK-ONLY, NO BOOTSTRAP — a ref whose last push predates this rollout has NO row until its
+ * next push, and on a quiet branch that is never. Raised on #758 (Codex P2). Adding this table to
+ * `SNAPSHOT_TABLES` seeds a fresh replica from the DO, which is right and necessary, but it cannot
+ * invent rows the DO never received: an unpushed-since-rollout ref is currently indistinguishable
+ * from one that never existed — the exact ambiguity the `deleted = 1` rule below exists to avoid for
+ * the OTHER case. The fix is the same backfill as `pr_review_threads` above (CTC-677): seed from
+ * GitHub's current refs rather than only from future webhooks.
+ *
+ * ⚠️ `created` / `deleted` are the webhook's own booleans for branch creation and deletion. A DELETED
+ * ref keeps its row with `deleted = 1` rather than being removed: "this branch is gone" is a fact a
+ * consumer needs, and a vanished row is indistinguishable from one that never existed.
+ */
+export const pushes = sqliteTable(
+  "pushes",
+  {
+    repo_id: text("repo_id").notNull(),
+    /** Full git ref as GitHub sends it, e.g. `refs/heads/main` — NOT shortened, so tags are unambiguous. */
+    ref: text("ref").notNull(),
+    /** The ref's head BEFORE this push (all-zero sha when the ref was just created). */
+    before: text("before"),
+    /** The ref's head AFTER this push (all-zero sha when the ref was deleted). */
+    after: text("after"),
+    /** True when the push was a force-push — the discriminator rebase detection actually keys on. */
+    forced: integer("forced"),
+    /** True when this push created the ref. */
+    created: integer("created"),
+    /** True when this push deleted the ref. */
+    deleted: integer("deleted"),
+    /** The ref this branch was created FROM, when GitHub reports one (`base_ref`); usually null. */
+    base_ref: text("base_ref"),
+    /** Who pushed — the resolvable `github:<login>` key, same convention as pr_events.actor_id. */
+    pusher_id: text("pusher_id"),
+    /** Head commit message/sha of the pushed head, when the payload carried a head_commit. */
+    head_commit_sha: text("head_commit_sha"),
+    updated_at: integer("updated_at"),
+  },
+  (t) => [primaryKey({ columns: [t.repo_id, t.ref] })],
+);
+
+/**
+ * CTC-704 — ONE ROW PER PUSH DELIVERY, append-only, alongside the per-ref `pushes` row above.
+ *
+ * ⛔ WHY THIS EXISTS, and it is a parity blocker rather than a nicety. `pushes` is keyed
+ * `(repo_id, ref)` and carries that ref's CURRENT head — deliberately, and that choice is still
+ * right for the question it answers. But a feed producer emits one edge per ROW, so it can never
+ * emit more than one edge per ref: **two pushes to the same ref between two producer ticks collapse
+ * to one edge**, and the second is unrecoverable from the mirror. CTL-48 measured the consequence
+ * against real traffic — **101 of 138** unmatched smee events were `github.push`, which makes GitHub
+ * parity structurally INCONCLUSIVE and the last smee tunnel un-retirable (CTL-1929).
+ *
+ * ⚠️ The 101 is an UPPER BOUND from a replay, not the live rate: a replay sees one row per ref, while
+ * live only pushes inside a single tick collapse. The number that matters is the shadow window's.
+ *
+ * ⭐ WHY A SECOND TABLE RATHER THAN RE-KEYING `pushes`. This is the same shape `deployment_statuses`
+ * takes next to `deployments`, and for the same stated reason: a consumer that acts on the ARRIVAL of
+ * a transition needs every arrival, while a consumer asking "where is this ref now" needs exactly one
+ * row. Re-keying `pushes` per push would serve the first and break the second — rebase detection
+ * (broker/router.mjs:1582) reads the per-ref head, `SNAPSHOT_TABLES` seeds it as CURRENT STATE, and
+ * both would then have to page an unbounded log to answer a one-row question. Splitting keeps
+ * ⭐ ref-latest EXACTLY derivable — it is the untouched `pushes` row — and costs one additive table.
+ *
+ * ⚠️ NOT SEEDED (absent from `SNAPSHOT_TABLES`), and that is the deliberate half of the trade. This
+ * table grows with every push — 3,746/month on mini-2 — and it is the unboundedness argument in
+ * `pushes`' own doc that makes it wrong to hand a fresh replica the entire history. A new host reads
+ * ref-latest from the seeded `pushes` row and per-push edges from its cursor forward, which is what a
+ * feed CONSUMER needs; nobody in the census asks a fresh replica for last month's push sequence.
+ *
+ * ⭐ THE PK IS THE WEBHOOK DELIVERY ID, which makes a redelivery idempotent for free. GitHub resends
+ * with the same `x-github-delivery`, and `processed_events.delivery_id` already drops a redelivery
+ * BEFORE the normalizer runs (MirrorDO.ts:2276) — so this table cannot double-count even if that
+ * upstream guard were bypassed. ⛔ A synthetic/random id would NOT have this property, and
+ * `(repo_id, ref, after)` would not either: the `pushes` doc records that two separate pushes can
+ * carry the SAME head sha (a revert-and-repush, a branch reset onto an existing sha), so keying on
+ * `after` silently collapses exactly the force-push case this table exists to preserve.
+ *
+ * ⚠️ WEBHOOK-ONLY, NO BACKFILL — like `pushes`, and here it is honest rather than a gap: an event log
+ * cannot invent deliveries that were never received. Parity is measured from the cutover forward.
+ */
+export const push_events = sqliteTable(
+  "push_events",
+  {
+    /** GitHub's `x-github-delivery` for the push webhook — see the header on why this, not a uuid. */
+    delivery_id: text("delivery_id").primaryKey(),
+    repo_id: text("repo_id").notNull(),
+    /** Full git ref as GitHub sends it, e.g. `refs/heads/main` — NOT shortened, so tags are unambiguous. */
+    ref: text("ref").notNull(),
+    /** The ref's head BEFORE this push (all-zero sha when the ref was just created). */
+    before: text("before"),
+    /** The ref's head AFTER this push (all-zero sha when the ref was deleted). */
+    after: text("after"),
+    /** True when the push was a force-push — the discriminator rebase detection actually keys on. */
+    forced: integer("forced"),
+    /** True when this push created the ref. */
+    created: integer("created"),
+    /** True when this push deleted the ref. */
+    deleted: integer("deleted"),
+    /** The ref this branch was created FROM, when GitHub reports one (`base_ref`); usually null. */
+    base_ref: text("base_ref"),
+    /** Who pushed — the resolvable `github:<login>` key, same convention as pr_events.actor_id. */
+    pusher_id: text("pusher_id"),
+    /** Head commit sha of the pushed head, when the payload carried a head_commit. */
+    head_commit_sha: text("head_commit_sha"),
+    /**
+     * ⛔ DELIVERY TIME, not the head commit's timestamp — the same rule `pushes.updated_at` follows
+     * and for the same reason (a force-push to an older commit moves a commit clock BACKWARD). Here
+     * it is also the producer's ORDERING key, so it must be monotonic in arrival order.
+     */
+    updated_at: integer("updated_at"),
+  },
+  (t) => [index("idx_push_events_repo_ref").on(t.repo_id, t.ref, t.updated_at)],
+);
+
+/**
+ * CTC-667 item 4 — a GitHub CHECK SUITE's completion, one row per suite id.
+ *
+ * ⛔ WHY THIS EXISTS. `github.check_suite.completed` is the orchestrator's CI wait
+ * (broker/router.mjs:1497) and the HIGHEST-VOLUME signal in CTL's census — 20,400 events on mini-2 in
+ * 2026-08 — and the mirror stored NO row for it: `normalizeGithub`'s `check_suite` case was a
+ * deliberate `return []`. So the one thing every phase agent blocks on had nothing to read, and the
+ * last GitHub smee tunnel could not be retired.
+ *
+ * ⭐⭐ THE ANSWER TO CTL'S QUESTION — "a suite row or an agreed derivation? just say which is
+ * contractual" — IS **THIS ROW**, AND A DERIVATION FROM `check_runs` IS EXPLICITLY *NOT*
+ * CONTRACTUAL. GitHub computes the rollup itself, and its answer is not reproducible from the
+ * constituent runs without replicating rules we do not have:
+ *
+ *   • ⛔ A DERIVATION MUST NOT BE "every run concluded `success`". `neutral` and `skipped` are
+ *     NON-FAILING under GitHub's own rollup, and this fleet has real rows of both — check run
+ *     `84696876797` is a genuine `neutral` (measured while fixing CTC-673). The naive rule reports a
+ *     GREEN suite as not-green, which for a CI wait means a phase agent blocking forever on a build
+ *     that already passed.
+ *   • ⛔ REQUIRED vs NON-REQUIRED checks are a BRANCH-PROTECTION fact, not a check_runs fact. A suite
+ *     can conclude `success` with a failing non-required run in it. Nothing in `check_runs` carries
+ *     the required-ness, so no derivation over that table can agree with GitHub in general.
+ *
+ * Storing GitHub's own `conclusion` sidesteps both. ⚠️ IF a consumer ever must derive one anyway
+ * (e.g. for suites predating this table), the ONLY defensible rule is **"no run failed, and all runs
+ * completed"** — never "all concluded success". Written down here so the second definition CTL was
+ * right to fear does not get invented independently.
+ *
+ * ⭐ CURRENT STATE, one row per suite id, same as every table here. A suite's interesting movement is
+ * `status`/`conclusion` converging, and the ORDERED history is the raw passthrough feed's job
+ * (ADR-0017) — exactly the argument `pushes` above makes.
+ *
+ * ⚠️ `conclusion` IS MUTABLE AFTER COMPLETION and this is the CTC-673 trap in a new place: a re-run
+ * or a late correction changes `conclusion` while `updated_at` (derived from an EVENT time) can stay
+ * put. CTC-673 fixed the upsert guard to accept an equal-timestamp write whose CONTENT differs, which
+ * is what lets this row converge at all — do not re-narrow that guard.
+ *
+ * ⚠️ `app_slug` distinguishes suites from different CI providers on one SHA (GitHub Actions, CodeQL,
+ * a third-party app). A consumer that waits on "the" suite for a SHA without it would pick one
+ * arbitrarily and report the wrong verdict on any repo with two providers — which this one has.
+ */
+export const check_suites = sqliteTable(
+  "check_suites",
+  {
+    repo_id: text("repo_id").notNull(),
+    /** GitHub's own check-suite id, as a string (same convention as check_runs.check_run_id). */
+    check_suite_id: text("check_suite_id").primaryKey(),
+    /** The commit this suite ran against — the join key every CI wait uses. */
+    head_sha: text("head_sha"),
+    /** The branch GitHub attributes the suite to, when it reports one. */
+    head_branch: text("head_branch"),
+    /** `queued` | `in_progress` | `completed` — a conclusion is only meaningful once completed. */
+    status: text("status"),
+    /** GitHub's OWN rollup: success | failure | neutral | cancelled | timed_out | action_required |
+     *  stale | skipped | startup_failure, or null while the suite is still running. THE contract. */
+    conclusion: text("conclusion"),
+    /** Which app produced this suite — see the app_slug note in the header. */
+    app_slug: text("app_slug"),
+    /** GitHub's own count of the runs in the suite; useful for spotting a suite still filling up. */
+    latest_check_runs_count: integer("latest_check_runs_count"),
+    updated_at: integer("updated_at"),
+  },
+  (t) => [index("idx_check_suites_sha").on(t.head_sha)],
+);
+
+/**
+ * CTC-667 — a GitHub DEPLOYMENT, one row per deployment id.
+ *
+ * ⛔ WHY THIS EXISTS. `github.deployment.created` is consumed by the orchestrator's deploy state
+ * machine (broker/router.mjs:1446/:1566) and the mirror ingested it not at all, so the last GitHub
+ * smee tunnel cannot be retired without `phase-monitor-deploy` going blind. Live volume on mini-2 for
+ * 2026-08: 68 `deployment.created`.
+ *
+ * ⭐ CURRENT STATE, one row per deployment — a deployment object is mutable only in trivial ways
+ * (description/payload), and its interesting movement lives entirely in its STATUSES, which get their
+ * own table below. `environment` is the field every consumer keys on.
+ *
+ * ⚠️ `sha` and `ref` are both kept and they are NOT redundant: a deployment is created against a ref
+ * (`main`, a tag, a PR head) and pinned to the sha that ref resolved to at creation. A consumer
+ * correlating a deploy with a merge commit needs the sha; one correlating it with a branch needs the
+ * ref. `task` is GitHub's own discriminator (`deploy` vs `deploy:migrations` etc.) and is what
+ * distinguishes two deployments to the same environment in the same second.
+ */
+export const deployments = sqliteTable(
+  "deployments",
+  {
+    /** GitHub's numeric deployment id, as text (same convention as the other GitHub id keys here). */
+    id: text("id").primaryKey(),
+    repo_id: text("repo_id").notNull(),
+    /** The git ref the deployment was created against, as sent (`main`, `refs/tags/v1`, a PR head). */
+    ref: text("ref"),
+    /** The commit sha that `ref` resolved to at creation — the correlation key for a merge commit. */
+    sha: text("sha"),
+    /** GitHub's task discriminator (`deploy`, `deploy:migrations`, …); distinguishes sibling deploys. */
+    task: text("task"),
+    /** The environment name — the field the deploy state machine keys on (`staging`, `production`). */
+    environment: text("environment"),
+    /** GitHub's own "is this the live one" flag for the environment, when the payload carries it. */
+    production_environment: integer("production_environment"),
+    /** True when GitHub marks the environment transient (a preview/PR env that will be torn down). */
+    transient_environment: integer("transient_environment"),
+    /** Human description, when supplied by whoever created the deployment. */
+    description: text("description"),
+    /** Who created it — the resolvable `github:<login>` key, same convention as pr_events.actor_id. */
+    creator_id: text("creator_id"),
+    created_at: integer("created_at"),
+    updated_at: integer("updated_at"),
+  },
+  (t) => [index("idx_deployments_repo_env").on(t.repo_id, t.environment, t.created_at)],
+);
+
+/**
+ * CTC-667 — a deployment's STATUS transitions, one row per status id (append-only).
+ *
+ * ⛔ WHY A SECOND TABLE RATHER THAN A `state` COLUMN ON `deployments`. The orchestrator routes on
+ * `github.deployment_status.success|failure|error` (broker/router.mjs:1456/:1570) — it acts on the
+ * ARRIVAL of a transition, not on a current value. Folding statuses into the deployment row would
+ * collapse `pending → in_progress → success` into whatever the replica happened to observe last, so
+ * two transitions landing between one host's polls would silently lose the first. GitHub's statuses
+ * are immutable and carry their own ids, which makes append-only the honest model — the same choice
+ * `pr_events` makes, and for the same reason.
+ *
+ * ⭐ AND THE VOLUME MAKES IT FREE. `deployment_status.*` ran 136 events on mini-2 for all of 2026-08.
+ * The unboundedness argument that made `pushes` current-state (3,746/month, one question) does not
+ * apply here: this table grows by low hundreds a month and answers a question about ORDER.
+ *
+ * ⚠️ `target_url` and `environment_url` are BOTH carried and are different things — `target_url` is
+ * where the deploy's LOGS are (the CI run), `environment_url` is where the deployed thing IS. The
+ * census names both because the state machine reads both; keeping only one would look complete.
+ */
+export const deployment_statuses = sqliteTable(
+  "deployment_statuses",
+  {
+    /** GitHub's numeric deployment-status id, as text. Immutable — a status is never rewritten. */
+    id: text("id").primaryKey(),
+    repo_id: text("repo_id").notNull(),
+    /** FK to `deployments.id`. Kept as text for the same reason `id` is. */
+    deployment_id: text("deployment_id").notNull(),
+    /** pending | queued | in_progress | success | failure | error | inactive — GitHub's own vocabulary. */
+    state: text("state"),
+    /** The environment, denormalized from the status (GitHub sends it) so a reader needs no join. */
+    environment: text("environment"),
+    /** Where the deploy's LOGS are — the CI run URL. */
+    target_url: text("target_url"),
+    /** Where the deployed thing IS — the live URL for this environment. */
+    environment_url: text("environment_url"),
+    description: text("description"),
+    /** Who/what reported the status — the resolvable `github:<login>` key. */
+    creator_id: text("creator_id"),
+    created_at: integer("created_at"),
+    updated_at: integer("updated_at"),
+  },
+  (t) => [index("idx_deployment_statuses_deployment").on(t.deployment_id, t.created_at)],
+);
+
+/**
+ * CTC-667 — a PR review THREAD's resolution state, one row per thread.
+ *
+ * ⛔ WHY THIS EXISTS, and it is a merge gate rather than a nicety. AGENTS.md makes "every review
+ * thread has been addressed and resolved" a condition for merging, the orchestrator routes on
+ * `github.pr_review_thread.resolved` (broker/router.mjs:1562), and `pr_review_comments` has NO
+ * resolution column — so with the smee tunnel gone, thread resolution is not merely stale, it is
+ * UNRECONSTRUCTABLE from the replica. Live volume on mini-2 for 2026-08: 2,111 resolutions.
+ *
+ * ⭐ CURRENT STATE, one row per thread, and here that IS the question: the gate asks "is this thread
+ * resolved NOW", not "how many times was it toggled". A thread that is resolved, reopened and
+ * resolved again ends in the same place a consumer needs to read.
+ *
+ * ⚠️ `id` IS GITHUB'S GRAPHQL `node_id`, NOT A NUMERIC REST ID — the `pull_request_review_thread`
+ * webhook's `thread` object carries no numeric id at all. This is the only GitHub table here whose
+ * key is a node id, which is why it is said out loud: a reader assuming the numeric convention would
+ * write a joiner that never matches.
+ *
+ * ⛔⛔ WEBHOOK-ONLY, NO BACKFILL — SO THIS TABLE IS NOT YET A MERGE GATE, AND READING IT AS ONE IS A
+ * FALSE GREEN. Raised by a reviewer on #758 (Codex P1) and it is right: GitHub emits
+ * `pull_request_review_thread` ONLY on `resolved` / `unresolved`. A thread that has been OPENED and
+ * never touched again produces no event at all, and nothing else writes here — the
+ * `pull_request_review_comment` webhook carries no thread id, and there is no reconcile leg for this
+ * table. So a PR whose threads are all still open holds ZERO rows, which is byte-identical to a PR
+ * with nothing outstanding.
+ *
+ * ⚠️ That error points the WORST possible direction for the question this table exists to answer:
+ * "does this PR have unresolved threads" would read NO for exactly the PRs that most need a yes. Until
+ * a backfill lands (CTC-677 — seed a PR's thread set from GitHub's GraphQL `pullRequest.reviewThreads`
+ * on the same reconcile pass that already sweeps its comments), this table answers only the NARROWER
+ * question it can actually answer: "of the threads we have observed a resolution event for, what is
+ * their current state". Do not wire the AGENTS.md merge gate to it before then.
+ *
+ * ⚠️ `first_comment_id` is the anchor INTO `pr_review_comments` (the earliest comment the thread's
+ * payload carries), because the reverse link does not exist — the `pull_request_review_comment`
+ * webhook carries no thread id, so a comment cannot name its thread. Nullable: a thread payload
+ * arriving with an empty `comments` array is not an error, it is a thread whose comments were
+ * deleted.
+ */
+export const pr_review_threads = sqliteTable(
+  "pr_review_threads",
+  {
+    /** GitHub's GraphQL `node_id` for the thread — NOT a numeric REST id (see the doc above). */
+    id: text("id").primaryKey(),
+    repo_id: text("repo_id").notNull(),
+    pr_number: integer("pr_number").notNull(),
+    /** 1 resolved / 0 unresolved / null unknown — never coerce an absent action to "unresolved". */
+    resolved: integer("resolved"),
+    /** When it was last resolved (ms epoch); null while unresolved or never resolved. */
+    resolved_at: integer("resolved_at"),
+    /** Who resolved it — the resolvable `github:<login>` key; null when unresolved. */
+    resolver_id: text("resolver_id"),
+    /** The earliest comment id in the thread — the anchor into pr_review_comments (see doc). */
+    first_comment_id: text("first_comment_id"),
+    /** How many comments the thread's payload carried, so "empty thread" is distinguishable from null. */
+    comment_count: integer("comment_count"),
+    updated_at: integer("updated_at"),
+  },
+  (t) => [index("idx_pr_review_threads_pr").on(t.repo_id, t.pr_number)],
+);
+
 // ── Mirror infra (not domain entities — never ride the change-feed) ─────────────────────────────────
 
 export const processed_events = sqliteTable("processed_events", {