@catalyst-cloud/schema 0.1.18 → 0.1.20

package/src/events/retention.ts

@@ -0,0 +1,198 @@
+// retention.ts — CTC-936 phase 4 (ADR-0039 proposal phase-1 items 4-5). The retention/deletion
+// policy and the versioned Analytics Engine projection layout, as machine-readable constants a
+// future R2/AE binding (phase 2 of the vertical slice, out of THIS ticket's scope) is typed against
+// rather than a prose description that can silently drift from the code.
+
+/**
+ * The hot window kept in DO SQLite before an event is eligible for pruning — the proposal's own
+ * words: "initially seven days is a reasonable operating assumption."
+ */
+export const EVENT_HOT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** The coordinates needed to compose one event's R2 archive key. `occurredAt` drives the
+ *  yyyy/mm/dd partition (UTC, so archival never depends on the writer's local clock). */
+export interface EventArchiveCoords {
+  tenantId: string;
+  sequence: number;
+  eventId: string;
+  /** ISO-8601. Uses the event's own `occurredAt`/`recordedAt`, not archival wall-clock time — the
+   *  proposal's key template partitions by when the fact happened, not when it was archived. */
+  occurredAt: string;
+}
+
+/** `sequence` is zero-padded to this width so R2's own lexicographic LIST order agrees with
+ *  numeric sequence order — the same reason `apps/mirror/src/artifacts/key.ts`'s `artifactKey`
+ *  zero-pads its `nonce`. 20 digits comfortably exceeds `Number.MAX_SAFE_INTEGER`'s 16 digits. */
+const SEQUENCE_PAD_WIDTH = 20;
+
+// `eventId` is PRODUCER-supplied (types.ts) and is interpolated into the R2 key, so it is the one
+// caller-supplied segment validated here — modelled on apps/mirror/src/artifacts/key.ts's NAME_RE,
+// "the same key-injection shape, a different partition." Allowlist rather than a `/`-only denylist
+// so any other path-shaped character (`\`, whitespace, control chars) is caught too.
+const EVENT_ID_RE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,238}[A-Za-z0-9])?$/;
+
+// Full ISO-8601 UTC-or-offset instant shape, anchored so surrounding whitespace and bare-year /
+// bare-number forms (both of which `new Date()` tolerates) are rejected before they ever reach the
+// coercion below.
+const ISO_8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+
+// `tenantId` is the one segment BOTH exported key-shaping functions below take, and it defines the
+// tenant-isolation boundary a scoped teardown (eventArchiveTenantPrefix) relies on — so it is
+// validated once, here, rather than duplicated in each caller.
+function assertValidTenantId(caller: string, tenantId: string): void {
+  if (typeof tenantId !== "string" || tenantId.length === 0 || tenantId.includes("/")) {
+    throw new Error(`${caller}: tenantId ${JSON.stringify(tenantId)} is not valid`);
+  }
+}
+
+/**
+ * Build the R2 archive key for one event: `tenant/yyyy/mm/dd/<paddedSequence>-<eventId>.json` — the
+ * proposal's own template, verbatim, with the zero-padding decision stated (see SEQUENCE_PAD_WIDTH).
+ */
+export function eventArchiveKey(coords: EventArchiveCoords): string {
+  const { tenantId, sequence, eventId, occurredAt } = coords;
+  assertValidTenantId("eventArchiveKey", tenantId);
+  // Throws with the reason named — never returns a falsy/plausible-looking sentinel (AGENTS.md;
+  // type-grammar.ts's assertValidEventType follows the same posture). `occurredAt` is OPTIONAL on
+  // CatalystEvent, so a malformed value reaching here on the normal write path must fail loudly
+  // rather than silently misfile the only durable copy into an unqueryable `0NaN/NaN/NaN` — or, for
+  // `null`, a plausible-looking but wrong `1970/01/01` — partition. Requiring the full ISO_8601_RE
+  // shape (rather than accepting whatever `new Date()` merely tolerates) also rejects a bare year
+  // ("2026"), a bare epoch-ms-looking number-as-string ("0"), and leading/trailing whitespace before
+  // they ever reach the round-trip check below.
+  if (typeof occurredAt !== "string" || !ISO_8601_RE.test(occurredAt)) {
+    throw new Error(
+      `eventArchiveKey: occurredAt ${JSON.stringify(occurredAt)} is not a valid date`,
+    );
+  }
+  const occurredAtMs = new Date(occurredAt).getTime();
+  if (Number.isNaN(occurredAtMs)) {
+    throw new Error(
+      `eventArchiveKey: occurredAt ${JSON.stringify(occurredAt)} is not a valid date`,
+    );
+  }
+  // A round-trip check: `new Date()` silently rolls an out-of-range calendar date forward (e.g.
+  // "2026-02-30" becomes March 2), which the regex shape check above cannot catch since the string
+  // is well-formed. Re-deriving the yyyy-mm-dd prefix from the parsed Date and requiring it to match
+  // the input's own date prefix rejects that rollover instead of misfiling into a wrong partition.
+  const roundTripDatePrefix = occurredAt.slice(0, 10);
+  // Codex P2 (PR #1250): derive the parsed prefix in the TIMESTAMP'S OWN offset, not UTC — a
+  // valid instant like 2026-08-24T23:30:00-02:00 is already Aug 25 in UTC, so a UTC comparison
+  // rejects a well-formed date the regex deliberately accepts. The rollover check still fires:
+  // an out-of-range date (2026-02-30) rolls forward and lands on a different calendar date in
+  // ANY fixed offset.
+  const offsetMatch = /(?:Z|([+-])(\d{2}):(\d{2}))$/.exec(occurredAt);
+  const offsetMs =
+    offsetMatch && offsetMatch[1]
+      ? (offsetMatch[1] === "-" ? -1 : 1) *
+        (Number(offsetMatch[2]) * 3600 + Number(offsetMatch[3]) * 60) *
+        1000
+      : 0;
+  const parsedDatePrefix = new Date(occurredAtMs + offsetMs).toISOString().slice(0, 10);
+  if (roundTripDatePrefix !== parsedDatePrefix) {
+    throw new Error(
+      `eventArchiveKey: occurredAt ${JSON.stringify(occurredAt)} is not a valid date`,
+    );
+  }
+  if (!Number.isSafeInteger(sequence) || sequence < 0) {
+    // `sequence` is SERVER-owned (allocated inside the DO's write transaction, types.ts), so this
+    // is not reachable from a producer today — but eventArchiveKey is an exported boundary function
+    // in a published package, so its callers are not all in this repo. A malformed value would
+    // otherwise break the lexicographic-ordering invariant SEQUENCE_PAD_WIDTH exists to guarantee
+    // (e.g. padding "NaN" or a negative number into a key that no longer sorts numerically).
+    throw new Error(
+      `eventArchiveKey: sequence ${JSON.stringify(sequence)} is not a safe non-negative integer`,
+    );
+  }
+  if (typeof eventId !== "string" || !EVENT_ID_RE.test(eventId)) {
+    // `eventId` is PRODUCER-supplied and interpolated into the key with no separator after it — an
+    // unvalidated slash would inject an extra path segment (see EVENT_ID_RE comment above). The
+    // `typeof` check is load-bearing on its own: `RegExp.prototype.test` COERCES a non-string
+    // argument, so `EVENT_ID_RE.test(null)` tests the literal string "null" (which the allowlist
+    // matches) and would otherwise silently misfile into a plausible-looking `...-null.json` key —
+    // the same coercion-into-a-wrong-partition failure the occurredAt guard above closes for dates.
+    throw new Error(
+      `eventArchiveKey: eventId ${JSON.stringify(eventId)} contains invalid characters`,
+    );
+  }
+  const d = new Date(occurredAt);
+  const yyyy = String(d.getUTCFullYear()).padStart(4, "0");
+  const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
+  const dd = String(d.getUTCDate()).padStart(2, "0");
+  const paddedSequence = String(sequence).padStart(SEQUENCE_PAD_WIDTH, "0");
+  return `${tenantId}/${yyyy}/${mm}/${dd}/${paddedSequence}-${eventId}.json`;
+}
+
+/**
+ * The R2 prefix that scopes a tenant's entire event archive — every key `eventArchiveKey` can ever
+ * produce for that tenant starts with this (the trailing "/" is load-bearing: without it, a tenant id
+ * that is a string-prefix of another, e.g. "t0" vs "t00", would leak into each other's deletion — see
+ * retention.test.ts's dedicated negative case). Throws with the reason named for a non-string, empty,
+ * or slash-bearing `tenantId` rather than silently returning a prefix that would leak (empty) or
+ * mis-scope (slash) a tenant-scoped deletion — the same posture `eventArchiveKey`'s other coordinates
+ * already take.
+ *
+ * ⚠️ This prefix is NOT distinguishable from `apps/mirror/src/artifacts/key.ts`'s `artifactPrefix({
+ * account: tenantId })` — both are a bare `${tenantId}/`. That is only safe under a DEDICATED event-
+ * archive bucket (docs/event-backbone/retention-and-deletion.md §4's recommendation). If a future
+ * binding reuses the shared `ARTIFACTS` bucket instead, this prefix MUST gain a distinct segment
+ * (e.g. `${tenantId}/events/`) before that binding ships, or a tenant-scoped teardown on one prefix
+ * will also sweep (or miss) the other.
+ */
+export function eventArchiveTenantPrefix(tenantId: string): string {
+  assertValidTenantId("eventArchiveTenantPrefix", tenantId);
+  return `${tenantId}/`;
+}
+
+/** What `mayPruneHotEvent` needs to know about one hot-window event. */
+export interface HotEventPruneCheck {
+  /** Epoch ms the R2 archive write was CONFIRMED, or `null` if not yet (or never) confirmed. */
+  archivedAt: number | null;
+  /** How old the event is, in ms, at the time of the check. */
+  ageMs: number;
+}
+
+/**
+ * May this hot-window event be pruned from DO SQLite? Both conditions are required — the proposal's
+ * own invariant: "Prune an event only after its R2 archive is confirmed." An event past the hot
+ * window with an UNCONFIRMED archive must NOT be pruned (the only durable copy would be lost); an
+ * event with a confirmed archive but still inside the hot window is kept for fast local replay.
+ */
+export function mayPruneHotEvent(check: HotEventPruneCheck): boolean {
+  return check.archivedAt !== null && check.ageMs > EVENT_HOT_WINDOW_MS;
+}
+
+/** Bump when the projection's slot ASSIGNMENT changes (a field moves position, or the slot count
+ *  changes); additive-at-the-end changes to a slot's semantic meaning still bump, because AE has no
+ *  schema to enforce it and a silent reinterpretation of an existing blob/double is the failure mode
+ *  this version guards against. */
+export const EVENT_PROJECTION_VERSION = 1;
+
+/** The Analytics Engine binding's slot budget this projection must stay inside — `apps/mirror/src/
+ *  event-stream/validate.ts`'s own documented caps, mirrored here so a future binding can assert
+ *  against the same numbers without importing a Workers-shaped module into this package. */
+export const AE_MAX_BLOB_SLOTS = 20;
+
+export interface EventProjectionSlots {
+  indexes: string[];
+  blobs: string[];
+  doubles: string[];
+}
+
+/**
+ * ⭐ THE VERSIONED AE PROJECTION — pinned POSITIONALLY to the layout that already exists and is live:
+ * `apps/mirror/src/event-stream/validate.ts:52-67`'s `toEventStreamDataPoint`, which returns
+ * `{indexes: [tenantId], blobs: [p.source, p.type, p.action, p.id, p.payloadExcerpt], doubles:
+ * [p.seq]}` off a `UnifiedEventPoint`. `sequence` here names the SAME position as that function's
+ * `p.seq` — `CatalystEvent.sequence` is this repo's name for the identical value. This function
+ * exists so a future phase that VERSIONS the live layout (rather than forking a second, silently
+ * divergent one) has a single source of truth to import; it is not consumed by any runtime code yet
+ * — that consumption is phase 2 of the vertical slice, out of this ticket's scope.
+ */
+export function eventProjectionSlots(): EventProjectionSlots {
+  return {
+    indexes: ["tenantId"],
+    blobs: ["source", "type", "action", "id", "payloadExcerpt"],
+    doubles: ["sequence"],
+  };
+}

package/src/events/type-grammar.ts

@@ -0,0 +1,64 @@
+// type-grammar.ts — CTC-936 phase 1. The variable-free `type` grammar Finding 2 proves the closed
+// registry depends on. See packages/schema/thoughts plan
+// (thoughts/shared/plans/2026-08-24-CTC-936-event-contract-phase-1.md) Finding 2: a full August scan
+// found 5,786 distinct raw `event.name` values, and 5,500 of those embedded a ticket id
+// (`CTC-###`/`CTL-###`/`ADV-###`). Stripping that one variable segment collapses the space to 433
+// types — a size a closed, reviewed registry can actually cover. That collapse is only sound if the
+// `type` field is FORBIDDEN from ever carrying a variable segment again, so this grammar is the
+// precondition for phase 2's registry being satisfiable at all, not a style preference.
+
+/** Bump when a field's meaning changes; additive fields do not bump. */
+export const EVENT_SCHEMA_VERSION = 1;
+
+/** Dotted lower-kebab segments: `lease.claimed`, `webhook.linear.issue.updated`. At least two
+ *  segments (one dot) are required — a bare single word is not a `type`. */
+const EVENT_TYPE_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?:\.[a-z][a-z0-9]*(?:-[a-z0-9]+)*)+$/;
+const MAX_EVENT_TYPE_BYTES = 128;
+
+/**
+ * ⛔ A ticket id in the TYPE is the defect this closes. Measured 2026-08: 5,500 of 5,786 observed
+ * event names carried one, which is the entire reason the name space was 5,786 wide instead of 433.
+ * The id belongs in `CatalystEvent.entity`, which exists for exactly this. Case-insensitive: the
+ * grammar's own lowercase-only rule already refuses an UPPERCASE ticket id, but this check also
+ * refuses a hypothetical lowercase one (`ctc-936`) that would otherwise slip past EVENT_TYPE_RE.
+ */
+const VARIABLE_SEGMENT_RE = /\b(?:CTC|CTL|ADV)-\d+\b/i;
+
+function byteLength(s: string): number {
+  return new TextEncoder().encode(s).length;
+}
+
+/** True iff `t` is a well-formed, variable-free dotted lower-kebab event type. Never throws. */
+export function isValidEventType(t: string): boolean {
+  if (typeof t !== "string" || t.length === 0) return false;
+  if (byteLength(t) > MAX_EVENT_TYPE_BYTES) return false;
+  if (VARIABLE_SEGMENT_RE.test(t)) return false;
+  return EVENT_TYPE_RE.test(t);
+}
+
+/**
+ * Throws with the reason named — never returns a falsy sentinel (AGENTS.md: a helper that degrades
+ * to `undefined` reads as "fine" to every caller). Checks the variable-segment case FIRST so that
+ * shape gets its own actionable message rather than being folded into the generic "malformed" one.
+ */
+export function assertValidEventType(t: string): void {
+  if (typeof t === "string" && VARIABLE_SEGMENT_RE.test(t)) {
+    throw new Error(
+      `event type ${JSON.stringify(t)} carries a variable segment (a ticket id) — move it to ` +
+        `CatalystEvent.entity ({ type: "ticket", id }) instead of embedding it in \`type\``,
+    );
+  }
+  if (!isValidEventType(t)) {
+    throw new Error(
+      `event type ${JSON.stringify(t)} is not a valid dotted lower-kebab event type ` +
+        `(pattern: lower-kebab segments joined by ".", max ${MAX_EVENT_TYPE_BYTES} bytes)`,
+    );
+  }
+}
+
+/** Splits a type into its leading domain segment plus the full segment list, for registry
+ *  grouping/reporting. Pure string split — does not itself validate `t`. */
+export function parseEventType(t: string): { domain: string; segments: string[] } {
+  const segments = t.split(".");
+  return { domain: segments[0] ?? "", segments };
+}

package/src/events/types.ts

@@ -0,0 +1,50 @@
+// types.ts — CTC-936 phase 1. The versioned event envelope, verbatim from the accepted proposal's
+// `CatalystEvent<T>` (thoughts/shared/research/2026-08-23-CTC-936-cloudflare-native-event-backbone-
+// proposal.md), field-for-field. ADR-0039 §"Event envelope".
+//
+// Nothing in this repo consumes this type yet — that is deliberate (phase 1 scope). It is the
+// boundary phase 2's DO outbox, phase 3's R2 archive, and phase 4's replay path are typed against.
+
+/**
+ * One entry in the tenant's ordered, immutable event history.
+ *
+ * Each field is documented as SERVER-owned or PRODUCER-supplied — the proposal's own words: "The
+ * server owns sequence assignment and validates event type/version combinations. Producers submit a
+ * typed command or outcome; they do not choose their own tenant sequence."
+ */
+export interface CatalystEvent<T = unknown> {
+  /** SERVER-owned. The tenant this event belongs to — the DO's own partition key. */
+  tenantId: string;
+  /** SERVER-owned. Monotonically increasing per-tenant sequence, allocated inside the DO's write
+   *  transaction. A producer never chooses this. */
+  sequence: number;
+  /** PRODUCER-supplied. A stable idempotent identifier for this specific event occurrence. */
+  eventId: string;
+  /** PRODUCER-supplied. The closed, dotted lower-kebab type — see ./type-grammar.ts and
+   *  ./registry.ts. Must be variable-free; a ticket id belongs in `entity`, not here. */
+  type: string;
+  /** PRODUCER-supplied. Which version of `type`'s payload shape this event was written against —
+   *  see EVENT_SCHEMA_VERSION below. The server validates the (type, schemaVersion) combination. */
+  schemaVersion: number;
+  /** SERVER-owned. When the DO committed this event — ISO-8601, the DO's own clock. */
+  recordedAt: string;
+  /** PRODUCER-supplied, optional. When the underlying real-world fact actually occurred, if that
+   *  differs from `recordedAt` (e.g. a delayed webhook delivery). */
+  occurredAt?: string;
+  /** PRODUCER-supplied, optional. The domain entity this event is about — this is where a variable
+   *  identifier (a ticket id, a PR number, a lease id) belongs, never in `type`. */
+  entity?: { type: string; id: string };
+  /** PRODUCER-supplied, optional. Who/what caused this event — a host, an agent, a webhook sender. */
+  actor?: { type: string; id?: string };
+  /** PRODUCER-supplied, optional. Groups events that belong to one logical operation across
+   *  producers/consumers. */
+  correlationId?: string;
+  /** PRODUCER-supplied, optional. The id of the event (or command) that directly caused this one —
+   *  the causal edge, distinct from the broader `correlationId` grouping. */
+  causationId?: string;
+  /** PRODUCER-supplied, optional. A key a producer can reuse across retries so a re-submitted write
+   *  is deduplicated rather than double-appended. */
+  idempotencyKey?: string;
+  /** PRODUCER-supplied. The typed body — shape depends on `type` + `schemaVersion`. */
+  payload: T;
+}

package/src/index.ts

@@ -76,6 +76,12 @@ export {
   type SchemaSkew,
 } from "./skew.js";
 
+// CTC-936 phase 1 (ADR-0039) — the event-contract module: the versioned `CatalystEvent<T>` envelope
+// and the variable-free dotted lower-kebab type grammar. Barrel-exported here so the SDK's existing
+// exact pin on this package (bun.lock) reaches it with no new published surface — see
+// packages/schema/src/events/index.ts's own header for what phase 2+ adds to this barrel.
+export * from "./events/index.js";
+
 /** Every table in the Mirror DO store — pass as `drizzle(storage, { schema: mirrorSchema })`. */
 export const mirrorSchema = {
   issues,