@pattern-stack/codegen 0.18.0 → 0.20.0

package/dist/src/index.js

@@ -44,27 +44,27 @@ import {
   validateOrchestrationProject,
   validatePatternComposition,
   validatePatternProject
-} from "../chunk-CFFTPWHM.js";
+} from "../chunk-KK5A7B2T.js";
 import "../chunk-KVOWSC5S.js";
-import "../chunk-PKDS6QIJ.js";
-import "../chunk-PRWIX6UW.js";
+import "../chunk-ATVGYF3D.js";
 import "../chunk-YK5JEVLX.js";
 import "../chunk-EO2QPOKH.js";
-import "../chunk-SQDOBLBP.js";
-import "../chunk-TDEHU73T.js";
-import "../chunk-LG57S2SC.js";
+import "../chunk-PRWIX6UW.js";
 import "../chunk-XWBK3XJK.js";
-import "../chunk-S7C6TIIF.js";
-import "../chunk-MZ6GV4YF.js";
-import "../chunk-HNWZFNKP.js";
 import "../chunk-AHV4GDYM.js";
-import "../chunk-43SBT72G.js";
-import "../chunk-4MF3HKJA.js";
-import "../chunk-TIZXQU26.js";
+import "../chunk-SQDOBLBP.js";
 import "../chunk-JEINYUJH.js";
 import "../chunk-5TK7MEN4.js";
 import "../chunk-4KNXX6TI.js";
 import "../chunk-3CJFPU6Q.js";
+import "../chunk-TDEHU73T.js";
+import "../chunk-S7C6TIIF.js";
+import "../chunk-MZ6GV4YF.js";
+import "../chunk-LG57S2SC.js";
+import "../chunk-HNWZFNKP.js";
+import "../chunk-I6UXRJ3Q.js";
+import "../chunk-TIZXQU26.js";
+import "../chunk-4MF3HKJA.js";
 import "../chunk-U64T4YZE.js";
 import "../chunk-2E224ZSN.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",

package/runtime/subsystems/events/domain-events.schema.ts

@@ -43,6 +43,7 @@ import {
   pgTable,
   text,
   timestamp,
+  uniqueIndex,
   uuid,
 } from 'drizzle-orm/pg-core';
 import { sql } from 'drizzle-orm';
@@ -96,6 +97,21 @@ export const domainEvents = pgTable(
     idxDomainEventsTierStatusOccurredAt: index(
       'idx_domain_events_tier_status_occurred_at',
     ).on(t.tier, t.status, t.occurredAt),
+    /**
+     * Scheduling idempotency — partial UNIQUE expression index (ADR-039). The
+     * `EventScheduler` materialises one tick per (event type, slot) by inserting
+     * with `metadata.scheduleSlot = @schedule/<type>/<slotStartMs>` and
+     * `ON CONFLICT DO NOTHING`; this constraint is what makes
+     * "exactly one event per slot" true across multi-instance deploys and
+     * boot/tick races — no advisory lock, no leader election. Partial on the
+     * extracted slot key so it only covers scheduler-materialised rows; ordinary
+     * (use-case / webhook) events carry no `scheduleSlot` and are untouched.
+     */
+    idxDomainEventsScheduleSlot: uniqueIndex(
+      'idx_domain_events_schedule_slot',
+    )
+      .on(t.type, sql`(${t.metadata} ->> 'scheduleSlot')`)
+      .where(sql`${t.metadata} ->> 'scheduleSlot' IS NOT NULL`),
     /**
      * Tier ↔ routing-fields invariant (AUDIT-1):
      *   - `tier` is one of `'domain' | 'audit'`.

package/runtime/subsystems/events/event-bus.drizzle-backend.ts

@@ -28,9 +28,15 @@
  * throughput. At that point, swap the backend for Redis Streams or similar
  * via EventsModule.forRoot({ backend: '...' }) without touching use cases.
  */
+import { randomUUID } from 'node:crypto';
 import { Injectable, OnModuleDestroy, OnModuleInit, Inject, Logger, Optional } from '@nestjs/common';
 import { eq, and, inArray, asc, desc, gte, lt, or, sql, type SQL } from 'drizzle-orm';
-import type { DomainEvent, DrizzleTransaction, IEventBus } from './event-bus.protocol';
+import type {
+  DomainEvent,
+  DrizzleTransaction,
+  IEventBus,
+  ScheduledEventSpec,
+} from './event-bus.protocol';
 import type {
   EventPage,
   IEventReadPort,
@@ -135,6 +141,17 @@ function toEventSummary(r: DomainEventRecord) {
   };
 }
 
+/**
+ * Postgres unique-violation (SQLSTATE 23505) test. Used by the scheduled-event
+ * materialiser (ADR-039) to treat a slot-key collision as the
+ * already-materialised no-op. Reads `.code` defensively across driver shapes
+ * (node-postgres surfaces it on the error, some wrappers nest it on `.cause`).
+ */
+function isUniqueViolation(err: unknown): boolean {
+  const code = (err as { code?: unknown; cause?: { code?: unknown } } | undefined);
+  return code?.code === '23505' || code?.cause?.code === '23505';
+}
+
 @Injectable()
 export class DrizzleEventBus implements IEventBus, IEventReadPort, OnModuleInit, OnModuleDestroy {
   private readonly logger = new Logger(DrizzleEventBus.name);
@@ -340,6 +357,91 @@ export class DrizzleEventBus implements IEventBus, IEventReadPort, OnModuleInit,
     };
   }
 
+  // ============================================================================
+  // ADR-039 — scheduled-event materialisation (time as an event source)
+  // ============================================================================
+
+  /**
+   * Insert one scheduled tick event idempotently. The slot key is stamped onto
+   * `metadata.scheduleSlot`; `ON CONFLICT DO NOTHING` against the partial UNIQUE
+   * expression index `idx_domain_events_schedule_slot` makes a duplicate insert
+   * a no-op — the DB constraint is the exactly-one-event-per-slot invariant.
+   *
+   * Reuses the standard outbox row shape (pool/direction/metadata) so the
+   * existing drain carries the tick like any other event. A LISTEN/NOTIFY wake
+   * fires for an immediately-due tick (boot/catch-up rows whose slot is already
+   * in the past); a future slot is claimed by polling once `occurred_at` passes.
+   */
+  async materializeScheduledEvent(
+    spec: ScheduledEventSpec,
+  ): Promise<{ created: boolean }> {
+    const multiTenant = this.opts.multiTenant ?? false;
+    const metadata: Record<string, unknown> = {
+      pool: spec.pool,
+      direction: spec.direction,
+      scheduleSlot: spec.slotKey,
+      triggerSource: 'schedule',
+    };
+    const base = {
+      id: randomUUID(),
+      type: spec.type,
+      // Payload-free scheduled fact (the dealbrain strict-producer pattern).
+      aggregateId: spec.type,
+      aggregateType: spec.type,
+      payload: {} as Record<string, unknown>,
+      occurredAt: spec.slotStart,
+      processedAt: null,
+      status: 'pending' as const,
+      metadata,
+      pool: spec.pool,
+      direction: spec.direction,
+      tier: 'domain' as const,
+    };
+    const values = multiTenant ? { ...base, tenantId: null } : base;
+
+    // The idempotency guard is the partial UNIQUE expression index
+    // `idx_domain_events_schedule_slot` on (type, metadata->>'scheduleSlot').
+    // Drizzle 0.45's typed `onConflictDoNothing({ target })` only accepts
+    // columns, so it can't name an expression index — we instead let the
+    // insert run and treat a unique-violation (SQLSTATE 23505) as the
+    // already-materialised no-op. This is the exactly-one-per-slot invariant:
+    // a concurrent or repeat materialise of the same slot loses the race at
+    // the DB and reports `created: false`.
+    try {
+      await this.db.insert(domainEvents).values(values);
+    } catch (err) {
+      if (isUniqueViolation(err)) return { created: false };
+      throw err;
+    }
+
+    // Wake the drainer for an already-due tick. A future slot waits for polling.
+    if (spec.slotStart.getTime() <= Date.now()) {
+      await this.emitWakeNotify(this.db, [spec.pool]);
+    }
+    return { created: true };
+  }
+
+  /** Most recent scheduled tick's `occurred_at` (epoch ms) for `type`, or null.
+   *  Read by the scheduler's catch-up backfill. */
+  async lastScheduledSlotMs(type: string): Promise<number | null> {
+    const rows = await this.db
+      .select({ occurredAt: domainEvents.occurredAt })
+      .from(domainEvents)
+      .where(
+        and(
+          eq(domainEvents.type, type),
+          sql`${domainEvents.metadata} ->> 'triggerSource' = 'schedule'`,
+        ),
+      )
+      .orderBy(desc(domainEvents.occurredAt))
+      .limit(1);
+    const row = rows[0];
+    if (!row?.occurredAt) return null;
+    return row.occurredAt instanceof Date
+      ? row.occurredAt.getTime()
+      : new Date(row.occurredAt as unknown as string).getTime();
+  }
+
   // ============================================================================
   // IEventReadPort (OBS-LIST-1)
   // ============================================================================

package/runtime/subsystems/events/event-bus.memory-backend.ts

@@ -19,8 +19,13 @@
  *   than introducing a memory-only options type — the surface is the same
  *   and keeping them unified avoids drift between backends.
  */
+import { randomUUID } from 'node:crypto';
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
-import type { DomainEvent, IEventBus } from './event-bus.protocol';
+import type {
+  DomainEvent,
+  IEventBus,
+  ScheduledEventSpec,
+} from './event-bus.protocol';
 import type {
   EventPage,
   EventSummary,
@@ -110,6 +115,57 @@ export class MemoryEventBus implements IEventBus, IEventReadPort {
     return this.publishedEvents.find((e) => e.id === eventId) ?? null;
   }
 
+  // ============================================================================
+  // ADR-039 — scheduled-event materialisation (memory parity)
+  // ============================================================================
+
+  /** Slot keys already materialised — the in-memory mirror of the partial
+   *  UNIQUE expression index `idx_domain_events_schedule_slot`. */
+  private readonly materialisedSlots = new Set<string>();
+
+  /**
+   * Mirror of the Drizzle `ON CONFLICT DO NOTHING` insert: emit one payload-free
+   * tick event per slot key, no-op if the slot was already materialised. The
+   * "constraint" is the `materialisedSlots` set. The tick is published through
+   * the normal `publish` path so subscribers fire synchronously (the memory bus
+   * has no future-slot/poll concept — a materialised slot dispatches now, which
+   * is the behaviour the unit suite pins).
+   */
+  async materializeScheduledEvent(
+    spec: ScheduledEventSpec,
+  ): Promise<{ created: boolean }> {
+    if (this.materialisedSlots.has(spec.slotKey)) return { created: false };
+    this.materialisedSlots.add(spec.slotKey);
+    const event: DomainEvent = {
+      id: randomUUID(),
+      type: spec.type,
+      aggregateId: spec.type,
+      aggregateType: spec.type,
+      payload: {},
+      occurredAt: spec.slotStart,
+      metadata: {
+        pool: spec.pool,
+        direction: spec.direction,
+        scheduleSlot: spec.slotKey,
+        triggerSource: 'schedule',
+      },
+    };
+    await this.publish(event);
+    return { created: true };
+  }
+
+  /** Most recent scheduled tick's `occurred_at` (epoch ms) for `type`, or null. */
+  async lastScheduledSlotMs(type: string): Promise<number | null> {
+    let best: number | null = null;
+    for (const e of this.publishedEvents) {
+      if (e.type !== type) continue;
+      if (e.metadata?.['triggerSource'] !== 'schedule') continue;
+      const ms = e.occurredAt.getTime();
+      if (best === null || ms > best) best = ms;
+    }
+    return best;
+  }
+
   subscribe<T extends DomainEvent = DomainEvent>(
     eventType: string,
     handler: (event: T) => Promise<void>,

package/runtime/subsystems/events/event-bus.protocol.ts

@@ -83,4 +83,51 @@ export interface IEventBus {
    *     of Redis backend is unsupported.
    */
   findById(eventId: string): Promise<DomainEvent | null>;
+
+  /**
+   * Materialise exactly one scheduled tick event (ADR-039 — time as an event
+   * source). Called by the framework `EventScheduler` on its boot + tick passes.
+   *
+   * The `slotKey` (`@schedule/<type>/<slotStartMs>`) is a pure function of
+   * (type, slot) — every instance computes the same key — and is stamped onto
+   * `metadata.scheduleSlot` (+ `metadata.triggerSource='schedule'`). The insert
+   * is deterministic and idempotent:
+   *   - Drizzle: `INSERT … ON CONFLICT DO NOTHING` against the partial UNIQUE
+   *     expression index on `(type, metadata->>'scheduleSlot')`. The DB
+   *     constraint — not a read, not a lock — is the exactly-one-event-per-slot
+   *     invariant across multi-instance deploys and boot/tick races.
+   *   - Memory: a slot-key marker set mirrors the constraint.
+   *
+   * Returns `created: false` when the slot event already existed (the no-op
+   * case). Optional on the protocol — only the scheduler calls it, and the
+   * Redis backend (no outbox history) does not implement it (the scheduler is
+   * drizzle/memory only).
+   */
+  materializeScheduledEvent?(
+    spec: ScheduledEventSpec,
+  ): Promise<{ created: boolean }>;
+
+  /**
+   * Optional (ADR-039) — `occurred_at` (epoch ms) of the most recent scheduled
+   * tick for `type`, or `null`. Read by the scheduler's catch-up backfill as
+   * `MAX(occurred_at) WHERE type=? AND metadata->>'triggerSource'='schedule'`.
+   */
+  lastScheduledSlotMs?(type: string): Promise<number | null>;
+}
+
+/**
+ * The fully-resolved shape the scheduler hands a backend to materialise one
+ * tick. Carries the routing fields the outbox row needs (direction/pool from
+ * the event's registry metadata) plus the slot key + boundary.
+ */
+export interface ScheduledEventSpec {
+  type: string;
+  /** `@schedule/<type>/<slotStartMs>` — the idempotency key. */
+  slotKey: string;
+  /** Slot boundary → the event's `occurred_at`. */
+  slotStart: Date;
+  /** `inbound | change | outbound` from the event's registry metadata. */
+  direction: string;
+  /** `events_inbound | events_change | events_outbound` from the registry. */
+  pool: string;
 }

package/runtime/subsystems/events/event-scheduler.ts

@@ -0,0 +1,351 @@
+/**
+ * EventScheduler — declarative time-based emission (ADR-039: time as an event
+ * source). Materialises exactly one `domain_events` row per (scheduled event
+ * type, slot) on a cadence; ADR-023's three activation tiers — unchanged — then
+ * react. The scheduler is a STRICT PRODUCER: it emits facts and does no work
+ * (the dealbrain `scheduler.service.ts` shape, generalised onto the outbox).
+ *
+ * Two entry points, both driven by `EventsModule`'s lifecycle:
+ *
+ *   - **reconcile-on-boot** (`materializeBoot`, at `onModuleInit`) — for every
+ *     scheduled event type, materialise the CURRENT slot (catch-up off → run
+ *     once on recovery) or bounded backfill (catch-up on). Boot is when a
+ *     downtime-healing tick matters most. In the outbox model a removed
+ *     `schedule:` simply stops being materialised — there's no broker scheduler
+ *     entry to leave dangling, so the dealbrain ENG-605 "zombie scheduler" class
+ *     of bug is structurally absent; the reconcile half is what we keep.
+ *   - **tick pass** (`materializeTick` on an interval) — materialise each
+ *     scheduled event's NEXT (and current) slot so ticks self-perpetuate.
+ *
+ * Exactly-one-per-slot lives in the DB (the partial UNIQUE expression index on
+ * `(type, metadata->>'scheduleSlot')`), reached via
+ * `IEventBus.materializeScheduledEvent` → `INSERT … ON CONFLICT DO NOTHING`.
+ * The scheduler never READS for an existing slot event (that read is the
+ * swe-brain dedupe trap — it matches the still-running incumbent). The slot key
+ * is a pure function of (type, slot), so every instance computes the same key
+ * and the constraint collapses the race.
+ *
+ * Drizzle + memory only. The Redis bus retains no outbox history, so slot-key
+ * idempotency can't be enforced there (mirrors bridge-on-Redis being
+ * unsupported); the scheduler is not wired under `backend: 'redis'`.
+ */
+import { Logger } from '@nestjs/common';
+import type { IEventBus } from './event-bus.protocol';
+import { ScheduleConfigError } from './events-errors';
+
+// ─── Duration grammar ────────────────────────────────────────────────────────
+
+const UNIT_MS: Readonly<Record<string, number>> = Object.freeze({
+  ms: 1,
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+});
+
+/**
+ * Parse a `schedule.every` into milliseconds. Accepts a positive number (ms) or
+ * a duration string `<number><unit>` (unit ∈ ms|s|m|h|d; decimals allowed).
+ * Throws `ScheduleConfigError` synchronously on anything unparseable, ≤0, or
+ * non-finite — so a bad schedule surfaces at boot before the tick loop starts.
+ */
+export function parseEvery(every: string | number, eventType?: string): number {
+  const where = eventType ? ` (event '${eventType}')` : '';
+  let ms: number;
+  if (typeof every === 'number') {
+    ms = every;
+  } else if (typeof every === 'string') {
+    const match = /^\s*([0-9]*\.?[0-9]+)\s*(ms|s|m|h|d)\s*$/.exec(every);
+    // Destructure the capture groups; under the consumer's stricter tsc
+    // (`noUncheckedIndexedAccess`) regex groups are `string | undefined` and
+    // the UNIT_MS lookup is `number | undefined`, so guard both explicitly
+    // rather than asserting. A truthy `match` always has both groups for this
+    // pattern, but the guard makes that provable (no non-null assertion).
+    const value = match?.[1];
+    const unit = match?.[2];
+    const unitMs = unit ? UNIT_MS[unit] : undefined;
+    if (value === undefined || unitMs === undefined) {
+      throw new ScheduleConfigError(
+        `schedule.every '${every}'${where} is not a valid duration. Use a ` +
+          `number of ms or '<n><unit>' with unit ms|s|m|h|d (e.g. '1h', '30m').`,
+      );
+    }
+    ms = Number(value) * unitMs;
+  } else {
+    throw new ScheduleConfigError(
+      `schedule.every${where} must be a duration string or a number of ms; ` +
+        `got ${typeof every}.`,
+    );
+  }
+  if (!Number.isFinite(ms) || ms <= 0) {
+    throw new ScheduleConfigError(
+      `schedule.every${where} resolved to ${ms}ms — must be a finite, positive ` +
+        `duration.`,
+    );
+  }
+  return ms;
+}
+
+// ─── Slot math ───────────────────────────────────────────────────────────────
+
+/**
+ * The start of the slot containing `atMs`, for a schedule of `everyMs`.
+ *   - `align: true` (default) — epoch-anchored: `floor(at / every) * every`.
+ *   - `align: false` — anchored to `anchorMs` (the scheduler's first-run time).
+ */
+export function slotStartFor(
+  atMs: number,
+  everyMs: number,
+  align: boolean,
+  anchorMs: number,
+): number {
+  if (align) return Math.floor(atMs / everyMs) * everyMs;
+  if (atMs < anchorMs) return anchorMs;
+  return anchorMs + Math.floor((atMs - anchorMs) / everyMs) * everyMs;
+}
+
+/** The start of the slot AFTER the one containing `atMs`. */
+export function nextSlotStart(
+  atMs: number,
+  everyMs: number,
+  align: boolean,
+  anchorMs: number,
+): number {
+  return slotStartFor(atMs, everyMs, align, anchorMs) + everyMs;
+}
+
+/** Prefix every scheduler-materialised `metadata.scheduleSlot` carries — the
+ *  partial UNIQUE index is scoped to non-null slot keys; this prefix keeps the
+ *  key namespace unambiguous and greppable. */
+export const SCHEDULE_KEY_PREFIX = '@schedule/';
+
+/** Deterministic slot key. Pure function of (type, slotStart) — every instance
+ *  computes the same value, which is what makes the idempotent insert
+ *  exactly-once. */
+export function slotKeyFor(type: string, slotStartMs: number): string {
+  return `${SCHEDULE_KEY_PREFIX}${type}/${slotStartMs}`;
+}
+
+// ─── Resolved schedule ───────────────────────────────────────────────────────
+
+const DEFAULT_MAX_CATCH_UP_SLOTS = 1000;
+
+/** Below this floor (== the default outbox poll interval) materialise/drain
+ *  latency dominates the cadence; allowed but warned once at boot. */
+export const SCHEDULE_FLOOR_MS = 1_000;
+
+/** One scheduled event the scheduler will materialise. Built from the generated
+ *  event registry (`schedule` block + direction/pool routing metadata). */
+export interface ScheduledEvent {
+  type: string;
+  everyMs: number;
+  align: boolean;
+  catchUp: boolean;
+  maxCatchUpSlots: number;
+  /** Routing — from the event's registry metadata (a scheduled event is
+   *  domain-tier, so both are always present). */
+  direction: string;
+  pool: string;
+}
+
+/** The raw `schedule` block as it appears in the generated registry entry. */
+export interface RegistrySchedule {
+  every: string | number;
+  align?: boolean;
+  catchUp?: boolean;
+  maxCatchUpSlots?: number;
+}
+
+/** Validate + normalise one registry entry's `schedule` into a `ScheduledEvent`.
+ *  Throws `ScheduleConfigError` on a malformed `every` (boot backstop — codegen
+ *  already validated, this catches hand-edits / version skew). */
+export function resolveScheduledEvent(
+  type: string,
+  schedule: RegistrySchedule,
+  direction: string | null,
+  pool: string | null,
+): ScheduledEvent {
+  if (!direction || !pool) {
+    throw new ScheduleConfigError(
+      `event '${type}' declares a schedule but has no direction/pool — a ` +
+        `scheduled event must be domain-tier so it can route to the bridge.`,
+    );
+  }
+  return {
+    type,
+    everyMs: parseEvery(schedule.every, type),
+    align: schedule.align ?? true,
+    catchUp: schedule.catchUp ?? false,
+    maxCatchUpSlots: schedule.maxCatchUpSlots ?? DEFAULT_MAX_CATCH_UP_SLOTS,
+    direction,
+    pool,
+  };
+}
+
+/**
+ * Read the scheduled-event set from a generated `eventRegistry`. The registry
+ * value shape is structural (`{ schedule?, direction, pool }`) so this stays
+ * decoupled from the generated `EventMetadata` type. Returns `[]` when nothing
+ * declared `schedule:`.
+ */
+export function scheduledEventsFromRegistry(
+  registry: Record<
+    string,
+    { schedule?: RegistrySchedule; direction: string | null; pool: string | null }
+  >,
+): ScheduledEvent[] {
+  const out: ScheduledEvent[] = [];
+  for (const [type, meta] of Object.entries(registry)) {
+    if (!meta?.schedule) continue;
+    out.push(resolveScheduledEvent(type, meta.schedule, meta.direction, meta.pool));
+  }
+  return out;
+}
+
+// ─── EventScheduler ──────────────────────────────────────────────────────────
+
+export interface EventSchedulerOptions {
+  /** Tick cadence (ms). Default = smallest scheduled `every`, floored. Test override. */
+  tickIntervalMs?: number;
+  /** Injectable clock for deterministic tests. Default `Date.now`. */
+  now?: () => number;
+}
+
+export class EventScheduler {
+  private readonly logger = new Logger(EventScheduler.name);
+  private readonly now: () => number;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private readonly anchorMs: number;
+  private readonly tickIntervalMs: number;
+
+  constructor(
+    private readonly bus: IEventBus,
+    private readonly schedules: ReadonlyArray<ScheduledEvent>,
+    opts: EventSchedulerOptions = {},
+  ) {
+    this.now = opts.now ?? Date.now;
+    this.anchorMs = this.now();
+    const smallest = schedules.length
+      ? Math.min(...schedules.map((s) => s.everyMs))
+      : SCHEDULE_FLOOR_MS;
+    this.tickIntervalMs = opts.tickIntervalMs ?? Math.max(smallest, SCHEDULE_FLOOR_MS);
+    for (const s of schedules) {
+      if (s.everyMs < SCHEDULE_FLOOR_MS) {
+        this.logger.warn(
+          `schedule for '${s.type}' is every ${s.everyMs}ms — below the ` +
+            `${SCHEDULE_FLOOR_MS}ms floor; materialise/drain latency dominates, ` +
+            `so the cadence is not honoured to that precision.`,
+        );
+      }
+    }
+    if (typeof bus.materializeScheduledEvent !== 'function') {
+      // The backend (e.g. Redis) cannot enforce slot idempotency. Caller
+      // should not construct the scheduler for such backends; guard anyway.
+      this.logger.warn(
+        `the configured event bus does not support scheduled-event ` +
+          `materialisation; ${schedules.length} schedule(s) will not fire.`,
+      );
+    }
+  }
+
+  /** Reconcile-on-boot, then start the tick interval. Idempotent. */
+  async start(): Promise<void> {
+    if (this.schedules.length === 0) return;
+    if (typeof this.bus.materializeScheduledEvent !== 'function') return;
+    await this.materializeBoot();
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      void this.materializeTick();
+    }, this.tickIntervalMs);
+    (this.timer as { unref?: () => void }).unref?.();
+    this.logger.log(
+      `EventScheduler started: ${this.schedules.length} scheduled event(s), ` +
+        `tick=${this.tickIntervalMs}ms.`,
+    );
+  }
+
+  /** Stop the tick interval. Idempotent. */
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /** Boot pass — materialise the current slot (or bounded backfill) per event. */
+  async materializeBoot(): Promise<void> {
+    const nowMs = this.now();
+    for (const s of this.schedules) {
+      try {
+        if (s.catchUp) {
+          await this.backfill(s, nowMs);
+        } else {
+          await this.materializeOne(s, slotStartFor(nowMs, s.everyMs, s.align, this.anchorMs));
+        }
+      } catch (err) {
+        this.logger.error(
+          `boot materialise for '${s.type}' failed: ${(err as Error).message}`,
+        );
+      }
+    }
+  }
+
+  /** Tick pass — materialise the current + next slot per event (current covers a
+   *  tick landing in a fresh slot the boot pass missed). */
+  async materializeTick(): Promise<void> {
+    const nowMs = this.now();
+    for (const s of this.schedules) {
+      try {
+        const current = slotStartFor(nowMs, s.everyMs, s.align, this.anchorMs);
+        await this.materializeOne(s, current);
+        await this.materializeOne(s, current + s.everyMs);
+      } catch (err) {
+        this.logger.error(
+          `tick materialise for '${s.type}' failed: ${(err as Error).message}`,
+        );
+      }
+    }
+  }
+
+  private async materializeOne(s: ScheduledEvent, slotStartMs: number): Promise<void> {
+    // `materialize*` only runs after `start()`/the boot path confirmed the bus
+    // supports materialisation; guard here too (no non-null assertion) so the
+    // optional-method call is provably defined.
+    const materialize = this.bus.materializeScheduledEvent;
+    if (!materialize) return;
+    const slotKey = slotKeyFor(s.type, slotStartMs);
+    const { created } = await materialize.call(this.bus, {
+      type: s.type,
+      slotKey,
+      slotStart: new Date(slotStartMs),
+      direction: s.direction,
+      pool: s.pool,
+    });
+    if (created) {
+      this.logger.debug?.(
+        `materialised '${s.type}' slot ${new Date(slotStartMs).toISOString()}`,
+      );
+    }
+  }
+
+  /** Backfill missed slots from the last emitted slot to the current one,
+   *  bounded by `maxCatchUpSlots`. */
+  private async backfill(s: ScheduledEvent, nowMs: number): Promise<void> {
+    const current = slotStartFor(nowMs, s.everyMs, s.align, this.anchorMs);
+    const lastMs = (await this.bus.lastScheduledSlotMs?.(s.type)) ?? null;
+    let from = lastMs !== null ? lastMs + s.everyMs : current;
+    if (from > current) from = current; // last >= current → just (re)try current
+    const total = Math.floor((current - from) / s.everyMs) + 1;
+    if (total > s.maxCatchUpSlots) {
+      const dropped = total - s.maxCatchUpSlots;
+      from = current - (s.maxCatchUpSlots - 1) * s.everyMs;
+      this.logger.warn(
+        `catchUp for '${s.type}' would backfill ${total} slots; capping at ` +
+          `${s.maxCatchUpSlots} (dropping ${dropped} oldest).`,
+      );
+    }
+    for (let slot = from; slot <= current; slot += s.everyMs) {
+      await this.materializeOne(s, slot);
+    }
+  }
+}