@catalyst-cloud/schema 0.1.15 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/schema",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "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,10 @@ import {
   pr_events,
   pr_ancillary_backfill,
   push_subscriptions,
+  pushes,
+  deployments,
+  deployment_statuses,
+  pr_review_threads,
 } from "./mirror.js";
 
 export * from "./mirror.js";
@@ -117,13 +121,27 @@ 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-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,
 } 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 +155,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 +186,89 @@ 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-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,
+} 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,20 @@ 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,
+      },
     ],
   },
   migrations: {
@@ -237,5 +251,9 @@ 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`);",
   },
 } as const;

package/src/mirror.ts

@@ -647,6 +647,192 @@ 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.
+ *
+ * ⚠️ `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-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.
+ *
+ * ⚠️ `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", {