@catalyst-cloud/schema 0.1.43 → 0.1.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/schema",
-  "version": "0.1.43",
+  "version": "0.1.45",
   "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.",
@@ -1141,6 +1162,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 +1190,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 +1253,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.",
@@ -1861,6 +1917,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.",
@@ -1905,8 +1968,12 @@ export interface TelemetryEventSpec {
  * telemetry-shaped in the plan's measurement) — ticks, gauges, process samples, read traces,
  * forwarding lag, "would-*" dry-run counterfactuals, and retry-storm noise that collapses to a single
  * durable boundary fact elsewhere in this registry (e.g. linear.write.proxy.failed's 140k+ lines/mo
- * collapses to the ONE durable linear.label.retry-exhausted terminal fact). CTC-962 (ADR-0048) added
- * 5 mirror-ingress names on top of those 70 (measured total: 75) — see the `mirror.*` entries below.
+ * collapses to the ONE durable linear.label.retry-exhausted terminal fact). CTC-962 (ADR-0048) started
+ * the `mirror.*` family; it now carries 7 names (CTC-289's mirror.webhook.out-of-scope and CTC-1510's
+ * mirror.dispatch-queue.derive-refused both rode the same sink after CTC-962 landed) — see those
+ * entries below. ⚠️ The "70 fleet/orchestrator-origin types" figure above is this comment's OWN prior
+ * measurement, already stale against the live count (Object.keys(telemetryEventTypes).length) by the
+ * time CTC-1510 read it — re-measure before citing it, don't re-derive it from this text.
  */
 export const telemetryEventTypes = {
   "account.ratelimit.sampled": {
@@ -2075,6 +2142,11 @@ export const telemetryEventTypes = {
       "CTC-289 — a verified, tenant-routable delivery whose repo/team is not a provisioned `projects` row. Carries the account, the scope key and the fence mode: the scope key is the entire diagnostic value (it answers 'why is repo Y in my mirror' and 'why is repo Y missing'), and the mode distinguishes an observed would-drop from an actual drop. Unsampled while the fence rolls out — the `observe` soak that gates enforcement reads exactly this signal, and a sampled soak cannot support a data-discarding flip. Revisit the class once enforce has been stable.",
     sampling: { kind: "always" },
   },
+  "mirror.dispatch-queue.derive-refused": {
+    reason:
+      "CTC-1510 — one point per fail-closed `deriveDispatchQueue` refusal (an unresolved, missing or ambiguous team_workflow_mapping), carrying the team and WHICH resolution failed. Not durable: the refusal is a description of a configuration state, not a state transition, and it repeats every pass until the mapping is fixed — the durable fact is the mapping row itself. `always`-sampled: rare by design (a healthy tenant never emits it) and it is the ONLY machine-readable signal that a team's queue stopped advancing on purpose, which is exactly what a sampled-away point would hide. Repeats inside the DO's announce window are folded into `count`, never dropped.",
+    sampling: { kind: "always" },
+  },
   "orphans.reap-requested": {
     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.",