@catalyst-cloud/schema 0.1.27 → 0.1.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/schema",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "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/events/registry.ts

@@ -1843,6 +1843,11 @@ export const telemetryEventTypes = {
       "A replica read falling back to a secondary path — an internal routing diagnostic, not a ticket/phase coordination fact.",
   },
   "catalyst.service.health": { reason: "A periodic service health-check gauge." },
+  "ci.run.completed": {
+    reason:
+      "CTC-1261 M4 — a completed check_suite webhook joined to its ticket at ingest time (head_branch == CTC-NNN by convention), zero extra API calls. Gauge/counter-shaped (catalyst_ci_runs_total{conclusion}): the collapsed count per (ticket, conclusion) is the signal, not any one occurrence's identity.",
+    sampling: { kind: "counted" },
+  },
   "cloud-feed.would-dispatch": {
     reason:
       "A 'would-*' counterfactual dispatch evaluation — the dry-run analogue of phase.dispatch.requested, never an actual dispatch.",
@@ -1945,6 +1950,11 @@ export const telemetryEventTypes = {
     reason:
       "Phase-agent worker-directory garbage collection. phase.terminal.reap-requested alone is 10,015 lines/mo — a periodic sweep re-requesting cleanup of already-terminal workers, not a discrete coordination fact worth replay.",
   },
+  "phase.lifecycle": {
+    reason:
+      "CTC-1261 — one closed vocabulary for every phase-transition observation across the relay ladder (claim, refuse, publish-success, release/setup-failure/reclaim), so a 20-30-runner fleet's phase health is queryable from one AE table by ticket. Each occurrence is individually meaningful (a specific ticket/phase/nonce transition), not a rollup-only gauge — always, never sampled away.",
+    sampling: { kind: "always" },
+  },
   "phase.predecessor.reap-complete": {
     reason:
       "Phase-agent worker-directory garbage collection. phase.terminal.reap-requested alone is 10,015 lines/mo — a periodic sweep re-requesting cleanup of already-terminal workers, not a discrete coordination fact worth replay.",
@@ -2095,6 +2105,16 @@ export const telemetryEventTypes = {
     reason:
       "A periodic context-usage/size sample logged during an agent session — a gauge, not a discrete session-lifecycle fact (contrast session.started/session.ended, which ARE durable).",
   },
+  "work.backlog.sampled": {
+    reason:
+      "CTC-1261 M3 — a per-(team,bucket) count from the 5-minute eligibility sweep (explainEligibleWork), the missing starvation time series (catalyst_work_backlog{team,bucket}). Gauge-shaped: only the collapsed count matters, not any one sweep's identity.",
+    sampling: { kind: "counted" },
+  },
+  "work.oldest-eligible-age.sampled": {
+    reason:
+      "CTC-1261 M3 — a per-team age gauge (catalyst_oldest_eligible_age_seconds) from the same sweep as work.backlog.sampled. Documented approximation: time since the team's dispatch queue was last (re)published (dispatch_queue_meta.published_at), not a true per-ticket time-became-eligible (no such timestamp exists in the schema) — a floor bound, not an exact dwell time.",
+    sampling: { kind: "counted" },
+  },
   "worker.memory.sampled": {
     reason:
       "ADR-0039's own telemetry example ('process samples') applied to a phase worker's own process.",

package/src/index.ts

@@ -86,6 +86,8 @@ export * from "./events/index.js";
 // admission gate over the events registry above, and the pure AE/Iceberg record builders both the
 // mirror Worker and any future out-of-Worker emitter import.
 export * from "./telemetry/point.js";
+// CTC-1261 — the phase.lifecycle family's closed status vocabulary and shared point builder.
+export * from "./telemetry/phase-lifecycle-point.js";
 
 /** Every table in the Mirror DO store — pass as `drizzle(storage, { schema: mirrorSchema })`. */
 export const mirrorSchema = {

package/src/migrations.generated.ts

@@ -235,6 +235,13 @@ export const MIRROR_MIGRATIONS = {
         tag: "0031_ctc851_comment_parent_backfill",
         breakpoints: true,
       },
+      {
+        idx: 32,
+        version: "6",
+        when: 1788057508383,
+        tag: "0032_elite_donald_blake",
+        breakpoints: true,
+      },
     ],
   },
   migrations: {
@@ -299,5 +306,7 @@ export const MIRROR_MIGRATIONS = {
       "ALTER TABLE `comments` ADD `parent_type` text;--> statement-breakpoint\nALTER TABLE `comments` ADD `parent_entity_id` text;--> statement-breakpoint\nCREATE INDEX `idx_comments_parent` ON `comments` (`parent_type`,`parent_entity_id`,`removed_at`);",
     "0031_ctc851_comment_parent_backfill":
       "-- CTC-851 — backfill comment parents + quarantine the pre-fix empty-issue_id orphans.\n--\n-- 0030 adds the parent_type/parent_entity_id columns and fixes both WRITE legs (webhook normalizer +\n-- reconcile) so new/re-swept comments carry a real parent, but that alone converges only rows the\n-- reconcile re-sweeps — and it walks OPEN issues, so a non-issue comment (or a comment on a closed\n-- issue) keeps its corrupt shape forever. This backfill is what makes the CORPUS canonical rather\n-- than just the new writes.\n--\n-- ⭐ Deliberately a DATA migration in the SHARED bundle (the 0014 pattern): the DO and every host /\n-- OPFS replica apply the same MIRROR_MIGRATIONS through the same runner, so each side repairs its OWN\n-- rows locally. That converges every replica WITHOUT emitting a change_log delta per row (migrations\n-- bypass appendChange), so no ring-buffer flood (the CTC-279 concern).\n--\n-- (a) Healthy rows (a real issue_id) → parent_type='issue', parent_entity_id=issue_id.\n-- (b) Orphans (issue_id empty-string — the measured shape — or NULL, defensively) cannot be repaired\n--     from row data: the replica comments table has no `raw` column and no parent signal beyond the\n--     comment-reply parent_id. A pure in-bundle DML migration cannot call Linear, so it QUARANTINES\n--     them: parent_type='unresolved', issue_id nulled — MARKED with a stated reason, never deleted\n--     (the AC explicitly permits quarantine-with-reason). CTC-851 measured 54 such rows live.\n--\n-- Idempotent by the `parent_type IS NULL` guard: once a row is stamped it is skipped on replay, so a\n-- crash between a statement succeeding and its tag being recorded (execReplaySafe) is safe.\nUPDATE `comments`\n  SET `parent_type` = 'issue', `parent_entity_id` = `issue_id`\n  WHERE `parent_type` IS NULL AND `issue_id` IS NOT NULL AND `issue_id` <> '';\n--> statement-breakpoint\nUPDATE `comments`\n  SET `parent_type` = 'unresolved', `issue_id` = NULL\n  WHERE `parent_type` IS NULL AND (`issue_id` = '' OR `issue_id` IS NULL);\n",
+    "0032_elite_donald_blake":
+      "ALTER TABLE `issues` ADD `creator_id` text;--> statement-breakpoint\nALTER TABLE `issues` ADD `creator_name` text;--> statement-breakpoint\nALTER TABLE `issues` ADD `creator_avatar_url` text;",
   },
 } as const;

package/src/mirror.ts

@@ -62,6 +62,10 @@ export const issues = sqliteTable(
     bot_actor_name: text("bot_actor_name"),
     bot_actor_type: text("bot_actor_type"),
     bot_actor_sub_type: text("bot_actor_sub_type"),
+    // CTC-867: the raiser — the Linear issue creator, inline triplet copying comments.author_*.
+    creator_id: text("creator_id"),
+    creator_name: text("creator_name"),
+    creator_avatar_url: text("creator_avatar_url"),
     parent_id: text("parent_id"),
     parent_identifier: text("parent_identifier"),
     // Ticket field enrichment (CTC-TICKET-FIELDS): lifecycle timestamps + due date + snooze + url +

package/src/telemetry/phase-lifecycle-point.ts

@@ -0,0 +1,79 @@
+// phase-lifecycle-point.ts — CTC-1261. The closed `status` vocabulary for the `phase.lifecycle`
+// telemetry family and the shared TelemetryPoint builder every mirror-side emit site (E1/E2/E4)
+// uses, so the four call sites don't hand-build the object literal four different ways.
+//
+// The registry (../events/registry.ts) only runtime-validates the event NAME (assertEmittable) —
+// there is no per-payload-field runtime enum validator anywhere in this package. `status` is a
+// second, independent closed vocabulary layered on top of one registry name, so it needs its own
+// guard here, in the same throw-not-a-falsy-sentinel posture as assertEmittable.
+
+import type { TelemetryPoint } from "./point.js";
+
+export const PHASE_LIFECYCLE_STATUSES = [
+  "claimed",
+  "started",
+  "succeeded",
+  "failed",
+  "refused",
+  "released",
+  "setup_failed",
+  "reclaimed",
+] as const;
+
+export type PhaseLifecycleStatus = (typeof PHASE_LIFECYCLE_STATUSES)[number];
+
+function assertKnownStatus(status: string): asserts status is PhaseLifecycleStatus {
+  if (!(PHASE_LIFECYCLE_STATUSES as readonly string[]).includes(status)) {
+    throw new Error(
+      `phase.lifecycle refuses status "${status}": not one of ${PHASE_LIFECYCLE_STATUSES.join("|")} ` +
+        `(packages/schema/src/telemetry/phase-lifecycle-point.ts is the one closed vocabulary)`,
+    );
+  }
+}
+
+export interface PhaseLifecycleFields {
+  status: PhaseLifecycleStatus;
+  ticket: string;
+  phase: string;
+  nonce: number;
+  executor: string;
+  substrate?: string;
+  provider?: string;
+  branch?: string;
+  baseSha?: string;
+  prNumber?: number;
+  artifactKey?: string;
+  durationMs?: number;
+  reason?: string;
+}
+
+/**
+ * Build one `phase.lifecycle` TelemetryPoint. Throws (never a falsy sentinel) on an unrecognized
+ * `status` — the same posture as `assertEmittable` for the event name.
+ */
+export function buildPhaseLifecyclePoint(fields: PhaseLifecycleFields): TelemetryPoint {
+  assertKnownStatus(fields.status);
+  const detailParts = [
+    `status=${fields.status}`,
+    `ticket=${fields.ticket}`,
+    `phase=${fields.phase}`,
+    `nonce=${fields.nonce}`,
+    `executor=${fields.executor}`,
+    ...(fields.substrate !== undefined ? [`substrate=${fields.substrate}`] : []),
+    ...(fields.provider !== undefined ? [`provider=${fields.provider}`] : []),
+    ...(fields.branch !== undefined ? [`branch=${fields.branch}`] : []),
+    ...(fields.baseSha !== undefined ? [`base_sha=${fields.baseSha}`] : []),
+    ...(fields.prNumber !== undefined ? [`pr_number=${fields.prNumber}`] : []),
+    ...(fields.artifactKey !== undefined ? [`artifact_key=${fields.artifactKey}`] : []),
+    ...(fields.reason !== undefined ? [`reason=${fields.reason}`] : []),
+  ];
+  return {
+    name: "phase.lifecycle",
+    service: "catalyst-cloud.mirror",
+    outcome: fields.status === "failed" || fields.status === "setup_failed" ? "error" : "ok",
+    detail: detailParts.join(" "),
+    traceId: `${fields.ticket}:${fields.phase}:${fields.nonce}`,
+    durationMs: fields.durationMs ?? null,
+    count: 1,
+  };
+}