@catalyst-cloud/schema 0.1.44 → 0.1.46

package/package.json

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

@@ -76,6 +76,27 @@ export const durableEventTypes = {
     ingestVerb: "coordination.publish",
     wakes: false,
   },
+  // CTC-838 — a long-lived coordination agent (concierge/steward/worker) announcing which ROLE it
+  // holds, so the fleet's own agent_roster (apps/mirror/src/do/agent-roster.ts) can answer "who holds
+  // which role, and are they alive" without inventing a heartbeat-shaped table of its own. See
+  // ADR-20260903T011701 for why this is observational only.
+  "agent.role.started": {
+    rationale:
+      "A long-lived coordination agent announced the ROLE it holds (concierge / steward / worker) and, when it has one, its parent — a discrete boundary fact, not a sampled reading. The paired terminal fact is agent.role.stopped.",
+    ingestVerb: "coordination.publish",
+    // ⛔ CTC-838 / ADR-20260903T011701 — a roster row is observational only. Waking a dispatcher on it would
+    // make a heartbeat-derived signal load-bearing for scheduling, which this repo's lease and
+    // entitlement planes explicitly refuse (lease-verbs.ts:10-13).
+    wakes: false,
+    entity: "agent",
+  },
+  "agent.role.stopped": {
+    rationale:
+      "A coordination agent released its role — the paired terminal fact to agent.role.started, and the only thing that distinguishes 'went away cleanly' from 'stopped pulsing'.",
+    ingestVerb: "coordination.publish",
+    wakes: false,
+    entity: "agent",
+  },
   "agent.waiting-on-user": {
     rationale:
       "The agent is now blocked awaiting human input — a coordination fact a host must act on.",
@@ -770,6 +791,20 @@ export const durableEventTypes = {
     wakes: false,
     entity: "ticket",
   },
+  "phase.merge.complete": {
+    rationale:
+      "ADR-0039 durable-fact example ('a phase started, completed, failed, or was preempted'): the phase reported success.",
+    ingestVerb: "coordination.publish",
+    wakes: false,
+    entity: "ticket",
+  },
+  "phase.merge.failed": {
+    rationale:
+      "ADR-0039 durable-fact example ('a phase started, completed, failed, or was preempted'): the phase reported failure.",
+    ingestVerb: "coordination.publish",
+    wakes: false,
+    entity: "ticket",
+  },
   "phase.merge.park": {
     rationale:
       "ADR-0039 durable-fact example ('a phase started, completed, failed, or was preempted'): the merge phase was PARKED after N consecutive failures (CTC-1270) — a terminal-until-released outcome, distinct from `phase.merge.failed`, which a reader must be able to tell apart. Paired with `phase.merge.revive`.",
@@ -1141,6 +1176,13 @@ export const durableEventTypes = {
     wakes: false,
     entity: "ticket",
   },
+  "phase.remediate.blocked": {
+    rationale:
+      "ADR-0039 durable-fact example: an escalated remediate round's exhaustion (or its own declared block) raised a catalyst-ask decision ticket that BLOCKS the remediated ticket (CTC-1373) — a confirmed, terminal-until-answered designation, distinct from `phase.remediate.escalation-exhausted`, which merely requested it.",
+    ingestVerb: "coordination.publish",
+    wakes: false,
+    entity: "ticket",
+  },
   "phase.remediate.boot-resume": {
     rationale:
       "ADR-0039 durable-fact example ('a phase started, completed, failed, or was preempted'): the daemon restarted and resumed this phase — a real coordination fact about continuity across a restart.",
@@ -1162,6 +1204,20 @@ export const durableEventTypes = {
     wakes: false,
     entity: "ticket",
   },
+  "phase.remediate.escalated": {
+    rationale:
+      "ADR-0039 durable-fact example: a remediate round's cap-exhaustion escalated to a second, broader-purview attempt instead of parking (CTC-1373) — a distinct lifecycle transition from an ordinary `phase.remediate.failed`, and one that creates newly claimable work.",
+    ingestVerb: "coordination.publish",
+    wakes: { consumerClass: "dispatcher" },
+    entity: "ticket",
+  },
+  "phase.remediate.escalation-exhausted": {
+    rationale:
+      "ADR-0039 durable-fact example: the escalated (broader-purview) remediate round also failed, or declared itself blocked (CTC-1373) — the terminal signal that requests a blocking ASK ticket be raised; see the paired `phase.remediate.blocked` once one is confirmed.",
+    ingestVerb: "coordination.publish",
+    wakes: false,
+    entity: "ticket",
+  },
   "phase.remediate.failed": {
     rationale:
       "ADR-0039 durable-fact example ('a phase started, completed, failed, or was preempted'): the phase reported failure.",
@@ -1211,6 +1267,20 @@ export const durableEventTypes = {
     wakes: false,
     entity: "ticket",
   },
+  "phase.remediate.rewind": {
+    rationale:
+      "ADR-0039 durable-fact example: a successful remediate round's own ladder-rewind request was applied (CTC-1373) — earlier relay_phase_state rows were reset to `ready`, creating newly claimable work for the reset span.",
+    ingestVerb: "coordination.publish",
+    wakes: { consumerClass: "dispatcher" },
+    entity: "ticket",
+  },
+  "phase.remediate.rewind-requested": {
+    rationale:
+      "ADR-0039 durable-fact example: a successful remediate round recommended the ladder start over rather than advance (CTC-1373's adjudication) — a request the mirror applies under its own fence and budget; see the paired `phase.remediate.rewind` once applied.",
+    ingestVerb: "coordination.publish",
+    wakes: false,
+    entity: "ticket",
+  },
   "phase.rescue.dispatched": {
     rationale:
       "ADR-0039 durable-fact example ('a phase started, completed, failed, or was preempted'): work became eligible and was dispatched to a worker.",
@@ -1512,6 +1582,20 @@ export const durableEventTypes = {
     wakes: false,
     entity: "ticket",
   },
+  "phase.validate.complete": {
+    rationale:
+      "ADR-0039 durable-fact example ('a phase started, completed, failed, or was preempted'): the phase reported success.",
+    ingestVerb: "coordination.publish",
+    wakes: false,
+    entity: "ticket",
+  },
+  "phase.validate.failed": {
+    rationale:
+      "ADR-0039 durable-fact example ('a phase started, completed, failed, or was preempted'): the phase reported failure. CTC-1541 — absent until now, so the record the runner has always published was dropped at deriveDurableCoordinationEvents's classification filter and never reached phase-failure-trigger.ts; ADR-0069 D3's 'every per-ticket failure drives the trigger' was not true for validate.",
+    ingestVerb: "coordination.publish",
+    wakes: false,
+    entity: "ticket",
+  },
   "phase.validate.park": {
     rationale:
       "ADR-0039 durable-fact example ('a phase started, completed, failed, or was preempted'): the validate phase was PARKED after N consecutive failures (CTC-1270) — a terminal-until-released outcome, distinct from `phase.validate.failed`, which a reader must be able to tell apart. Paired with `phase.validate.revive`.",
@@ -1861,6 +1945,13 @@ export interface CurrentStateEventSpec {
  * for zero replay value.
  */
 export const currentStateEventTypes = {
+  // CTC-838 — the pulse half of the agent-role pair above: updates the agent_roster row's
+  // last_seen_at in place rather than growing the durable history on every pulse.
+  "agent.role.heartbeat": {
+    rationale:
+      "A coordination agent's role liveness pulse — updates mutable NOW (the agent_roster row's last_seen_at); agent.role.started/stopped are the durable boundary facts.",
+    boundaryEvents: ["agent.role.started", "agent.role.stopped"],
+  },
   "broker.daemon.heartbeat": {
     rationale:
       "The coordination broker daemon's own liveness pulse — updates mutable NOW; startup/shutdown are the durable boundary facts.",
@@ -1978,6 +2069,11 @@ export const telemetryEventTypes = {
     reason:
       "A replica read falling back to a secondary path — an internal routing diagnostic, not a ticket/phase coordination fact.",
   },
+  "catalyst.runner.egress.policy.applied": {
+    reason:
+      "CTC-1501 — one point per RunnerDispatchDO `/ensure` egress-policy application, `outcome` carrying ok (applied) / error (observe-mode swallow, `detail` naming the classified reason) / skip (RUNNER_EGRESS_MODE=off). Gauge/ratio-shaped: the whole value is the rollup of error-over-total, which is the denominator the ticket's own 'how often, versus container starts per hour' question needs — no individual /ensure poll has identity. The durable fact a failed application produces elsewhere is the phase outcome's egress: unpoliced attribute (loop.ts), not this point.",
+    sampling: { kind: "counted" },
+  },
   "catalyst.service.health": { reason: "A periodic service health-check gauge." },
   "ci.run.completed": {
     reason:

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

@@ -45,6 +45,21 @@ export interface PhaseLifecycleFields {
   artifactKey?: string;
   durationMs?: number;
   reason?: string;
+  /** CTC-1417 — the Linear team key. Optional here (an ergonomic caller-facing input, unlike
+   *  TelemetryPoint's wire shape): when omitted, {@link buildPhaseLifecyclePoint} derives it from
+   *  `ticket` via {@link teamFromTicket}. An explicit value always wins over the derivation. */
+  team?: string;
+  /** CTC-1417 — `owner/name`. Optional; a caller with none in scope leaves the point's `repo: null`
+   *  rather than fabricating one. */
+  repo?: string;
+}
+
+/** The Linear team key is the ticket identifier's prefix by construction (`CTC-1390` → `CTC`) — the
+ *  same convention apps/mirror/src/do/ci-run-telemetry.ts's TICKET_SHAPE already depends on. Returns
+ *  null, NEVER a guess, for anything that is not identifier-shaped. */
+export function teamFromTicket(ticket: string): string | null {
+  const m = /^([A-Z][A-Z0-9]{1,9})-\d+$/.exec(ticket);
+  return m === null ? null : m[1]!;
 }
 
 /**
@@ -75,5 +90,8 @@ export function buildPhaseLifecyclePoint(fields: PhaseLifecycleFields): Telemetr
     traceId: `${fields.ticket}:${fields.phase}:${fields.nonce}`,
     durationMs: fields.durationMs ?? null,
     count: 1,
+    projectId: null,
+    repo: fields.repo ?? null,
+    team: fields.team ?? teamFromTicket(fields.ticket),
   };
 }

package/src/telemetry/point.ts

@@ -18,26 +18,31 @@ export const MAX_POINTS_PER_BATCH = 25;
 export const MAX_INDEX_BYTES = 96;
 /** ClickHouse/AE per-blob byte cap. The bounded excerpt (`detail`) is budgeted against this. */
 export const MAX_EXCERPT_BYTES = 1_024;
+/** AE caps each blob at 1 KiB individually and the blob SUM at ~5 KiB. `detail` owns the 1 KiB budget;
+ *  a dimension blob (`project_id`/`repo`/`team`) gets 256 — far above any real `owner/name` (GitHub:
+ *  39 + 100 chars) or Linear team key, and small enough that three of them cannot push a row over the
+ *  sum cap (CTC-1417 D4). */
+export const MAX_DIMENSION_BYTES = 256;
 
 function byteLen(s: string): number {
   return new TextEncoder().encode(s).length;
 }
 
 /**
- * Bound a would-be-blob string to the AE per-blob cap, appending a stable elision marker that names
- * how many bytes were dropped. Truncation is on a UTF-8 CHARACTER boundary: a naive byte slice can
- * split a multi-byte sequence, so the kept bytes are decoded leniently and a trailing partial
- * (U+FFFD) is dropped so the excerpt is always valid text AND stays under the byte budget. Lifted
- * here (CTC-962) from apps/mirror/src/event-stream/validate.ts, which now imports this copy instead
- * of carrying its own — one truncator, not two that could drift.
+ * Bound a would-be-blob string to `cap` (default the AE per-blob cap), appending a stable elision
+ * marker that names how many bytes were dropped. Truncation is on a UTF-8 CHARACTER boundary: a naive
+ * byte slice can split a multi-byte sequence, so the kept bytes are decoded leniently and a trailing
+ * partial (U+FFFD) is dropped so the excerpt is always valid text AND stays under the byte budget.
+ * Lifted here (CTC-962) from apps/mirror/src/event-stream/validate.ts, which now imports this copy
+ * instead of carrying its own — one truncator, not two that could drift.
  */
-export function boundExcerpt(raw: string): string {
+export function boundExcerpt(raw: string, cap: number = MAX_EXCERPT_BYTES): string {
   const bytes = byteLen(raw);
-  if (bytes <= MAX_EXCERPT_BYTES) return raw;
+  if (bytes <= cap) return raw;
   // Reserve marker room using the WORST-CASE omitted count (the whole payload); the real marker is
-  // never longer, so the final excerpt is guaranteed ≤ MAX_EXCERPT_BYTES.
+  // never longer, so the final excerpt is guaranteed ≤ cap.
   const markerReserve = byteLen(`…[+${bytes} bytes]`);
-  const keepBudget = Math.max(0, MAX_EXCERPT_BYTES - markerReserve);
+  const keepBudget = Math.max(0, cap - markerReserve);
   const kept = new TextEncoder().encode(raw).slice(0, keepBudget);
   // Lenient decode → a split trailing multi-byte becomes U+FFFD; strip it so output is valid + smaller.
   let decoded = new TextDecoder().decode(kept);
@@ -46,6 +51,20 @@ export function boundExcerpt(raw: string): string {
   return `${decoded}…[+${omitted} bytes]`;
 }
 
+/**
+ * The ONE builder for an AE `indexes` array in this repo (CTC-1417 D8). Every lane fences on exactly
+ * one low-cardinality value — the tenant — so "every stream is indexed by the same account_id" is a
+ * property of CONSTRUCTION, not a convention five modules separately honour (which is how
+ * catalyst_runner_egress once shipped with no index at all, CTC-1528). THROWS on an over-cap id rather
+ * than truncating: a truncated tenant id is a plausible-looking WRONG fence.
+ */
+export function aeAccountIndexes(accountId: string): string[] {
+  if (byteLen(accountId) > MAX_INDEX_BYTES) {
+    throw new Error(`accountId exceeds ${MAX_INDEX_BYTES}-byte AE index cap`);
+  }
+  return [accountId];
+}
+
 /** Conservative default for a telemetry name with no explicit `sampling` spec — never "unbounded".
  *  70 pre-existing fleet/orchestrator names carry no per-name budget yet (see registry.ts); defaulting
  *  them to `always` would import their full volume into the hot tier the moment anything emits them. */
@@ -76,6 +95,13 @@ export interface TelemetryPoint {
   readonly durationMs: number | null;
   /** >1 when this point is a collapsed repeat (see `collapse`). */
   readonly count: number;
+  /** ADR-0011 dimensions, promoted to typed fields so BOTH legs carry them (ADR-0048 D3: one
+   *  vocabulary, two volumes; CTC-1417). `null` — never absent, never the string "null" — when the
+   *  emitting surface genuinely has no such value. Required-but-nullable ON PURPOSE: an optional field
+   *  lets a call site forget one; a nullable one makes it STATE that it has none. */
+  readonly projectId: string | null;
+  readonly repo: string | null;
+  readonly team: string | null;
 }
 
 /**
@@ -114,14 +140,26 @@ export interface TelemetryAeDataPoint {
  * event-stream/sql-proxy.ts's `doubles:[seq]` already uses. Encoding an unknown duration as `0`
  * (the previous behavior) would have AE and the hot-leg feed report a false zero-latency instead of
  * "no duration recorded", indistinguishable from a real fast operation.
+ *
+ * Blobs 1-5 (`service, name, outcome, traceId, detail`) are FROZEN — the read proxy is positional.
+ * Blobs 6-8 (`project_id, repo, team`, CTC-1417) are APPENDED: an absent dimension emits an empty
+ * string, never a dropped slot, so position never shifts.
  */
 export function toTelemetryDataPoint(p: TelemetryPoint, accountId: string): TelemetryAeDataPoint {
-  if (byteLen(accountId) > MAX_INDEX_BYTES) {
-    throw new Error(`accountId exceeds ${MAX_INDEX_BYTES}-byte AE index cap`);
-  }
+  const dimBlob = (v: string | null): string =>
+    v === null ? "" : boundExcerpt(v, MAX_DIMENSION_BYTES);
   return {
-    indexes: [accountId],
-    blobs: [p.service, p.name, p.outcome, p.traceId, boundExcerpt(p.detail)],
+    indexes: aeAccountIndexes(accountId),
+    blobs: [
+      p.service,
+      p.name,
+      p.outcome,
+      p.traceId,
+      boundExcerpt(p.detail),
+      dimBlob(p.projectId),
+      dimBlob(p.repo),
+      dimBlob(p.team),
+    ],
     doubles: p.durationMs == null ? [p.count] : [p.count, p.durationMs],
   };
 }
@@ -142,6 +180,9 @@ export interface TelemetryStreamRecord {
   readonly detail: string | null;
   readonly duration_ms: number | null;
   readonly count: number;
+  readonly project_id: string | null;
+  readonly repo: string | null;
+  readonly team: string | null;
   readonly [key: string]: unknown;
 }
 
@@ -162,21 +203,29 @@ export function toTelemetryStreamRecord(
     detail: p.detail ? boundExcerpt(p.detail) : null,
     duration_ms: p.durationMs,
     count: p.count,
+    project_id: p.projectId,
+    repo: p.repo,
+    team: p.team,
   };
 }
 
 /**
- * Fold points sharing an identical (name, outcome) pair into a single point carrying the summed
- * count and the FIRST traceId seen for that pair — the direct answer to ADR-0039's measurement (one
- * fact logged 14,256 times). Order-preserving on first occurrence. Applies identically regardless of
- * sampling class, to BOTH legs (D3/D4) — a `counted` name's "never stored individually" guarantee
- * comes from this stage, not from `applySampling`.
+ * Fold points sharing an identical (name, outcome, projectId, repo, team) tuple into a single point
+ * carrying the summed count and the FIRST traceId seen for that tuple — the direct answer to
+ * ADR-0039's measurement (one fact logged 14,256 times). Order-preserving on first occurrence.
+ * Applies identically regardless of sampling class, to BOTH legs (D3/D4) — a `counted` name's
+ * "never stored individually" guarantee comes from this stage, not from `applySampling`.
+ *
+ * The key is widened beyond (name, outcome) to include projectId/repo/team (CTC-1417): once
+ * dimensions live on the point, folding on (name, outcome) alone while spreading the FIRST point
+ * would merge two different repos' identically-named/outcome points into one row carrying the first
+ * repo's name and the SUMMED count — one repo's volume silently attributed to another.
  */
 export function collapse(points: readonly TelemetryPoint[]): TelemetryPoint[] {
   const order: string[] = [];
   const byKey = new Map<string, TelemetryPoint>();
   for (const p of points) {
-    const key = `${p.name}\u0000${p.outcome}`;
+    const key = `${p.name}\u0000${p.outcome}\u0000${p.projectId}\u0000${p.repo}\u0000${p.team}`;
     const existing = byKey.get(key);
     if (existing) {
       byKey.set(key, { ...existing, count: existing.count + p.count });