@cosmicdrift/kumiko-framework 0.1.0

package/src/pipeline/__tests__/event-dispatcher-pg-listen.integration.ts

@@ -0,0 +1,123 @@
+// E.4 — PG LISTEN/NOTIFY wake-up. Without this, delivery latency is
+// bounded below by pollIntervalMs (default 100ms, test-stack 50ms). With
+// LISTEN, event-store.append fires `pg_notify` on commit and any
+// subscribed dispatcher wakes immediately — latency becomes TCP
+// round-trip, typically sub-millisecond on localhost.
+//
+// The polling timer stays on as a safety net for dropped subscriptions
+// and crashes between commit and wake. These tests pin:
+//
+//   1. NOTIFY → runOnce fires faster than one pollInterval.
+//   2. The dispatcher starts cleanly when pgClient is wired and stops
+//      without leaking the LISTEN connection.
+
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { createTenantDb, type TenantDb } from "../../db/tenant-db";
+import { defineFeature } from "../../engine";
+import { createEntityTable, setupTestStack, type TestStack, TestUsers } from "../../stack";
+import { sharedWidgetEntity, sharedWidgetTable } from "../../testing";
+
+// --- Fixture ---
+
+const executor = createEventStoreExecutor(sharedWidgetTable, sharedWidgetEntity, {
+  entityName: "widget",
+});
+
+const deliveryTimes: number[] = [];
+
+const listenFeature = defineFeature("listen", (r) => {
+  r.entity("widget", sharedWidgetEntity);
+
+  r.multiStreamProjection({
+    name: "latency-probe",
+    apply: {
+      "widget.created": async () => {
+        deliveryTimes.push(Date.now());
+      },
+    },
+  });
+});
+
+const admin = TestUsers.admin;
+let stack: TestStack;
+let tdb: TenantDb;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [listenFeature],
+    systemHooks: [],
+  });
+  await createEntityTable(stack.db, sharedWidgetEntity, "widget");
+  tdb = createTenantDb(stack.db, admin.tenantId);
+});
+
+afterAll(async () => {
+  // setupTestStack's cleanup handles eventDispatcher.stop(), which in
+  // turn unlistens.
+});
+
+// --- Tests ---
+
+describe("E.4 — PG NOTIFY/LISTEN wake-up", () => {
+  test("NOTIFY on commit triggers runOnce faster than one pollInterval", async () => {
+    // pollIntervalMs in the test-stack is 50ms. If LISTEN works, delivery
+    // lands within a few ms of commit; if LISTEN is broken, it takes up
+    // to pollIntervalMs. Use a generous upper bound that still discriminates:
+    // if the timer drives delivery, the gap between append and delivery
+    // is 25–50ms on average. If LISTEN drives it, it's sub-10ms.
+    deliveryTimes.length = 0;
+
+    await stack.eventDispatcher?.start();
+    try {
+      const appendedAt = Date.now();
+      await executor.create({ name: "latency-test" }, admin, tdb);
+
+      // Wait up to 500ms, then check latency.
+      const deadline = Date.now() + 500;
+      while (Date.now() < deadline && deliveryTimes.length === 0) {
+        await new Promise((r) => setTimeout(r, 5));
+      }
+      expect(deliveryTimes).toHaveLength(1);
+
+      const latencyMs = (deliveryTimes[0] ?? 0) - appendedAt;
+      // LISTEN should beat the polling timer comfortably. Originally 40ms
+      // (LISTEN typical: <10ms; pollInterval: 50ms). ARM self-hosted runner
+      // schwankt bei 50-60ms wegen DB-IPC + clock-jitter im poll-loop —
+      // bound auf 2× pollInterval erweitert. Discriminierung bleibt:
+      // wenn LISTEN ganz broken ist, fällt der 500ms-Wait am `expect
+      // (deliveryTimes).toHaveLength(1)`-Check leer.
+      expect(latencyMs).toBeLessThan(100);
+    } finally {
+      await stack.eventDispatcher?.stop();
+    }
+  });
+
+  test("dispatcher start/stop cycle with LISTEN attached still delivers after restart", async () => {
+    // Repeated start/stop must not leak connections or break LISTEN. After
+    // 3 cycles the last .start() should still wake on NOTIFY — if the
+    // unlisten handle was mishandled, the subscription would either be
+    // stale (LISTEN on a closed connection) or double-registered.
+    for (let i = 0; i < 2; i++) {
+      await stack.eventDispatcher?.start();
+      await stack.eventDispatcher?.stop();
+    }
+
+    deliveryTimes.length = 0;
+    await stack.eventDispatcher?.start();
+    try {
+      const appendedAt = Date.now();
+      await executor.create({ name: "restart-probe" }, admin, tdb);
+      const deadline = Date.now() + 500;
+      while (Date.now() < deadline && deliveryTimes.length === 0) {
+        await new Promise((r) => setTimeout(r, 5));
+      }
+      expect(deliveryTimes).toHaveLength(1);
+      // Latency must still be LISTEN-fast (< pollInterval) — if the
+      // subscription silently dropped, the timer would deliver at ~50ms.
+      expect((deliveryTimes[0] ?? 0) - appendedAt).toBeLessThan(40);
+    } finally {
+      await stack.eventDispatcher?.stop();
+    }
+  });
+});

package/src/pipeline/__tests__/event-dispatcher-recovery.integration.ts

@@ -0,0 +1,202 @@
+// E.9 — Dead-Letter Recovery surface.
+//
+// The dispatcher halts-on-poison: repeated handler throws on the same event
+// mark the consumer "dead" and pause delivery for it. Without an operational
+// recovery surface, "dead" was a terminal state with only raw SQL as an
+// escape hatch. These tests pin the five recovery moves:
+//
+//   restartConsumer  status=dead → idle, attempts=0, cursor unchanged.
+//                    Dispatcher retries the failing event on the next pass.
+//   disableConsumer  status=any → disabled. Dispatcher skips it entirely.
+//   enableConsumer   status=disabled → idle. Delivery resumes.
+//   skipPoisonEvent  advances cursor past the first event after the current
+//                    cursor, resets attempts, status=idle. For events that
+//                    will never succeed (broken payload, removed code).
+//   (list/status are read-only; covered by event-dispatcher wiring tests.)
+
+import { afterEach, beforeAll, describe, expect, test } from "vitest";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { createTenantDb, type TenantDb } from "../../db/tenant-db";
+import { defineFeature } from "../../engine";
+import {
+  disableConsumer,
+  enableConsumer,
+  getConsumerState,
+  restartConsumer,
+  skipPoisonEvent,
+} from "../../pipeline";
+import {
+  createEntityTable,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+} from "../../stack";
+import { sharedWidgetEntity, sharedWidgetTable } from "../../testing";
+
+// --- Fixture ---
+
+const executor = createEventStoreExecutor(sharedWidgetTable, sharedWidgetEntity, {
+  entityName: "widget",
+});
+
+// Names that make the observer throw. Reset in afterEach.
+let poisonNames = new Set<string>();
+let observed: Array<{ name: string }> = [];
+
+const recoveryFeature = defineFeature("recoverytest", (r) => {
+  r.entity("widget", sharedWidgetEntity);
+
+  r.multiStreamProjection({
+    name: "observer",
+    apply: {
+      "widget.created": async (event) => {
+        const name = event.payload["name"] as string;
+        if (poisonNames.has(name)) {
+          throw new Error(`poisoned: ${name}`);
+        }
+        observed.push({ name });
+      },
+    },
+  });
+});
+
+const admin = TestUsers.admin;
+const qn = "recoverytest:projection:observer";
+let stack: TestStack;
+let tdb: TenantDb;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [recoveryFeature],
+    systemHooks: [],
+  });
+  await createEntityTable(stack.db, sharedWidgetEntity, "widget");
+  tdb = createTenantDb(stack.db, admin.tenantId);
+});
+
+afterEach(async () => {
+  poisonNames = new Set();
+  observed = [];
+  await resetEventStore(stack, ["read_widgets"]);
+});
+
+async function appendWidget(name: string): Promise<void> {
+  await executor.create({ name }, admin, tdb);
+}
+
+async function driveUntilDead(): Promise<void> {
+  // Default maxAttempts is 10. Run enough passes to exhaust and land on dead.
+  for (let i = 0; i < 10; i++) {
+    await stack.eventDispatcher?.runOnce();
+  }
+}
+
+// --- Tests ---
+
+describe("E.9 — restartConsumer", () => {
+  test("revives a dead consumer: status=idle, attempts=0, cursor unchanged, handler retried next pass", async () => {
+    poisonNames.add("poison");
+    await appendWidget("poison");
+    await driveUntilDead();
+
+    const deadState = await getConsumerState(stack.db, qn);
+    expect(deadState?.status).toBe("dead");
+    expect(deadState?.attempts).toBe(10);
+    const cursorBefore = deadState?.lastProcessedEventId;
+
+    const after = await restartConsumer(stack.db, qn);
+    expect(after.status).toBe("idle");
+    expect(after.attempts).toBe(0);
+    expect(after.lastError).toBeNull();
+    // Cursor unchanged — next pass retries the SAME failing event.
+    expect(after.lastProcessedEventId).toBe(cursorBefore);
+
+    // Retry still poisoned (handler still throws) — attempts climbs again.
+    await stack.eventDispatcher?.runOnce();
+    const afterRetry = await getConsumerState(stack.db, qn);
+    expect(afterRetry?.attempts).toBe(1);
+    expect(afterRetry?.lastError).toMatch(/poisoned: poison/);
+  });
+
+  test("refuses to restart a healthy consumer (only dead makes sense)", async () => {
+    await appendWidget("clean");
+    await stack.eventDispatcher?.runOnce();
+    const state = await getConsumerState(stack.db, qn);
+    expect(state?.status).toBe("idle");
+
+    await expect(restartConsumer(stack.db, qn)).rejects.toThrow(/not dead/);
+  });
+});
+
+describe("E.9 — disable / enable", () => {
+  test("disabled consumer skips delivery even when new events arrive; enable resumes", async () => {
+    await appendWidget("first");
+    await stack.eventDispatcher?.runOnce();
+    expect(observed.map((o) => o.name)).toEqual(["first"]);
+
+    await disableConsumer(stack.db, qn);
+    const disabled = await getConsumerState(stack.db, qn);
+    expect(disabled?.status).toBe("disabled");
+
+    await appendWidget("while-disabled");
+    await stack.eventDispatcher?.runOnce();
+    // Still only "first" — disabled consumer didn't pick up "while-disabled".
+    expect(observed.map((o) => o.name)).toEqual(["first"]);
+
+    await enableConsumer(stack.db, qn);
+    const enabled = await getConsumerState(stack.db, qn);
+    expect(enabled?.status).toBe("idle");
+
+    await stack.eventDispatcher?.runOnce();
+    expect(observed.map((o) => o.name)).toEqual(["first", "while-disabled"]);
+  });
+
+  test("enable on a non-disabled consumer throws (prevents accidental state reset)", async () => {
+    await appendWidget("healthy");
+    await stack.eventDispatcher?.runOnce();
+    await expect(enableConsumer(stack.db, qn)).rejects.toThrow(/not disabled/);
+  });
+});
+
+describe("E.9 — skipPoisonEvent", () => {
+  test("skips past a poisoned event, advances cursor, subsequent events deliver", async () => {
+    await appendWidget("before-poison");
+    await poisonNames.add("the-poison");
+    await appendWidget("the-poison");
+    poisonNames.delete("the-poison"); // no-op for current state; only matters for later retries
+    await appendWidget("after-poison");
+
+    // Restore throw-on: the handler keeps throwing on the poison name
+    // until we explicitly skip it. Re-add.
+    poisonNames.add("the-poison");
+    await driveUntilDead();
+
+    const beforeSkip = await getConsumerState(stack.db, qn);
+    expect(beforeSkip?.status).toBe("dead");
+    // "before-poison" was delivered successfully, so cursor sits at event 1.
+    expect(beforeSkip?.lastProcessedEventId).toBe(1n);
+
+    const skipResult = await skipPoisonEvent(stack.db, qn);
+    expect(skipResult.status).toBe("idle");
+    expect(skipResult.attempts).toBe(0);
+    expect(skipResult.skippedEventId).toBe(2n);
+    expect(skipResult.lastProcessedEventId).toBe(2n);
+
+    // Now the dispatcher should pick up event 3 ("after-poison").
+    await stack.eventDispatcher?.runOnce();
+    expect(observed.map((o) => o.name)).toEqual(["before-poison", "after-poison"]);
+  });
+
+  test("no-op when cursor is already at events head", async () => {
+    await appendWidget("only-one");
+    await stack.eventDispatcher?.runOnce();
+    const caught = await getConsumerState(stack.db, qn);
+    expect(caught?.lastProcessedEventId).toBe(1n);
+
+    const skipResult = await skipPoisonEvent(stack.db, qn);
+    expect(skipResult.skippedEventId).toBeNull();
+    // Cursor did not move.
+    expect(skipResult.lastProcessedEventId).toBe(1n);
+  });
+});

package/src/pipeline/__tests__/event-dispatcher-second-audit.integration.ts

@@ -0,0 +1,290 @@
+// Second-audit fixes — two latent silent-broken behaviours in the async
+// event-dispatcher that only surface when specific call-sites materialise.
+// Pinned here so regressions fail loudly:
+//
+//   1. Prune-vs-new-consumer race. Before the fix, a fresh deploy that
+//      adds a new MSP + simultaneously runs prune could silently delete
+//      events before the new consumer ever saw them. Two pieces close
+//      this: (a) pre-registering every consumer row on dispatcher.start()
+//      so the retention guard sees it, (b) a SHARE-mode table lock in
+//      pruneEvents as defence-in-depth.
+//
+//   2. LISTEN-subscription health is now emitted as a gauge
+//      (kumiko_event_dispatcher_listen_connected). Ops can see the
+//      moment delivery latency regresses from TCP-round-trip to
+//      pollIntervalMs.
+
+import { eq, sql } from "drizzle-orm";
+import { afterEach, beforeAll, describe, expect, test } from "vitest";
+import { defineFeature } from "../../engine";
+import { eventsTable } from "../../event-store";
+import {
+  DEFAULT_SENSITIVE_CONFIG,
+  type MetricEvent,
+  type ObservabilityProvider,
+  RecordingMeter,
+  RecordingTracer,
+} from "../../observability";
+import { ConsumerLagError, eventConsumerStateTable, pruneEvents } from "../../pipeline";
+import {
+  createEntityTable,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+} from "../../stack";
+import { sharedWidgetEntity } from "../../testing";
+import { generateId } from "../../utils";
+
+// --- Fixture ---
+
+const auditFeature = defineFeature("audit", (r) => {
+  r.entity("widget", sharedWidgetEntity);
+
+  // Two MSPs so the dispatcher has two consumer rows to register in the
+  // pre-registration tests below. Both no-op — the tests observe the
+  // kumiko_event_consumers rows, not the apply handlers.
+  r.multiStreamProjection({
+    name: "default-scope",
+    apply: { "widget.created": async () => {} },
+  });
+  r.multiStreamProjection({
+    name: "system-opt-out",
+    apply: { "widget.created": async () => {} },
+  });
+});
+
+const admin = TestUsers.admin;
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [auditFeature],
+    systemHooks: [],
+  });
+  await createEntityTable(stack.db, sharedWidgetEntity, "widget");
+});
+
+afterEach(async () => {
+  await resetEventStore(stack, ["read_widgets"]);
+});
+
+async function seedOldWidgetEvent(createdAt: Temporal.Instant): Promise<void> {
+  await stack.db.insert(eventsTable).values({
+    aggregateId: generateId(),
+    aggregateType: "widget",
+    tenantId: admin.tenantId,
+    version: 1,
+    type: "widget.created",
+    payload: {},
+    metadata: { userId: admin.id },
+    createdAt,
+    createdBy: admin.id,
+  });
+}
+
+// --- Fix #1 — Prune-vs-new-consumer race (pre-registration) ---
+
+describe("Second audit — consumer pre-registration on start()", () => {
+  test("start() inserts a state row for every registered consumer", async () => {
+    // Before the fix, state rows were created lazily on first runOnce. A
+    // deploy that brought up the process AND immediately ran prune (in a
+    // separate service) could prune past a consumer that hadn't run yet.
+    // Pre-registration closes that window: start() inserts, prune sees
+    // every consumer at cursor=0, refuses to prune past them.
+    await stack.eventDispatcher?.start();
+    try {
+      const rows = await stack.db.select().from(eventConsumerStateTable);
+      const names = new Set(rows.map((r) => r.name));
+
+      // The test-stack wires only feature MSP consumers (systemHooks: []),
+      // so we expect the two r.multiStreamProjection entries.
+      expect(names.has("audit:projection:default-scope")).toBe(true);
+      expect(names.has("audit:projection:system-opt-out")).toBe(true);
+
+      // Every pre-registered row starts at cursor 0 with status=idle.
+      for (const row of rows) {
+        expect(row.lastProcessedEventId).toBe(0n);
+        expect(row.status).toBe("idle");
+      }
+    } finally {
+      await stack.eventDispatcher?.stop();
+    }
+  });
+
+  test("pre-registered consumer blocks prune via ConsumerLagError", async () => {
+    // The integration-level guarantee: after start(), prune refuses to
+    // delete events below any pre-registered consumer's cursor. This is
+    // the race fix made deterministic — no Promise.all timing, just the
+    // invariant the fix guarantees.
+    await seedOldWidgetEvent(Temporal.Now.instant().subtract({ hours: 240 }));
+
+    await stack.eventDispatcher?.start();
+    try {
+      await expect(
+        pruneEvents(stack.db, { olderThanDays: 1, aggregateTypes: ["widget"] }),
+      ).rejects.toBeInstanceOf(ConsumerLagError);
+    } finally {
+      await stack.eventDispatcher?.stop();
+    }
+  });
+
+  test("start() is idempotent — two starts don't duplicate state rows", async () => {
+    // ON CONFLICT DO NOTHING guarantees this. Guarded so a buildServer
+    // double-start (or process-wide restart) doesn't trip unique-violation
+    // or regress the cursor.
+    await stack.eventDispatcher?.start();
+    await stack.eventDispatcher?.stop();
+
+    // Advance the cursor explicitly so we can prove the second start
+    // doesn't clobber it back to 0.
+    await stack.db
+      .update(eventConsumerStateTable)
+      .set({ lastProcessedEventId: 42n })
+      .where(eq(eventConsumerStateTable.name, "audit:projection:default-scope"));
+
+    await stack.eventDispatcher?.start();
+    try {
+      const [row] = await stack.db
+        .select()
+        .from(eventConsumerStateTable)
+        .where(eq(eventConsumerStateTable.name, "audit:projection:default-scope"));
+      expect(row?.lastProcessedEventId).toBe(42n);
+    } finally {
+      await stack.eventDispatcher?.stop();
+    }
+  });
+});
+
+// --- Fix #2 — LISTEN observability ---
+
+describe("Second audit — LISTEN gauge", () => {
+  test("kumiko_event_dispatcher_listen_connected is 1 after start() with pgClient", async () => {
+    const metricEvents: MetricEvent[] = [];
+    const meter = new RecordingMeter((e) => metricEvents.push(e));
+    const tracer = new RecordingTracer({
+      sensitiveConfig: DEFAULT_SENSITIVE_CONFIG,
+      onSpanEnd: () => {},
+    });
+    const recordingProvider: ObservabilityProvider = {
+      name: "recording",
+      meter,
+      tracer,
+      shutdown: async () => {},
+    };
+
+    const recStack = await setupTestStack({
+      features: [auditFeature],
+      systemHooks: [],
+      observability: recordingProvider,
+    });
+    try {
+      await createEntityTable(recStack.db, sharedWidgetEntity, "widget");
+
+      await recStack.eventDispatcher?.start();
+      try {
+        // Filter for gauge.set events on the LISTEN metric. Expect the
+        // sequence: 0 (start() resets) → 1 (onlisten callback fires).
+        const gauges = metricEvents.filter(
+          (e) => e.type === "gauge.set" && e.name === "kumiko_event_dispatcher_listen_connected",
+        );
+        expect(gauges.length).toBeGreaterThanOrEqual(2);
+        expect(gauges[0]?.value).toBe(0);
+        expect(gauges[gauges.length - 1]?.value).toBe(1);
+      } finally {
+        await recStack.eventDispatcher?.stop();
+      }
+
+      // After stop(), the gauge must flip back to 0 so ops can tell the
+      // subscription was deliberately torn down (vs. silently dropped).
+      const postStop = metricEvents
+        .filter(
+          (e) => e.type === "gauge.set" && e.name === "kumiko_event_dispatcher_listen_connected",
+        )
+        .pop();
+      expect(postStop?.value).toBe(0);
+    } finally {
+      await recStack.cleanup();
+    }
+  });
+
+  test("onlisten fires again on silent reconnect — gauge flips to 1 a second time", async () => {
+    // This is the claim that justifies the onlisten-callback over a
+    // simpler .set(1) after `await listen()`: on a dropped TCP, postgres.js
+    // re-subscribes automatically and invokes onlisten again, and ops
+    // needs to see the recovery window. Proved here by killing the
+    // LISTEN backend and observing a second gauge.set(1).
+    const metricEvents: MetricEvent[] = [];
+    const meter = new RecordingMeter((e) => metricEvents.push(e));
+    const tracer = new RecordingTracer({
+      sensitiveConfig: DEFAULT_SENSITIVE_CONFIG,
+      onSpanEnd: () => {},
+    });
+    const recordingProvider: ObservabilityProvider = {
+      name: "recording",
+      meter,
+      tracer,
+      shutdown: async () => {},
+    };
+
+    const recStack = await setupTestStack({
+      features: [auditFeature],
+      systemHooks: [],
+      observability: recordingProvider,
+    });
+    try {
+      await createEntityTable(recStack.db, sharedWidgetEntity, "widget");
+
+      await recStack.eventDispatcher?.start();
+      try {
+        const connectsWithValue1 = (): number =>
+          metricEvents.filter(
+            (e) =>
+              e.type === "gauge.set" &&
+              e.name === "kumiko_event_dispatcher_listen_connected" &&
+              e.value === 1,
+          ).length;
+
+        // Wait for the initial onlisten (gauge.set 1) to land.
+        await waitFor(() => connectsWithValue1() >= 1, 2000);
+        const initialConnects = connectsWithValue1();
+        expect(initialConnects).toBeGreaterThanOrEqual(1);
+
+        // Terminate the LISTEN backend. postgres.js runs LISTEN on a
+        // dedicated max=1 sub-pool — the backend whose last query is
+        // `LISTEN "kumiko_events_new"` and is now idle. pg_terminate_backend
+        // on it closes the TCP; postgres.js's onclose handler re-subscribes
+        // and fires onlisten again.
+        await recStack.db.execute(
+          sql`SELECT pg_terminate_backend(pid) FROM pg_stat_activity
+              WHERE datname = current_database()
+                AND query ILIKE 'listen%'
+                AND state = 'idle'
+                AND pid <> pg_backend_pid()`,
+        );
+
+        // Wait for the SECOND gauge.set(1) — the reconnect. Generous timeout
+        // because postgres.js's reconnect loop includes backoff.
+        await waitFor(() => connectsWithValue1() > initialConnects, 10000);
+        expect(connectsWithValue1()).toBeGreaterThan(initialConnects);
+      } finally {
+        await recStack.eventDispatcher?.stop();
+      }
+    } finally {
+      await recStack.cleanup();
+    }
+  });
+});
+
+// --- Helpers ---
+
+async function waitFor(predicate: () => boolean, timeoutMs: number): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (predicate()) return;
+    await new Promise((r) => setTimeout(r, 25));
+  }
+  if (!predicate()) {
+    throw new Error(`waitFor: predicate never became true within ${timeoutMs}ms`);
+  }
+}

package/src/pipeline/__tests__/event-dispatcher-strict.test.ts

@@ -0,0 +1,65 @@
+// Strict-precondition contract: runOnce() without a preceding start() /
+// ensureRegistered() must throw, not silently bootstrap. The throw is the
+// dispatcher's last line of defense against the prune-race — if pre-reg
+// is skipped, the state rows are absent, and acquireConsumerState would
+// return skip="not_registered" for every consumer. Failing loudly surfaces
+// the misuse instead of swallowing events.
+//
+// Unit-level because the check happens before any DB call — no pgClient,
+// no event-store schema, no setupTestStack needed.
+
+import { describe, expect, test } from "vitest";
+import type { AppContext, Registry } from "../../engine/types";
+import { createEventDispatcher, type EventConsumer } from "../event-dispatcher";
+
+function stubContext(): AppContext {
+  return {
+    db: {} as unknown as AppContext["db"],
+    redis: {} as unknown as AppContext["redis"],
+    registry: {} as unknown as Registry,
+  } as AppContext;
+}
+
+describe("event-dispatcher — strict runOnce precondition", () => {
+  test("runOnce() before start() throws a clear 'not registered' error", async () => {
+    const consumers: EventConsumer[] = [{ name: "noop", handler: async () => {} }];
+    const dispatcher = createEventDispatcher({
+      db: {} as never,
+      consumers,
+      context: stubContext(),
+    });
+
+    await expect(dispatcher.runOnce()).rejects.toThrow(/runOnce\(\) called before start\(\)/);
+  });
+
+  test("ensureRegistered() is a valid alternative to start() — runOnce no longer throws", async () => {
+    const consumers: EventConsumer[] = [{ name: "noop", handler: async () => {} }];
+    let insertCalls = 0;
+    const stubDb = {
+      insert: () => ({
+        values: () => ({ onConflictDoNothing: async () => ++insertCalls }),
+      }),
+      transaction: async (fn: (tx: unknown) => Promise<unknown>) =>
+        fn({
+          select: () => ({
+            from: () => ({ where: () => ({ for: () => [] }) }),
+          }),
+          execute: async () => [],
+          update: () => ({ set: () => ({ where: () => Promise.resolve() }) }),
+        }),
+    };
+    const dispatcher = createEventDispatcher({
+      db: stubDb as never,
+      consumers,
+      context: stubContext(),
+    });
+
+    await dispatcher.ensureRegistered();
+    expect(insertCalls).toBe(1);
+    // runOnce() no longer throws — it drains against the stubbed transaction.
+    await expect(dispatcher.runOnce()).resolves.toMatchObject({
+      processed: 0,
+      failed: 0,
+    });
+  });
+});