@catalyst-cloud/schema 0.1.11 → 0.1.13

package/package.json

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

@@ -18,6 +18,7 @@ import {
   issue_history,
   projects,
   cycles,
+  workflow_states,
   initiatives,
   project_initiatives,
   comments,
@@ -35,6 +36,11 @@ import {
   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";
@@ -71,6 +77,7 @@ export const mirrorSchema = {
   issue_history,
   projects,
   cycles,
+  workflow_states,
   initiatives,
   project_initiatives,
   comments,
@@ -97,6 +104,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;
 
 /**
@@ -123,6 +138,7 @@ export const mirrorEntityTables = {
   issue_history,
   projects,
   cycles,
+  workflow_states,
   initiatives,
   project_initiatives,
   comments,
@@ -136,6 +152,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

@@ -158,6 +158,20 @@ export const MIRROR_MIGRATIONS = {
         tag: "0020_wealthy_snowbird",
         breakpoints: true,
       },
+      {
+        idx: 21,
+        version: "6",
+        when: 1786857732587,
+        tag: "0021_worried_annihilus",
+        breakpoints: true,
+      },
+      {
+        idx: 22,
+        version: "6",
+        when: 1786928302892,
+        tag: "0022_chilly_gorgon",
+        breakpoints: true,
+      },
     ],
   },
   migrations: {
@@ -201,5 +215,9 @@ export const MIRROR_MIGRATIONS = {
       "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`);",
+    "0022_chilly_gorgon":
+      "CREATE TABLE `workflow_states` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`team_id` text,\n\t`name` text,\n\t`type` text,\n\t`position` real,\n\t`color` text,\n\t`archived_at` integer,\n\t`updated_at` integer\n);\n--> statement-breakpoint\nCREATE INDEX `idx_workflow_states_team` ON `workflow_states` (`team_id`);--> statement-breakpoint\nALTER TABLE `issues` ADD `state_type` text;--> statement-breakpoint\nALTER TABLE `issues` ADD `state_position` real;",
   },
 } as const;

package/src/mirror.ts

@@ -39,6 +39,11 @@ export const issues = sqliteTable(
     // CTC-148: the workflow state id behind the `state` NAME — lets a consumer key on state without
     // string-matching the renameable name.
     state_id: text("state_id"),
+    // CTC-308: the state's bucket (triage|backlog|unstarted|started|completed|canceled) + its manual
+    // column order — denormalized off `state` (the `workflow_states` FK, below) so a board can order
+    // its columns without a join on the hot path. Null on a partial webhook, exactly like state_id.
+    state_type: text("state_type"),
+    state_position: real("state_position"),
     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).
@@ -308,6 +313,28 @@ export const cycles = sqliteTable("cycles", {
   updated_at: integer("updated_at"),
 });
 
+// Linear workflow states (CTC-308) — the id/type/position behind an issue's `state` NAME, mirrored as
+// its own entity table so a board can order columns by (type, position) and key a column across teams
+// (the prerequisite CTC-277's kanban board blocks on). Small, workspace-wide set — full sweep each
+// pass, same discipline as `labels`/`cycles`. No `removed_at`: Linear ARCHIVES a workflow state rather
+// than deleting it (`archived_at`), same convention `issues.archived_at` already uses.
+export const workflow_states = sqliteTable(
+  "workflow_states",
+  {
+    id: text("id").primaryKey(),
+    team_id: text("team_id"),
+    name: text("name"),
+    // The state's bucket: triage | backlog | unstarted | started | completed | canceled.
+    type: text("type"),
+    // Manual sort rank within its team's workflow — a Float, Linear's own column order.
+    position: real("position"),
+    color: text("color"),
+    archived_at: integer("archived_at"),
+    updated_at: integer("updated_at"),
+  },
+  (t) => [index("idx_workflow_states_team").on(t.team_id)],
+);
+
 // 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.
@@ -446,6 +473,135 @@ export const reviews = sqliteTable("reviews", {
   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", {
@@ -665,3 +821,33 @@ export const pr_review_backfill = sqliteTable(
   },
   (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] })],
+);