@catalyst-cloud/schema 0.1.52 → 0.1.54

package/package.json

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

@@ -1288,6 +1288,20 @@ export const durableEventTypes = {
     wakes: false,
     entity: "ticket",
   },
+  "phase.remediate.decision-raised": {
+    rationale:
+      "ADR-0039 durable-fact example: the mirror actually raised (or attached to an existing) a catalyst-ask decision ticket for a decision an accepted remediate decision-surfaced record named (CTC-1737) — a confirmed, DO-side fact, distinct from `phase.remediate.decision-surfaced`, which merely reported the session's own words.",
+    ingestVerb: "coordination.publish",
+    wakes: false,
+    entity: "ticket",
+  },
+  "phase.remediate.decision-surfaced": {
+    rationale:
+      "ADR-0039 durable-fact example: a remediate round (ANY tier, unlike `phase.remediate.escalation-exhausted`) reported a genuine human decision via its own decisions.json (CTC-1737) — the requesting signal that asks the mirror to raise a blocking catalyst-ask ticket; see the paired `phase.remediate.decision-raised` once one is confirmed.",
+    ingestVerb: "coordination.publish",
+    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.",
@@ -1678,6 +1692,20 @@ export const durableEventTypes = {
     wakes: false,
     entity: "ticket",
   },
+  "phase.validate.decision-raised": {
+    rationale:
+      "ADR-0039 durable-fact example: the mirror actually raised (or attached to an existing) a catalyst-ask decision ticket for a decision an accepted validate decision-surfaced record named (CTC-1737) — a confirmed, DO-side fact, distinct from `phase.validate.decision-surfaced`, which merely reported the session's own words.",
+    ingestVerb: "coordination.publish",
+    wakes: false,
+    entity: "ticket",
+  },
+  "phase.validate.decision-surfaced": {
+    rationale:
+      "ADR-0039 durable-fact example: a validate round reported a genuine human decision via its own decisions.json (CTC-1737) — `validate` had no decision vocabulary at all before this; the requesting signal that asks the mirror to raise a blocking catalyst-ask ticket, paired with `phase.validate.decision-raised` once one is confirmed.",
+    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.",
@@ -2188,6 +2216,20 @@ export const telemetryEventTypes = {
     reason:
       "A per-turn counter sample of the agent SDK loop — a gauge, not a discrete coordination fact.",
   },
+  // CTC-1385 — the fleet flow-metrics tracer bullet's two per-transition facts. `always`-sampled: each
+  // occurrence is an individually meaningful ticket-/PR-level stage transition (the exact grain the
+  // ship-or-languish cohorts and eval baselines are computed from), not a gauge or a retry-storm signal
+  // — sampling one in a hundred would make a per-cohort probability meaningless.
+  "flow.transition": {
+    reason:
+      "A ticket crossed a flow-board stage boundary — the per-transition fact the P(ship within N days), aging-WIP and stage-stuck metrics are computed from. Individually meaningful, not a sample.",
+    sampling: { kind: "always" },
+  },
+  "flow.pr-transition": {
+    reason:
+      "A pull request crossed a lifecycle boundary (opened/ready/queued/merged/closed) — the PR-side counterpart to flow.transition, same always-sampled reasoning.",
+    sampling: { kind: "always" },
+  },
   "github-feed.would-dispatch": {
     reason:
       "Same 'would-*' counterfactual shape as cloud-feed.would-dispatch, for the GitHub-sourced feed.",

package/src/index.ts

@@ -54,6 +54,7 @@ import {
   fleet_anomalies,
   fleet_activity_rate,
   fleet_health_sends,
+  flow_daily,
 } from "./mirror.js";
 
 export * from "./mirror.js";
@@ -92,6 +93,8 @@ export * from "./events/index.js";
 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";
+// CTC-1385 — the flow.transition / flow.pr-transition family's closed vocabulary and point builders.
+export * from "./telemetry/flow-transition-point.js";
 
 /** Every table in the Mirror DO store — pass as `drizzle(storage, { schema: mirrorSchema })`. */
 export const mirrorSchema = {
@@ -167,6 +170,10 @@ export const mirrorSchema = {
   // consumer should ever see over the feed).
   fleet_activity_rate,
   fleet_health_sends,
+  // CTC-1385: the per-(repo,day) flow-metrics snapshot. A real table the DO creates and the migration
+  // bundle must produce, but DELIBERATELY ABSENT from `feedEntityTables` below — see the no-feed
+  // rationale on the table definition in ./mirror.ts.
+  flow_daily,
 } as const;
 
 /**

package/src/migrations.generated.ts

@@ -284,6 +284,20 @@ export const MIRROR_MIGRATIONS = {
         tag: "0038_ctc1855_fleet_activity_routing",
         breakpoints: true,
       },
+      {
+        idx: 39,
+        version: "6",
+        when: 1789132086184,
+        tag: "0039_unknown_nebula",
+        breakpoints: true,
+      },
+      {
+        idx: 40,
+        version: "6",
+        when: 1789188558404,
+        tag: "0040_ctc1885_workflow_state_name_backfill",
+        breakpoints: true,
+      },
     ],
   },
   migrations: {
@@ -362,5 +376,9 @@ export const MIRROR_MIGRATIONS = {
       "-- CTC-1597 — rename the persisted workflow slot `triage` -> `intake`.\n--\n-- ⭐ Deliberately a DATA migration in the SHARED bundle (the 0014/0031 pattern): the DO and every\n-- host / OPFS replica apply the same MIRROR_MIGRATIONS through the same runner, so each side renames\n-- its OWN rows locally. That converges every replica WITHOUT emitting a change_log delta per row\n-- (migrations bypass appendChange), so no ring-buffer flood.\n--\n-- ⚠️ THE REGISTRY D1 IS THE AUTHORITY and gets its own migration\n-- (apps/mirror/src/registry/migrations/20260903T1928_workflow_slot_intake.sql); this one exists\n-- because a D1-only rewrite bumps no `workflow_rev` and pushes nothing, so a DO that is never\n-- re-saved would sit on the old value forever. THIS migration is what makes the rename correct on\n-- every DO/replica, including one offline at merge time. There is no separate re-projection script:\n-- an already-connected browser/host that needs to see the rename before its own next open converges\n-- the ordinary way — an operator re-saving that team's stage mapping calls the existing full-replace\n-- projection handler (`handleWorkflowMappingUpsert`, MirrorDO.ts), which DOES emit a change_log\n-- delta. No new production route was added for a one-time rename.\n--\n-- PK-safe: (team_id, slot) — and the PK does NOT consider `removed_at`, so a SOFT-DELETED `intake`\n-- row still occupies the slot. Drop a stale `triage` row for a team that already holds ANY `intake`\n-- row — live or soft-deleted — then rename what is left. Idempotent under execReplaySafe replay — a\n-- row already renamed to `intake` no longer matches `slot = 'triage'` on a re-run.\n--\n-- ⛔ CTC-1597 remediate (C2): an earlier draft of the EXISTS guard filtered `removed_at IS NULL`,\n-- reasoning that a soft-deleted `intake` row should never cause a still-live `triage` row to be\n-- dropped instead of renamed. That reasoning had it backwards — the PK collision this guard exists\n-- to prevent happens precisely BECAUSE `removed_at` is not part of the primary key: a host that\n-- receives a soft-deleted `intake` row via replication (from a DO that already renamed and was then\n-- unmapped) before it has applied this migration locally still has its own live `triage` row: the\n-- DELETE's old filter left the `triage` row in place, and the following blind UPDATE then tried to\n-- rename it to a slot value a row already occupies, violating the PK and aborting the whole bundle.\n-- Matching on ANY `intake` row (regardless of `removed_at`) fixes it: the stale `triage` row is\n-- dropped, not renamed, whenever the slot is already spoken for.\n--\n-- ⛔ CTC-1597 remediate (validate-plan finding 1) — a `triage`-slot row whose OWN mapped state is\n-- ITSELF type='triage' (Linear's reserved Triage inbox, legally name-matched into the OLD\n-- `RECOMMENDED_STAGES` entry before this ticket) must NOT be renamed blind: `SLOT_STATE_TYPES.intake`\n-- no longer accepts that type (Scope B), so renaming it in place would silently flip the team's\n-- `types_compatible` check from pass to a blocking fail with no data fix and no recourse — the write\n-- path's own validation (the same narrowing) would refuse a re-save of the identical row. Soft-delete\n-- it instead, via `removed_at` — this table's own convention for \"this slot is unmapped\" (see the\n-- table's doc comment in packages/schema/src/mirror.ts) — so the team lands in the ordinary,\n-- already-actionable \"needs a stage\" state a brand-new team starts in, which Scope C's per-team\n-- runbook resolves. Runs BEFORE the final rename so no live-or-dead row anywhere keeps the retired\n-- `triage` slot value; guarded by `removed_at IS NULL` so a replay is a no-op.\nUPDATE `team_workflow_mapping`\n   SET `removed_at` = CAST(unixepoch() AS INTEGER) * 1000\n WHERE `slot` = 'triage' AND `linear_state_type` = 'triage' AND `removed_at` IS NULL;\n--> statement-breakpoint\nDELETE FROM `team_workflow_mapping`\n WHERE `slot` = 'triage'\n   AND EXISTS (SELECT 1 FROM `team_workflow_mapping` m2\n                WHERE m2.`team_id` = `team_workflow_mapping`.`team_id` AND m2.`slot` = 'intake');\n--> statement-breakpoint\nUPDATE `team_workflow_mapping` SET `slot` = 'intake' WHERE `slot` = 'triage';\n",
     "0038_ctc1855_fleet_activity_routing":
       "ALTER TABLE `fleet_activity` ADD `provider` text;--> statement-breakpoint\nALTER TABLE `fleet_activity` ADD `model` text;--> statement-breakpoint\nALTER TABLE `fleet_activity` ADD `effort` text;--> statement-breakpoint\nALTER TABLE `fleet_activity` ADD `routing_source` text;",
+    "0039_unknown_nebula":
+      "CREATE TABLE `flow_daily` (\n\t`repo_id` text NOT NULL,\n\t`day` text NOT NULL,\n\t`active_count` integer NOT NULL,\n\t`entries` integer NOT NULL,\n\t`exits_to_done` integer NOT NULL,\n\t`exits_to_canceled` integer NOT NULL,\n\t`stage_counts` text,\n\t`aging_p50_seconds` integer,\n\t`aging_p90_seconds` integer,\n\t`fleet_active_count` integer,\n\t`fleet_exits_to_done` integer,\n\t`fleet_cycle_p50_seconds` integer,\n\t`fleet_cycle_p90_seconds` integer,\n\t`interactive_active_count` integer,\n\t`interactive_exits_to_done` integer,\n\t`interactive_cycle_p50_seconds` integer,\n\t`interactive_cycle_p90_seconds` integer,\n\t`stalled_count` integer,\n\t`estimated_ticket_count` integer,\n\t`open_pr_count` integer,\n\t`open_pr_draft_count` integer,\n\t`prs_merged` integer,\n\t`pr_cycle_p50_seconds` integer,\n\t`pr_cycle_p90_seconds` integer,\n\t`pr_age_p50_seconds` integer,\n\t`pr_age_p90_seconds` integer,\n\t`computed_at` integer NOT NULL,\n\tPRIMARY KEY(`repo_id`, `day`)\n);\n--> statement-breakpoint\nCREATE INDEX `idx_flow_daily_day` ON `flow_daily` (`day`);",
+    "0040_ctc1885_workflow_state_name_backfill":
+      "-- CTC-1885 — re-stamp cached workflow-state NAMES from the authoritative workflow_states row, by\n-- stable state id.\n--\n-- ⭐ Deliberately a pure DATA migration in the SHARED bundle (the 0014/0031/0037 pattern): the DO\n-- and every host / OPFS replica apply the same MIRROR_MIGRATIONS through the same runner, so each\n-- store repairs its OWN rows locally. That converges the already-stale corpus WITHOUT emitting a\n-- change_log delta per historical row (migrations bypass appendChange), so the 200k-row / 7-day ring\n-- buffer is not flooded by the very backlog this repairs, and a replica that was OFFLINE at deploy\n-- time heals itself the moment it next opens and applies the bundle.\n--\n-- The defect: `issues.state` is denormalized at issue ingest and `team_workflow_mapping.\n-- linear_state_name` at mapping projection, while `workflow_states.name` is written by the\n-- workflow-state sweep. A Linear rename (Triage -> Intake) updated only the latter, so issues kept\n-- answering the OLD name (/api/v1/issues returns the column verbatim; the board keys columns by it)\n-- and the mapping kept displaying it. Runtime cascade (this ticket's reconcile change) covers FUTURE\n-- renames; THIS migration repairs every row already stale at upgrade time, including on stores the\n-- runtime never gets to replay.\n--\n-- Matching is by STABLE ID, never by the mutable old string (the table's own header: the name is a\n-- display snapshot, never a lookup key — a same-named row under a different state id must not move):\n--   • issues: `issues.state_id` -> `workflow_states.id`. The state id is globally unique (Linear\n--     UUID), which IS the team scoping — an issue's state belongs to exactly one team's workflow.\n--   • team_workflow_mapping: `linear_state_id` AND `team_id` both resolve. The mapping's team fence\n--     is kept because a Linear-to-Linear import can re-mint ids per team (CTC-403).\n-- Both updates are guarded by `ws.name IS NOT <cached>` so already-converged rows are untouched and\n-- a replay (execReplaySafe re-runs a statement after a crash between success and tag-record) is a\n-- no-op. `IS` / `IS NOT` keep every comparison NULL-safe.\n--\n-- ⛔ NO timestamps, revisions, or tombstones are rewritten: `updated_at`, `workflow_rev`, and\n-- `removed_at` survive exactly as stored. A state rename is provider-owned state metadata, not an\n-- issue mutation and not a tenant mapping decision; advancing those fields would corrupt freshness,\n-- board ranking, last-write-wins ordering, and the host workflow-rev receipt. Only the NAME fields\n-- converge. (Tombstoned mapping rows converge too — a dead row's display snapshot changing is\n-- unobservable and emits nothing; the runtime cascade, which DOES emit deltas, stays live-only.)\nUPDATE `issues`\n   SET `state` = (SELECT `ws`.`name` FROM `workflow_states` `ws` WHERE `ws`.`id` = `issues`.`state_id`)\n WHERE EXISTS (\n       SELECT 1 FROM `workflow_states` `ws`\n        WHERE `ws`.`id` = `issues`.`state_id`\n          AND `ws`.`name` IS NOT NULL\n          AND `ws`.`name` IS NOT `issues`.`state`);\n--> statement-breakpoint\nUPDATE `team_workflow_mapping`\n   SET `linear_state_name` = (SELECT `ws`.`name`\n                                FROM `workflow_states` `ws`\n                               WHERE `ws`.`id` = `team_workflow_mapping`.`linear_state_id`\n                                 AND `ws`.`team_id` = `team_workflow_mapping`.`team_id`)\n WHERE EXISTS (\n       SELECT 1 FROM `workflow_states` `ws`\n        WHERE `ws`.`id` = `team_workflow_mapping`.`linear_state_id`\n          AND `ws`.`team_id` = `team_workflow_mapping`.`team_id`\n          AND `ws`.`name` IS NOT NULL\n          AND `ws`.`name` IS NOT `team_workflow_mapping`.`linear_state_name`);\n",
   },
 } as const;

package/src/mirror.ts

@@ -1484,3 +1484,61 @@ export const fleet_health_sends = sqliteTable(
   },
   (t) => [primaryKey({ columns: [t.host_id, t.status, t.status_changed_at_ms] })],
 );
+
+/**
+ * CTC-1385 — one FLOW SNAPSHOT per (repo_id, day). A derived rollup, recomputed from `issue_history` /
+ * `pull_requests` each reconcile pass and overwritten in place — never a hand-edited or externally
+ * written row.
+ *
+ * ⛔ HUB-READ-ONLY — deliberately in NEITHER `feedEntityTables` NOR `nonFeedEntityTables` (index.ts),
+ * the same posture as `pull_sweeps` / `pr_ancillary_backfill`. It is recomputable from tables the feed
+ * already carries, so broadcasting it account-wide would put a recomputable aggregate on every host
+ * replica and every browser OPFS DB for no reader.
+ *
+ * ⚠️ NO `tenant_id` — the DO IS the tenant (this file's header). The ticket phrases the key as
+ * (tenant, repository, day); inside a tenant's own DO that is exactly (repo_id, day). Nothing dropped.
+ *
+ * ⭐ EVERY DURATION IS SECONDS, and every column that holds one says so in its name (`*_seconds`). The
+ * ticket's adaptive-rendering rule (minutes as the fleet improves) lives in the client; the store never
+ * picks a unit.
+ */
+export const flow_daily = sqliteTable(
+  "flow_daily",
+  {
+    repo_id: text("repo_id").notNull(),
+    /** UTC `YYYY-MM-DD` — `utcDayString`, never a raw timestamp (write-budget.ts's boundary rule). */
+    day: text("day").notNull(),
+    active_count: integer("active_count").notNull(),
+    entries: integer("entries").notNull(),
+    exits_to_done: integer("exits_to_done").notNull(),
+    exits_to_canceled: integer("exits_to_canceled").notNull(),
+    /** JSON: `{ "<stateKey>": count }` over the active-board tickets currently in that state. */
+    stage_counts: text("stage_counts"),
+    aging_p50_seconds: integer("aging_p50_seconds"),
+    aging_p90_seconds: integer("aging_p90_seconds"),
+    // The same figures, split by delivery mode (CTC-1385's delivery-mode rule).
+    fleet_active_count: integer("fleet_active_count"),
+    fleet_exits_to_done: integer("fleet_exits_to_done"),
+    fleet_cycle_p50_seconds: integer("fleet_cycle_p50_seconds"),
+    fleet_cycle_p90_seconds: integer("fleet_cycle_p90_seconds"),
+    interactive_active_count: integer("interactive_active_count"),
+    interactive_exits_to_done: integer("interactive_exits_to_done"),
+    interactive_cycle_p50_seconds: integer("interactive_cycle_p50_seconds"),
+    interactive_cycle_p90_seconds: integer("interactive_cycle_p90_seconds"),
+    stalled_count: integer("stalled_count"),
+    estimated_ticket_count: integer("estimated_ticket_count"),
+    // The GitHub pull-request addendum (added 2026-09-01) — same repo/day grain, no new ingestion:
+    // sourced from the already-mirrored `pull_requests` table.
+    open_pr_count: integer("open_pr_count"),
+    open_pr_draft_count: integer("open_pr_draft_count"),
+    prs_merged: integer("prs_merged"),
+    pr_cycle_p50_seconds: integer("pr_cycle_p50_seconds"),
+    pr_cycle_p90_seconds: integer("pr_cycle_p90_seconds"),
+    pr_age_p50_seconds: integer("pr_age_p50_seconds"),
+    pr_age_p90_seconds: integer("pr_age_p90_seconds"),
+    computed_at: integer("computed_at").notNull(), // ms epoch — when this pass wrote the row
+  },
+  // The index lives in the Drizzle SSOT ONLY (NOT schema.sql) — migrate.ts's generated CREATE INDEX is
+  // replay-safe; schema.sql would break the adoption test (the same rule idx_issues_sort_order states).
+  (t) => [primaryKey({ columns: [t.repo_id, t.day] }), index("idx_flow_daily_day").on(t.day)],
+);

package/src/telemetry/flow-transition-point.ts

@@ -0,0 +1,96 @@
+// flow-transition-point.ts — CTC-1385. The `flow.transition` / `flow.pr-transition` telemetry family's
+// closed vocabulary and shared TelemetryPoint builders, modeled line-for-line on
+// ./phase-lifecycle-point.ts: a closed enum, a throwing guard (never a falsy sentinel — the same
+// posture assertEmittable takes for the event NAME), and one builder per point kind.
+//
+// ⚠️ EVERY DIMENSION IS AN IDENTIFIER OR AN ENUM — no ticket titles, no PR titles, no branch names, no
+// tenant prose (ADR-0048 binding condition 1). `ticket`/`repository` are identifiers; every other field
+// is a closed vocabulary member or a number.
+
+import type { TelemetryPoint } from "./point.js";
+import { teamFromTicket } from "./phase-lifecycle-point.js";
+
+/**
+ * The PR-transition kind vocabulary. `queued` is a MEMBER even though nothing emits it yet (D18 — no
+ * mirrored table carries a "PR entered the merge queue at T" timestamp today); documented here so the
+ * follow-up that adds queue-entry ingestion needs no vocabulary change.
+ */
+export const PR_TRANSITION_KINDS = ["opened", "ready", "queued", "merged", "closed"] as const;
+export type PrTransitionKind = (typeof PR_TRANSITION_KINDS)[number];
+
+function assertKnownPrTransition(kind: string): asserts kind is PrTransitionKind {
+  if (!(PR_TRANSITION_KINDS as readonly string[]).includes(kind)) {
+    throw new Error(
+      `flow.pr-transition refuses kind "${kind}": not one of ${PR_TRANSITION_KINDS.join("|")} ` +
+        `(packages/schema/src/telemetry/flow-transition-point.ts is the one closed vocabulary)`,
+    );
+  }
+}
+
+export interface FlowTransitionFields {
+  ticket: string;
+  repository: string;
+  fromStage: string;
+  toStage: string;
+  secondsInStage: number;
+  deliveryMode: "fleet" | "interactive";
+  estimate: number | null;
+}
+
+/** Build one `flow.transition` TelemetryPoint — a ticket crossing a flow-board stage boundary. */
+export function buildFlowTransitionPoint(fields: FlowTransitionFields): TelemetryPoint {
+  const detailParts = [
+    `ticket=${fields.ticket}`,
+    `repository=${fields.repository}`,
+    `from_stage=${fields.fromStage}`,
+    `to_stage=${fields.toStage}`,
+    `seconds_in_stage=${fields.secondsInStage}`,
+    `delivery_mode=${fields.deliveryMode}`,
+    ...(fields.estimate != null ? [`estimate=${fields.estimate}`] : []),
+  ];
+  return {
+    name: "flow.transition",
+    service: "catalyst-cloud.mirror",
+    outcome: "ok",
+    detail: detailParts.join(" "),
+    traceId: `${fields.ticket}:${fields.fromStage}:${fields.toStage}`,
+    durationMs: null,
+    count: 1,
+    projectId: null,
+    repo: fields.repository,
+    team: teamFromTicket(fields.ticket),
+  };
+}
+
+export interface PrTransitionFields {
+  repository: string;
+  prNumber: number;
+  kind: PrTransitionKind;
+  secondsSincePrevious: number;
+  deliveryMode: "fleet" | "interactive";
+}
+
+/** Build one `flow.pr-transition` TelemetryPoint. Throws (never a falsy sentinel) on an unrecognized
+ *  `kind` — the same posture `assertKnownStatus` takes in phase-lifecycle-point.ts. */
+export function buildPrTransitionPoint(fields: PrTransitionFields): TelemetryPoint {
+  assertKnownPrTransition(fields.kind);
+  const detailParts = [
+    `repository=${fields.repository}`,
+    `pr_number=${fields.prNumber}`,
+    `kind=${fields.kind}`,
+    `seconds_since_previous=${fields.secondsSincePrevious}`,
+    `delivery_mode=${fields.deliveryMode}`,
+  ];
+  return {
+    name: "flow.pr-transition",
+    service: "catalyst-cloud.mirror",
+    outcome: "ok",
+    detail: detailParts.join(" "),
+    traceId: `${fields.repository}:${fields.prNumber}:${fields.kind}`,
+    durationMs: null,
+    count: 1,
+    projectId: null,
+    repo: fields.repository,
+    team: null,
+  };
+}

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

@@ -45,6 +45,10 @@ export interface PhaseLifecycleFields {
   artifactKey?: string;
   durationMs?: number;
   reason?: string;
+  /** CTC-1778 — one remediation round may carry several descriptive classes. They remain labels,
+   * not additional lifecycle points or admission keys. */
+  remediateClasses?: readonly string[];
+  remediationRound?: 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. */
@@ -98,6 +102,12 @@ export const PHASE_LIFECYCLE_DETAIL_ORDER = [
   "pr_number",
   "artifact_key",
   "reason",
+  // CTC-1778 — the bundled-remediation tokens, registered in the exact order
+  // `buildPhaseLifecyclePoint` emits them (remediation_round, then remediate_classes). Rule (2)
+  // above applies to both: unregistered, they are indistinguishable from a ladder digest pair and
+  // get swallowed into `reason`'s value.
+  "remediation_round",
+  "remediate_classes",
   // Reserved — CTC-1771 Phase 5.
   "failure_class",
   "round",
@@ -163,6 +173,12 @@ export function buildPhaseLifecyclePoint(fields: PhaseLifecycleFields): Telemetr
     ...(fields.prNumber !== undefined ? [`pr_number=${fields.prNumber}`] : []),
     ...(fields.artifactKey !== undefined ? [`artifact_key=${fields.artifactKey}`] : []),
     ...(fields.reason !== undefined ? [`reason=${fields.reason}`] : []),
+    ...(fields.remediationRound !== undefined
+      ? [`remediation_round=${fields.remediationRound}`]
+      : []),
+    ...(fields.remediateClasses !== undefined && fields.remediateClasses.length > 0
+      ? [`remediate_classes=${[...new Set(fields.remediateClasses)].sort().join(",")}`]
+      : []),
   ];
   return {
     name: "phase.lifecycle",