@catalyst-cloud/schema 0.1.28 → 0.1.30

package/package.json

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

@@ -1030,6 +1030,13 @@ export const durableEventTypes = {
     wakes: false,
     entity: "ticket",
   },
+  "phase.pr.park": {
+    rationale:
+      "ADR-0039 durable-fact example ('a phase started, completed, failed, or was preempted'): the pr phase was PARKED — a terminal-until-released outcome, distinct from `phase.pr.failed`, which a reader must be able to tell apart (CTC-1322). Paired with the already-registered `phase.pr.revive`.",
+    ingestVerb: "coordination.publish",
+    wakes: false,
+    entity: "ticket",
+  },
   "phase.pr.preempted": {
     rationale:
       "ADR-0039 durable-fact example ('a phase started, completed, failed, or was preempted'): a higher-priority worker preempted this phase.",
@@ -1843,6 +1850,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 +1957,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 +2112,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/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,
+  };
+}