@catalyst-cloud/schema 0.1.10 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/schema",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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",
@@ -30,7 +30,7 @@
     "drizzle-orm": "0.44.7"
   },
   "devDependencies": {
-    "@catalyst-cloud/typescript-config": "0.0.0",
+    "@catalyst-cloud/typescript-config": "workspace:*",
     "@types/node": "^25.9.3",
     "drizzle-kit": "^0.31.0",
     "prettier": "^3.8.4",

package/src/index.ts

@@ -34,6 +34,12 @@ import {
   agent_activities,
   fleet_activity_pruned,
   pull_sweeps,
+  pr_review_backfill,
+  pr_review_comments,
+  pr_conversation_comments,
+  pr_commits,
+  pr_events,
+  pr_ancillary_backfill,
 } from "./mirror.js";
 
 export * from "./mirror.js";
@@ -86,6 +92,9 @@ export const mirrorSchema = {
   // migration bundle must produce) but DELIBERATELY ABSENT from `mirrorEntityTables` below — see the
   // no-feed arithmetic on the table definition in ./mirror.ts.
   pull_sweeps,
+  // CTC-575: the closed/merged-PR review-body backfill marker. Same posture as pull_sweeps — a real
+  // table, deliberately absent from mirrorEntityTables (see the doc on the table itself).
+  pr_review_backfill,
   // CTC-393: the fleet_activity anti-resurrection tombstone. Same posture as pull_sweeps — a real
   // table the DO creates, but pure internal bookkeeping that must NEVER ride the change-feed (a
   // consumer has no use for "a row was once terminal here"; see the doc on the table itself).
@@ -93,6 +102,14 @@ export const mirrorSchema = {
   agent_sessions,
   agent_activities,
   fleet_activity_pruned,
+  // CTC-575/577: inline review comments, PR conversation comments, PR commits, PR timeline events —
+  // all four ARE change-feed entities (see mirrorEntityTables below). The fifth new table,
+  // pr_ancillary_backfill, is hub-read-only like pr_review_backfill (see its own doc).
+  pr_review_comments,
+  pr_conversation_comments,
+  pr_commits,
+  pr_events,
+  pr_ancillary_backfill,
 } as const;
 
 /**
@@ -132,6 +149,11 @@ export const mirrorEntityTables = {
   // CTC-524: agent sessions + their activities.
   agent_sessions,
   agent_activities,
+  // CTC-575/577: inline review comments, PR conversation comments, PR commits, PR timeline events.
+  pr_review_comments,
+  pr_conversation_comments,
+  pr_commits,
+  pr_events,
 } as const;
 
 /** The wire `entity` name of a change-feed-carried table (keys of mirrorEntityTables). */

package/src/migrations.generated.ts

@@ -151,6 +151,20 @@ export const MIRROR_MIGRATIONS = {
         tag: "0019_mushy_sinister_six",
         breakpoints: true,
       },
+      {
+        idx: 20,
+        version: "6",
+        when: 1786856395245,
+        tag: "0020_wealthy_snowbird",
+        breakpoints: true,
+      },
+      {
+        idx: 21,
+        version: "6",
+        when: 1786857732587,
+        tag: "0021_worried_annihilus",
+        breakpoints: true,
+      },
     ],
   },
   migrations: {
@@ -192,5 +206,9 @@ export const MIRROR_MIGRATIONS = {
       "CREATE TABLE `agent_activities` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`session_id` text NOT NULL,\n\t`type` text,\n\t`body` text,\n\t`signal` text,\n\t`created_at` integer,\n\t`updated_at` integer,\n\t`raw` text\n);\n--> statement-breakpoint\nCREATE INDEX `idx_agent_activities_session_created` ON `agent_activities` (`session_id`,`created_at`);--> statement-breakpoint\nCREATE TABLE `agent_sessions` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`issue_id` text,\n\t`status` text,\n\t`app_user_id` text,\n\t`creator_id` text,\n\t`created_at` integer,\n\t`updated_at` integer,\n\t`removed_at` integer,\n\t`raw` text\n);\n--> statement-breakpoint\nCREATE INDEX `idx_agent_sessions_issue` ON `agent_sessions` (`issue_id`,`updated_at`);",
     "0019_mushy_sinister_six":
       "ALTER TABLE `agent_sessions` ADD `archived_at` integer;--> statement-breakpoint\nALTER TABLE `agent_sessions` ADD `dismissed_at` integer;--> statement-breakpoint\nALTER TABLE `agent_sessions` ADD `dismissed_by` text;",
+    "0020_wealthy_snowbird":
+      "CREATE TABLE `pr_review_backfill` (\n\t`repo_id` text NOT NULL,\n\t`pr_number` integer NOT NULL,\n\t`backfilled_at` integer NOT NULL,\n\tPRIMARY KEY(`repo_id`, `pr_number`)\n);\n--> statement-breakpoint\nALTER TABLE `reviews` ADD `body` text;",
+    "0021_worried_annihilus":
+      "CREATE TABLE `pr_ancillary_backfill` (\n\t`repo_id` text NOT NULL,\n\t`pr_number` integer NOT NULL,\n\t`backfilled_at` integer NOT NULL,\n\tPRIMARY KEY(`repo_id`, `pr_number`)\n);\n--> statement-breakpoint\nCREATE TABLE `pr_commits` (\n\t`repo_id` text NOT NULL,\n\t`pr_number` integer NOT NULL,\n\t`sha` text NOT NULL,\n\t`message` text,\n\t`author_login` text,\n\t`author_name` text,\n\t`author_email` text,\n\t`authored_at` integer,\n\t`committed_at` integer,\n\tPRIMARY KEY(`repo_id`, `pr_number`, `sha`)\n);\n--> statement-breakpoint\nCREATE TABLE `pr_conversation_comments` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`repo_id` text NOT NULL,\n\t`pr_number` integer NOT NULL,\n\t`author_id` text,\n\t`body` text,\n\t`created_at` integer,\n\t`updated_at` integer,\n\t`removed_at` integer\n);\n--> statement-breakpoint\nCREATE INDEX `idx_pr_conversation_comments_pr` ON `pr_conversation_comments` (`repo_id`,`pr_number`);--> statement-breakpoint\nCREATE TABLE `pr_events` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`repo_id` text NOT NULL,\n\t`pr_number` integer NOT NULL,\n\t`action` text,\n\t`actor_id` text,\n\t`created_at` integer,\n\t`updated_at` integer,\n\t`raw` text\n);\n--> statement-breakpoint\nCREATE INDEX `idx_pr_events_pr` ON `pr_events` (`repo_id`,`pr_number`,`created_at`);--> statement-breakpoint\nCREATE TABLE `pr_review_comments` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`repo_id` text NOT NULL,\n\t`pr_number` integer NOT NULL,\n\t`review_id` text,\n\t`commit_id` text,\n\t`path` text,\n\t`line` integer,\n\t`diff_hunk` text,\n\t`in_reply_to_id` text,\n\t`author_id` text,\n\t`body` text,\n\t`created_at` integer,\n\t`updated_at` integer,\n\t`removed_at` integer\n);\n--> statement-breakpoint\nCREATE INDEX `idx_pr_review_comments_pr` ON `pr_review_comments` (`repo_id`,`pr_number`);",
   },
 } as const;

package/src/mirror.ts

@@ -438,8 +438,143 @@ export const reviews = sqliteTable("reviews", {
   user_id: text("user_id"),
   state: text("state"),
   submitted_at: integer("submitted_at"),
+  // CTC-575: the review's text. GitHub always sends it; it was destructured away at the type boundary
+  // in three places (github/queries.ts, normalize/github.ts ×2) before this. ⛔ `reviews` has NO
+  // updated_at, so upsertRow's last-write-wins guard is inert here — the reconcile's hand-rolled
+  // read-before-emit (github-reconcile.ts) is the ONLY thing that decides whether an edited body
+  // re-emits a change_log delta, and it must compare `body` too or an edit never propagates.
+  body: text("body"),
 });
 
+/**
+ * CTC-575 — inline PR review comments (the diff-attached kind, `GET /pulls/{n}/comments` +
+ * the `pull_request_review_comment` webhook). Distinct from {@link pr_conversation_comments} below —
+ * GitHub itself models these as two different REST resources and two different webhook events; this
+ * table only ever holds the diff-anchored kind (`path`/`line`/`diff_hunk` are meaningful here and
+ * absent on a conversation comment).
+ *
+ * `updated_at` IS present (unlike `reviews`) — GitHub bumps it on an edit, so the ordinary
+ * `upsertRow` last-write-wins guard is live here; no hand-rolled read-before-emit needed.
+ * Soft-delete (`removed_at`): the webhook sends `action: "deleted"` for a genuinely deleted comment.
+ */
+export const pr_review_comments = sqliteTable(
+  "pr_review_comments",
+  {
+    id: text("id").primaryKey(),
+    repo_id: text("repo_id").notNull(),
+    pr_number: integer("pr_number").notNull(),
+    // The review this comment belongs to (GitHub's pull_request_review_id) — FK → reviews.review_id.
+    // Nullable: GitHub's own field is optional on some legacy/edge payloads.
+    review_id: text("review_id"),
+    commit_id: text("commit_id"),
+    path: text("path"),
+    line: integer("line"),
+    diff_hunk: text("diff_hunk"),
+    // Threading: the parent comment id when this is a reply. Nullable — most comments are top-level.
+    in_reply_to_id: text("in_reply_to_id"),
+    // The resolvable `github:<login>` users key (CTC-USERS), same convention as reviews.user_id.
+    author_id: text("author_id"),
+    body: text("body"),
+    created_at: integer("created_at"),
+    updated_at: integer("updated_at"),
+    removed_at: integer("removed_at"),
+  },
+  (t) => [index("idx_pr_review_comments_pr").on(t.repo_id, t.pr_number)],
+);
+
+/**
+ * CTC-577 — PR conversation-tab comments (`GET /issues/{n}/comments` + the `issue_comment` webhook,
+ * filtered to deliveries whose `issue.pull_request` is present — GitHub fires `issue_comment` for
+ * BOTH a plain repo issue comment and a PR conversation comment, and does not distinguish them at the
+ * event-type level; the payload's `issue.pull_request` field is the only signal).
+ *
+ * ⚠️ DELIBERATELY A SEPARATE TABLE FROM LINEAR'S `comments`. `comments` is keyed `issue_id` for
+ * LINEAR issues, with no `source`/`repo_id`/`pr_number` column — reusing it would have been a real
+ * schema change (a new discriminator + nullable Linear-only columns going unused on every GitHub row),
+ * not a free ride. A separate table makes "a Linear comment and a PR comment are never confused" true
+ * by construction: there is no shared row space for them to collide in.
+ */
+export const pr_conversation_comments = sqliteTable(
+  "pr_conversation_comments",
+  {
+    id: text("id").primaryKey(),
+    repo_id: text("repo_id").notNull(),
+    pr_number: integer("pr_number").notNull(),
+    author_id: text("author_id"),
+    body: text("body"),
+    created_at: integer("created_at"),
+    updated_at: integer("updated_at"),
+    removed_at: integer("removed_at"),
+  },
+  (t) => [index("idx_pr_conversation_comments_pr").on(t.repo_id, t.pr_number)],
+);
+
+/**
+ * CTC-575 — commits on a PR (`GET /pulls/{n}/commits`). The mirror previously stored only the scalar
+ * `pull_requests.head_sha`; this is the full commit list. Composite PK (repo_id, pr_number, sha): the
+ * SAME commit sha can legitimately appear under more than one PR (e.g. a shared base branch, or a
+ * commit cherry-picked into a second PR), so the PR is part of the identity, not just the commit.
+ *
+ * NO `updated_at` and NO `removed_at`, deliberately: a git commit's content is immutable once
+ * authored — there is no legitimate "edit" of a stored row, only a fresh INSERT for a sha not seen
+ * before. (A force-push that drops a commit from the PR's list leaves a stale row here, same posture
+ * as `check_runs`/`commit_statuses` never retracting a run/status GitHub stops reporting.)
+ */
+export const pr_commits = sqliteTable(
+  "pr_commits",
+  {
+    repo_id: text("repo_id").notNull(),
+    pr_number: integer("pr_number").notNull(),
+    sha: text("sha").notNull(),
+    message: text("message"),
+    // The resolvable `github:<login>` users key when GitHub matched the commit author to an account;
+    // null for an unmatched/external author (common on a rebased or externally-authored commit).
+    author_login: text("author_login"),
+    // The raw git author name/email — kept even when author_login is null, so the commit is never
+    // author-less in the UI just because GitHub couldn't match it to an account.
+    author_name: text("author_name"),
+    author_email: text("author_email"),
+    authored_at: integer("authored_at"),
+    committed_at: integer("committed_at"),
+  },
+  (t) => [primaryKey({ columns: [t.repo_id, t.pr_number, t.sha] })],
+);
+
+/**
+ * CTC-575 — a PR's timeline events (immutable, `issue_history`-shaped), capturing the `action` field
+ * that every `pull_request` webhook already carries and that normalizePullRequest has always
+ * discarded. Curated to the FIVE actions the ticket names — ready_for_review, merged, closed,
+ * reopened, review_requested — not every `pull_request` action GitHub sends: `synchronize` fires on
+ * every push and `labeled`/`unlabeled`/`edited` etc. are not "lifecycle" events, so capturing every
+ * action verbatim would flood this table with noise the ticket never asked for. `merged` is OUR OWN
+ * vocabulary layered on GitHub's `action: "closed"` + `pull_request.merged: true` — GitHub has no
+ * separate "merged" action.
+ *
+ * ⛔ WEBHOOK-ONLY, NO BACKFILL. Unlike the three tables above, there is no REST endpoint that
+ * reconstructs this history for a PR predating the webhook subscription — GitHub's PR object carries
+ * no event log, only the current state. A PR's timeline before this ships is simply not recoverable.
+ *
+ * `id` is a SYNTHETIC key (repo_id:pr_number:action:updated_at ms) — GitHub's `pull_request` webhook
+ * carries no event-level id the way Linear's IssueHistory nodes do. HARD upsert (no removed_at, like
+ * issue_history) — an event, once recorded, never changes or vanishes.
+ */
+export const pr_events = sqliteTable(
+  "pr_events",
+  {
+    id: text("id").primaryKey(),
+    repo_id: text("repo_id").notNull(),
+    pr_number: integer("pr_number").notNull(),
+    // ready_for_review | merged | closed | reopened | review_requested (see the curation note above).
+    action: text("action"),
+    // Who triggered it (the webhook's top-level `sender`) — the resolvable `github:<login>` key.
+    actor_id: text("actor_id"),
+    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
+    raw: text("raw"), // JSON.stringify of the relevant webhook fields — full fidelity / forward-compat
+  },
+  (t) => [index("idx_pr_events_pr").on(t.repo_id, t.pr_number, t.created_at)],
+);
+
 // ── Mirror infra (not domain entities — never ride the change-feed) ─────────────────────────────────
 
 export const processed_events = sqliteTable("processed_events", {
@@ -621,3 +756,71 @@ export const pull_sweeps = sqliteTable(
   },
   (t) => [primaryKey({ columns: [t.repo_id, t.pr_number] })],
 );
+
+/**
+ * CTC-575 — a marker that a CLOSED/MERGED PR's reviews have been swept AT LEAST ONCE for `body`.
+ *
+ * ⛔ WHY THIS EXISTS. `reconcileGithub`'s open-PR walk sweeps reviews only for PRs whose `state` is
+ * still `open` — a closed/merged PR's reviews are frozen at whatever the last webhook or open-PR sweep
+ * wrote, which for every review that predates this ticket is `body: null` (the column did not exist).
+ * Nothing else ever revisits a closed PR, so without a dedicated backfill leg every historical review
+ * body on every already-closed PR would stay null forever.
+ *
+ * ⛔ WHY A MARKER PER PR, NOT A SINGLE RESUME CURSOR. PR numbers are monotonic by CREATION order, not
+ * by CLOSE order — PR #5 can close well after PR #50 already did. A single "highest number backfilled"
+ * watermark (the `resumeEntity`/`mergeableEntity` pattern above) would permanently skip a low-numbered
+ * PR that closes late, once the watermark has already passed its number. A per-(repo_id, pr_number)
+ * marker is checked independently, so a PR is swept exactly once, whenever it happens to close.
+ *
+ * ⛔ DELIBERATELY NOT `pull_sweeps`. That table's three-state decode (no row / SHA-mismatch / count-or-
+ * error) is a documented invariant for the OPEN-PR CI-enrichment receipt (check_runs/commit_statuses),
+ * and this backfill sweeps reviews ONLY for a closed PR — writing a `pull_sweeps` row with
+ * check_run_count/commit_status_count left null and no *_error set would forge a fourth, undocumented
+ * state indistinguishable from "the checks fetch failed". A dedicated table keeps the two receipts'
+ * invariants independently true.
+ *
+ * ⛔ HUB-READ-ONLY, same posture as `pull_sweeps` / `fleet_activity_pruned`: never rides the change
+ * feed (absent from mirrorEntityTables / SNAPSHOT_TABLES / GITHUB_ENTITIES, no appendChange) — a
+ * consumer has no use for "we once swept this PR's reviews", and self-limiting at |closed PRs in the
+ * repo| (one row per PR, written once, never revisited).
+ */
+export const pr_review_backfill = sqliteTable(
+  "pr_review_backfill",
+  {
+    repo_id: text("repo_id").notNull(),
+    pr_number: integer("pr_number").notNull(),
+    /** When the backfill swept this PR's reviews (ms). */
+    backfilled_at: integer("backfilled_at").notNull(),
+  },
+  (t) => [primaryKey({ columns: [t.repo_id, t.pr_number] })],
+);
+
+/**
+ * CTC-575/577 — a marker that a PR's ANCILLARY GitHub entities (review comments, commits,
+ * conversation comments) have been fetched at least once. Unlike {@link pr_review_backfill} (which
+ * tracks a NARROWER re-fetch of already-existing review rows for their new `body` column), this
+ * marker covers three BRAND-NEW tables that start with zero rows for every PR, open or closed — so
+ * the ancillary backfill walks the WHOLE PR list (not just closed ones), gated per-PR by this marker
+ * so a PR already caught up is never re-swept.
+ *
+ * ⚠️ DOES NOT COVER `pr_events` — that table is webhook-only (see its own doc: no REST endpoint can
+ * reconstruct PR timeline history), so there is nothing for a backfill to fetch.
+ *
+ * ⚠️ `pr_commits` HAS NO WEBHOOK, so a PR's commit list is only ever as fresh as its last backfill —
+ * an open PR that receives new commits AFTER being marked backfilled does not get them until this
+ * marker is cleared. Documented trade-off (the ticket asks for a backfill, not continuous freshness);
+ * a future ticket that wants `pr_commits` live on open PRs should sweep it in step 2 as a peer of
+ * checks/statuses/reviews.
+ *
+ * ⛔ HUB-READ-ONLY, same posture as `pr_review_backfill` / `pull_sweeps`: never rides the change feed.
+ */
+export const pr_ancillary_backfill = sqliteTable(
+  "pr_ancillary_backfill",
+  {
+    repo_id: text("repo_id").notNull(),
+    pr_number: integer("pr_number").notNull(),
+    /** When the backfill swept this PR's review comments + commits + conversation comments (ms). */
+    backfilled_at: integer("backfilled_at").notNull(),
+  },
+  (t) => [primaryKey({ columns: [t.repo_id, t.pr_number] })],
+);