@catalyst-cloud/schema 0.1.40 → 0.1.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/schema",
-  "version": "0.1.40",
+  "version": "0.1.41",
   "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/current-state.ts

@@ -0,0 +1,31 @@
+// current-state.ts — CTC-355. The THIRD admission gate, and the reason it did not exist.
+//
+// `classifyEventType` sorts every declared name into exactly one of three disjoint buckets, and until
+// now only two of them had a door: `appendEventWithOutbox` (apps/mirror/src/do/event-backbone.ts)
+// admits `durable`, `assertEmittable` (./telemetry/point.ts) admits `telemetry`, and `current-state`
+// was admitted by NOTHING — declared, unproduced, unconsumed, the "declared but unfed lane" shape
+// ADR-0029 names. This is that door: the fleet-liveness heartbeat ingest lane
+// (apps/mirror/src/coordination/heartbeat-validate.ts) calls this to refuse anything that is not a
+// heartbeat-shaped current-state name, symmetrically with how the durable backbone and the telemetry
+// sink already refuse everything that is NOT theirs.
+//
+// Three disjoint buckets, three gates, one per bucket — the symmetry is the point. The other two gates
+// stay exactly as they are: a heartbeat is still refused by the durable backbone and by the telemetry
+// sink, which is correct — updating mutable NOW is this gate's job alone.
+
+import { classifyEventType } from "./registry.js";
+
+/**
+ * Refuse to admit a name that is not `classifyEventType(name) === "current-state"`. Throws — never
+ * returns a falsy sentinel (AGENTS.md: a helper that degrades to "fine" hides the defect, and a caller
+ * cannot degrade a refusal into a silent skip when the refusal is an exception).
+ */
+export function assertCurrentState(name: string): void {
+  const klass = classifyEventType(name);
+  if (klass !== "current-state") {
+    throw new Error(
+      `event type ${JSON.stringify(name)} is classified "${klass}" — only current-state (heartbeat) ` +
+        `names may update mutable NOW. See packages/schema/src/events/registry.ts.`,
+    );
+  }
+}

package/src/events/index.ts

@@ -6,3 +6,7 @@ export * from "./types.js";
 export * from "./type-grammar.js";
 export * from "./registry.js";
 export * from "./retention.js";
+// CTC-355 — the THIRD admission gate: durable/current-state/telemetry are the three disjoint buckets
+// classifyEventType partitions the vocabulary into; the other two already had a door
+// (appendEventWithOutbox, ../telemetry/point.ts's assertEmittable). This is current-state's.
+export * from "./current-state.js";

package/src/events/registry.ts

@@ -185,12 +185,14 @@ export const durableEventTypes = {
     wakes: { consumerClass: "dispatcher" },
   },
   "fleet.health.degraded": {
-    rationale: "A fleet-wide health boundary crossing — paired with fleet.health.recovered.",
+    rationale:
+      "A fleet-wide health boundary crossing — paired with fleet.health.recovered. ⭐ CTC-355 is its producer: the per-tenant absence-based liveness evaluator (apps/mirror/src/do/fleet-liveness-evaluate.ts's evaluateLiveness, invoked from MirrorDO.alarm()) derives it from monitor.heartbeat ABSENCE past a per-host grace window — exactly the derivation currentStateEventTypes' boundaryEvents list above was typed against. ⚠️ `ingestVerb` below is unchanged and now under-describes this name: the producer is an in-DO evaluator, not an ingest verb. The field is descriptive metadata with no runtime consumer (verified: nothing outside this registry file reads it) — widening its closed union for one unread field would touch ~90 spec literals.",
     ingestVerb: "coordination.publish",
     wakes: { consumerClass: "host-channel" },
   },
   "fleet.health.recovered": {
-    rationale: "The paired boundary-crossing fact to fleet.health.degraded.",
+    rationale:
+      "The paired boundary-crossing fact to fleet.health.degraded. Same producer (CTC-355's liveness evaluator) — fired when a degraded host's heartbeat resumes inside a later evaluation pass.",
     ingestVerb: "coordination.publish",
     wakes: false,
   },
@@ -1910,6 +1912,16 @@ export const telemetryEventTypes = {
   "account.ratelimit.sampled": {
     reason: "A periodic provider rate-limit budget reading — a gauge, not a state transition.",
   },
+  "catalyst.fleet.liveness.evaluated": {
+    reason:
+      "CTC-355 — one point per per-tenant liveness evaluation pass, carrying the live/degraded/unknown counts. Gauge-shaped: the rollup is the signal, no individual pass has identity. The BOUNDARY crossings are durable (fleet.health.degraded/recovered below); this is the pass itself.",
+    sampling: { kind: "counted" },
+  },
+  "catalyst.fleet.anomaly.detected": {
+    reason:
+      "CTC-355 — one point per NEWLY-OPENED fleet anomaly (rate_spike/flatline), never per re-detection of an already-open one. The anomaly ROW (fleet_anomalies) is the durable record of what is wrong now; this is the detection event.",
+    sampling: { kind: "counted" },
+  },
   "account.ratelimit.unsampled": {
     reason:
       "The raw (pre-sampling) rate-limit reading behind account.ratelimit.sampled — same gauge family.",

package/src/index.ts

@@ -50,6 +50,10 @@ import {
   deployment_statuses,
   pr_review_threads,
   check_suites,
+  fleet_host_liveness,
+  fleet_anomalies,
+  fleet_activity_rate,
+  fleet_health_sends,
 } from "./mirror.js";
 
 export * from "./mirror.js";
@@ -152,6 +156,17 @@ export const mirrorSchema = {
   // CTC-667 item 4: the check SUITE's own rollup — the highest-volume signal in CTL's census and the
   // one every phase agent's CI wait blocks on.
   check_suites,
+  // CTC-355: per-host fleet liveness (mutable NOW) + open anomaly signals. Real tables the DO creates
+  // (migrations must produce them) and change-feed entities (see feedEntityTables below) — the
+  // dashboard is a live consumer of both.
+  fleet_host_liveness,
+  fleet_anomalies,
+  // CTC-355: the rolling activity-rate bucket table (anomaly baseline source) and the fleet-health
+  // push re-fire gate. Same posture as fleet_activity_pruned / pull_sweeps — real tables the DO
+  // creates, deliberately absent from feedEntityTables/nonFeedEntityTables (pure bookkeeping no
+  // consumer should ever see over the feed).
+  fleet_activity_rate,
+  fleet_health_sends,
 } as const;
 
 /**
@@ -225,6 +240,12 @@ export const feedEntityTables = {
   // CTC-667 item 4: GitHub's OWN check-suite rollup. ⛔ The row is contractual; a derivation from
   // `check_runs` is NOT — see the table's own header for the two reasons it cannot agree with GitHub.
   check_suites,
+  // CTC-355: per-host fleet liveness + open anomaly signals. On this plane deliberately — the
+  // dashboard's fleet-liveness panel is a legitimate account-wide reader, same posture as
+  // fleet_activity directly above (both are BROWSER_ONLY at the changefeed layer — see
+  // apps/mirror/src/do/changefeed.ts's BROWSER_ONLY_ENTITIES).
+  fleet_host_liveness,
+  fleet_anomalies,
 } as const;
 
 /**

package/src/migrations.generated.ts

@@ -263,6 +263,13 @@ export const MIRROR_MIGRATIONS = {
         tag: "0035_tricky_swarm",
         breakpoints: true,
       },
+      {
+        idx: 36,
+        version: "6",
+        when: 1788333712249,
+        tag: "0036_watery_hercules",
+        breakpoints: true,
+      },
     ],
   },
   migrations: {
@@ -335,5 +342,7 @@ export const MIRROR_MIGRATIONS = {
       "CREATE INDEX `idx_processed_events_source_received` ON `processed_events` (`source`,`received_at`);",
     "0035_tricky_swarm":
       "ALTER TABLE `agent_activities` ADD `action` text;--> statement-breakpoint\nALTER TABLE `agent_activities` ADD `parameter` text;--> statement-breakpoint\nALTER TABLE `agent_activities` ADD `result` text;--> statement-breakpoint\nUPDATE agent_activities\n   SET action    = json_extract(raw, '$.content.action'),\n       parameter = json_extract(raw, '$.content.parameter'),\n       result    = json_extract(raw, '$.content.result')\n WHERE raw IS NOT NULL\n   AND json_valid(raw)\n   AND json_extract(raw, '$.content.type') = 'action';\n",
+    "0036_watery_hercules":
+      "CREATE TABLE `fleet_activity_rate` (\n\t`host_id` text NOT NULL,\n\t`ticket` text NOT NULL,\n\t`bucket_start_ms` integer NOT NULL,\n\t`events` integer NOT NULL,\n\tPRIMARY KEY(`host_id`, `ticket`, `bucket_start_ms`)\n);\n--> statement-breakpoint\nCREATE TABLE `fleet_anomalies` (\n\t`kind` text NOT NULL,\n\t`host_id` text NOT NULL,\n\t`ticket` text NOT NULL,\n\t`detected_at_ms` integer NOT NULL,\n\t`observed` integer NOT NULL,\n\t`baseline` integer NOT NULL,\n\t`detail` text,\n\t`updated_at` integer NOT NULL,\n\tPRIMARY KEY(`kind`, `host_id`, `ticket`)\n);\n--> statement-breakpoint\nCREATE TABLE `fleet_health_sends` (\n\t`host_id` text NOT NULL,\n\t`status` text NOT NULL,\n\t`status_changed_at_ms` integer NOT NULL,\n\t`sent_at_ms` integer NOT NULL,\n\t`delivered` integer NOT NULL,\n\t`failed` integer NOT NULL,\n\tPRIMARY KEY(`host_id`, `status`, `status_changed_at_ms`)\n);\n--> statement-breakpoint\nCREATE TABLE `fleet_host_liveness` (\n\t`host_id` text PRIMARY KEY NOT NULL,\n\t`status` text NOT NULL,\n\t`reason` text,\n\t`last_heartbeat_ms` integer,\n\t`last_activity_ms` integer,\n\t`last_seen_ms` integer,\n\t`period_ms` integer,\n\t`grace_ms` integer,\n\t`agent_version` text,\n\t`status_changed_at_ms` integer,\n\t`updated_at` integer NOT NULL\n);\n",
   },
 } as const;

package/src/mirror.ts

@@ -1366,3 +1366,109 @@ export const push_subscriptions = sqliteTable(
   // PK), keyed off issues.assignee_id — the same shape idx_workflow_states_team indexes on team_id.
   (t) => [index("idx_push_subscriptions_member").on(t.member_id)],
 );
+
+/**
+ * CTC-355 — MUTABLE NOW for one fleet host's liveness. One row per host_id.
+ *
+ * ⛔ THIS IS NOT `fleet_activity`, AND THE DIFFERENCE IS THE WHOLE POINT. `fleet_activity` advances
+ * only when a host does TICKET WORK, so an alive-but-idle host freezes its watermark — the exact trap
+ * `apps/web/src/lib/sync-health.ts` documents for `last_ingest_ms` (CTC-144 added a heartbeat
+ * precisely because of it). Liveness is asserted by a HEARTBEAT and by nothing else.
+ *
+ * ⚠️ `last_activity_ms` folds in ONE-WAY. Publishing a coordination event is positive proof of life,
+ * so it advances `last_seen_ms`; its ABSENCE proves nothing and never drives a verdict.
+ *
+ * ⭐ `status` is TRI-STATE and `unknown` is load-bearing. A host that has never heartbeated is
+ * `unknown` regardless of how much activity it has produced — because on the day this shipped NO host
+ * emitted `monitor.heartbeat`, and a binary model would have marked the entire fleet degraded and
+ * pushed a notification for every one of them.
+ */
+export const fleet_host_liveness = sqliteTable("fleet_host_liveness", {
+  host_id: text("host_id").primaryKey(),
+  /** 'live' | 'degraded' | 'unknown' — see FleetLivenessStatus (do/fleet-liveness-evaluate.ts). */
+  status: text("status").notNull(),
+  /** Why, when status is 'unknown': 'no_heartbeat_lane' | 'clock_skew'. Null otherwise. */
+  reason: text("reason"),
+  /** Last accepted heartbeat receipt (the DO's OWN clock). NULL ⇒ never heartbeated ⇒ unknown. */
+  last_heartbeat_ms: integer("last_heartbeat_ms"),
+  /** Last accepted coordination-event receipt for this host (DO clock). Positive proof only. */
+  last_activity_ms: integer("last_activity_ms"),
+  /** max(last_heartbeat_ms, last_activity_ms) — the value the grace window is measured against. */
+  last_seen_ms: integer("last_seen_ms"),
+  /** The cadence the host DECLARED, clamped on ingest. Drives the per-host grace window. */
+  period_ms: integer("period_ms"),
+  /** The window in force for this host, materialized so the UI reports the SAME number the evaluator
+   *  used rather than re-deriving one that could disagree. */
+  grace_ms: integer("grace_ms"),
+  /** The host's self-reported agent/SDK version, verbatim. Display only. */
+  agent_version: text("agent_version"),
+  /** When `status` last CHANGED — not when the row was last touched. The two differ on every
+   *  heartbeat of a healthy host, and the UI needs the former ("degraded for 20 minutes"). */
+  status_changed_at_ms: integer("status_changed_at_ms"),
+  updated_at: integer("updated_at").notNull(), // upsertRow's last-write-wins guard column
+});
+
+/**
+ * CTC-355 — an open anomaly signal. One row per (kind, host_id, ticket); DELETED when the condition
+ * clears, so this table is "what is wrong now", never a history.
+ *
+ * ⚠️ TICKET IS `''` FOR TENANT-SCOPE KINDS (flatline), never NULL — it is a PK column, and SQLite
+ * treats NULLs as distinct in a UNIQUE index, so a nullable PK member would let the same flatline
+ * insert unboundedly many times.
+ */
+export const fleet_anomalies = sqliteTable(
+  "fleet_anomalies",
+  {
+    kind: text("kind").notNull(), // 'rate_spike' | 'flatline'
+    host_id: text("host_id").notNull(), // '' for tenant-scope kinds
+    ticket: text("ticket").notNull(), // '' for tenant-scope kinds
+    detected_at_ms: integer("detected_at_ms").notNull(),
+    /** The measured value and the baseline it was judged against — so the UI can SHOW the arithmetic
+     *  instead of asserting a verdict the reader has to trust. */
+    observed: integer("observed").notNull(),
+    baseline: integer("baseline").notNull(),
+    detail: text("detail"),
+    updated_at: integer("updated_at").notNull(),
+  },
+  (t) => [primaryKey({ columns: [t.kind, t.host_id, t.ticket] })],
+);
+
+/**
+ * CTC-355 — bounded rolling activity counters, the ONLY baseline source for anomaly detection. 15-min
+ * buckets, 24h retention: ≤96 rows per active (host, ticket), and a pair stops producing rows the
+ * moment it stops publishing. Bookkeeping — on NEITHER entity list, like fleet_activity_pruned.
+ *
+ * ⛔ NOT Analytics Engine. AE applies query-time sampling, and a sampled-away point is
+ * indistinguishable from an absent one — which for an absence-based detector is a FALSE ALARM, not a
+ * rounding error. This table is how it is dodged rather than compensated for.
+ */
+export const fleet_activity_rate = sqliteTable(
+  "fleet_activity_rate",
+  {
+    host_id: text("host_id").notNull(),
+    ticket: text("ticket").notNull(),
+    bucket_start_ms: integer("bucket_start_ms").notNull(),
+    events: integer("events").notNull(),
+  },
+  (t) => [primaryKey({ columns: [t.host_id, t.ticket, t.bucket_start_ms] })],
+);
+
+/**
+ * CTC-355 — the durable "has anybody been told?" record for fleet-health notifications, modelled on
+ * the CTC-764 ask-push re-fire gate. Keyed by the transition, so a re-evaluation that re-derives the
+ * same verdict cannot re-notify, and a genuine flap (degraded → live → degraded) can.
+ */
+export const fleet_health_sends = sqliteTable(
+  "fleet_health_sends",
+  {
+    host_id: text("host_id").notNull(),
+    /** The status transitioned INTO. */
+    status: text("status").notNull(),
+    /** The status_changed_at_ms this send was for — what makes a flap re-notifiable. */
+    status_changed_at_ms: integer("status_changed_at_ms").notNull(),
+    sent_at_ms: integer("sent_at_ms").notNull(),
+    delivered: integer("delivered").notNull(), // count of endpoints that accepted
+    failed: integer("failed").notNull(),
+  },
+  (t) => [primaryKey({ columns: [t.host_id, t.status, t.status_changed_at_ms] })],
+);