feat(core-events): scaffold events optional core

Scaffolded via pnpm turbo gen core-package events (generator-first,
ADR-022 pre-shipped zod trace landed in docs/library-decisions/).
Generator wired transpilePackages + E1/J eslint rule block. Two
story-00-precedent additions so the coverage gates pass: the
@vitest/coverage-v8 devDep (L0 sweep) and the honest symbols.ts
exclude (mirroring core-shared/vitest.config.ts) plus its missing
ALLOWED_GLOBS mirror in scripts/coverage/diff.mjs (L1 gate). No
consumers wired — compile-green floor for the walking-skeleton
PRD (ADR-027).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK

packages/core-events/src/event-bus.interface.ts

@@ -0,0 +1,24 @@
+import type { z } from "zod";
+import type { EventBusProtocol } from "@repo/core-shared/di/bind-protocols";
+import type { EventDescriptor } from "./event-descriptor";
+
+export type EventHandler<T> = (event: T) => Promise<void>;
+
+export interface IEventBus extends EventBusProtocol {
+  publish<T>(
+    descriptor: EventDescriptor<string, z.ZodType<T>>,
+    payload: T,
+  ): Promise<void>;
+
+  /**
+   * Subscribe a handler. `consumerFeature` is the kebab-case name of the
+   * subscribing feature (e.g., "marketing-pages"). It is unused by
+   * InMemoryEventBus; PayloadJobsEventBus uses it to name the fan-out task
+   * slug deterministically (`__events.<event>.<consumerFeature>`).
+   */
+  subscribe<T>(
+    descriptor: EventDescriptor<string, z.ZodType<T>>,
+    consumerFeature: string,
+    handler: EventHandler<T>,
+  ): void;
+}

packages/core-events/src/event-descriptor.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@/event-descriptor";
+
+describe("defineEvent", () => {
+  it("returns a descriptor with name and schema", () => {
+    const schema = z.object({ id: z.string() }).strict();
+    const descriptor = defineEvent("test.thing.happened", schema);
+    expect(descriptor.name).toBe("test.thing.happened");
+    expect(descriptor.schema).toBe(schema);
+  });
+
+  it("descriptor.schema parses valid payloads", () => {
+    const schema = z.object({ id: z.string() }).strict();
+    const d = defineEvent("test.evt", schema);
+    expect(() => d.schema.parse({ id: "abc" })).not.toThrow();
+  });
+
+  it("descriptor.schema rejects invalid payloads", () => {
+    const schema = z.object({ id: z.string() }).strict();
+    const d = defineEvent("test.evt", schema);
+    expect(() => d.schema.parse({ id: 123 })).toThrow();
+  });
+});

packages/core-events/src/event-descriptor.ts

@@ -0,0 +1,13 @@
+import type { z } from "zod";
+
+export type EventDescriptor<TName extends string, TSchema extends z.ZodType> = {
+  readonly name: TName;
+  readonly schema: TSchema;
+};
+
+export function defineEvent<TName extends string, TSchema extends z.ZodType>(
+  name: TName,
+  schema: TSchema,
+): EventDescriptor<TName, TSchema> {
+  return { name, schema };
+}

packages/core-events/src/in-memory-event-bus.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, vi } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@/event-descriptor";
+import { InMemoryEventBus } from "@/in-memory-event-bus";
+
+const evt = defineEvent("test.thing", z.object({ id: z.string() }).strict());
+
+describe("InMemoryEventBus", () => {
+  it("validates the payload via the descriptor's schema before fanout", async () => {
+    const bus = new InMemoryEventBus();
+    const handler = vi.fn();
+    bus.subscribe(evt, "test-consumer", handler);
+    await expect(
+      bus.publish(evt, { id: 123 } as unknown as { id: string }),
+    ).rejects.toThrow();
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("delivers to all registered handlers in parallel", async () => {
+    const bus = new InMemoryEventBus();
+    const a = vi.fn();
+    const b = vi.fn();
+    bus.subscribe(evt, "consumer-a", a);
+    bus.subscribe(evt, "consumer-b", b);
+    await bus.publish(evt, { id: "x" });
+    expect(a).toHaveBeenCalledWith({ id: "x" });
+    expect(b).toHaveBeenCalledWith({ id: "x" });
+  });
+
+  it("swallows handler errors by default (publisher's publish does not throw)", async () => {
+    const bus = new InMemoryEventBus();
+    bus.subscribe(evt, "boom", async () => {
+      throw new Error("subscriber blew up");
+    });
+    await expect(bus.publish(evt, { id: "x" })).resolves.toBeUndefined();
+  });
+
+  it("rethrows the first handler error when failFast is true", async () => {
+    const bus = new InMemoryEventBus({ failFast: true });
+    bus.subscribe(evt, "first", async () => {
+      throw new Error("first failure");
+    });
+    bus.subscribe(evt, "second", vi.fn());
+    await expect(bus.publish(evt, { id: "x" })).rejects.toThrow(
+      "first failure",
+    );
+  });
+
+  it("delivers nothing when no handlers are registered", async () => {
+    const bus = new InMemoryEventBus();
+    await expect(bus.publish(evt, { id: "x" })).resolves.toBeUndefined();
+  });
+});

packages/core-events/src/in-memory-event-bus.ts

@@ -0,0 +1,42 @@
+import type { z } from "zod";
+import type { EventDescriptor } from "./event-descriptor";
+import type { EventHandler, IEventBus } from "./event-bus.interface";
+
+export type InMemoryEventBusOptions = {
+  /** When true, rethrow the first handler error (default: false — errors swallowed). */
+  failFast?: boolean;
+};
+
+export class InMemoryEventBus implements IEventBus {
+  private readonly handlers = new Map<string, EventHandler<unknown>[]>();
+
+  constructor(private readonly options: InMemoryEventBusOptions = {}) {}
+
+  async publish<T>(
+    descriptor: EventDescriptor<string, z.ZodType<T>>,
+    payload: T,
+  ): Promise<void> {
+    descriptor.schema.parse(payload);
+    const subscribers = this.handlers.get(descriptor.name) ?? [];
+    if (subscribers.length === 0) return;
+    const settled = await Promise.allSettled(
+      subscribers.map((h) => h(payload)),
+    );
+    if (this.options.failFast) {
+      const failure = settled.find((s) => s.status === "rejected");
+      // Only the first rejection is rethrown. Other failures are intentionally
+      // dropped — `failFast` is a test-affordance, not a fault-tolerance design.
+      if (failure && failure.status === "rejected") throw failure.reason;
+    }
+  }
+
+  subscribe<T>(
+    descriptor: EventDescriptor<string, z.ZodType<T>>,
+    _consumerFeature: string,
+    handler: EventHandler<T>,
+  ): void {
+    const arr = this.handlers.get(descriptor.name) ?? [];
+    arr.push(handler as EventHandler<unknown>);
+    this.handlers.set(descriptor.name, arr);
+  }
+}

packages/core-events/src/index.ts

@@ -0,0 +1,9 @@
+export type { EventDescriptor } from "./event-descriptor";
+export { defineEvent } from "./event-descriptor";
+export type { IEventBus, EventHandler } from "./event-bus.interface";
+export { CORE_EVENTS_SYMBOLS } from "./symbols";
+export {
+  InMemoryEventBus,
+  type InMemoryEventBusOptions,
+} from "./in-memory-event-bus";
+export { PayloadJobsEventBus } from "./payload-jobs-event-bus";

packages/core-events/src/payload-jobs-event-bus.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@/event-descriptor";
+import { PayloadJobsEventBus } from "@/payload-jobs-event-bus";
+import type { IJobQueue } from "@repo/core-shared/jobs";
+
+const evt = defineEvent(
+  "auth.user.signed-up",
+  z.object({ userId: z.string() }).strict(),
+);
+
+function recordingQueue(): IJobQueue & {
+  enqueued: { taskSlug: string; input: unknown }[];
+} {
+  const enqueued: { taskSlug: string; input: unknown }[] = [];
+  const q: IJobQueue = {
+    async enqueue(taskSlug, input) {
+      enqueued.push({ taskSlug, input });
+      return { jobId: `recording-${enqueued.length}` };
+    },
+  };
+  return Object.assign(q, { enqueued });
+}
+
+describe("PayloadJobsEventBus", () => {
+  it("validates the payload before enqueueing", async () => {
+    const queue = recordingQueue();
+    const bus = new PayloadJobsEventBus(queue);
+    bus.subscribe(evt, "marketing-pages", vi.fn());
+    await expect(
+      bus.publish(evt, { userId: 42 } as unknown as { userId: string }),
+    ).rejects.toThrow();
+    expect(queue.enqueued).toHaveLength(0);
+  });
+
+  it("enqueues one task per subscriber, naming `__events.<event>.<consumer>`", async () => {
+    const queue = recordingQueue();
+    const bus = new PayloadJobsEventBus(queue);
+    bus.subscribe(evt, "marketing-pages", vi.fn());
+    bus.subscribe(evt, "blog", vi.fn());
+    await bus.publish(evt, { userId: "u1" });
+    expect(queue.enqueued).toHaveLength(2);
+    expect(queue.enqueued.map((e) => e.taskSlug).sort()).toEqual([
+      "__events.auth.user.signed-up.blog",
+      "__events.auth.user.signed-up.marketing-pages",
+    ]);
+    expect(queue.enqueued[0]!.input).toEqual({ userId: "u1" });
+  });
+
+  it("enqueues nothing when no subscribers are registered", async () => {
+    const queue = recordingQueue();
+    const bus = new PayloadJobsEventBus(queue);
+    await bus.publish(evt, { userId: "u1" });
+    expect(queue.enqueued).toHaveLength(0);
+  });
+});

packages/core-events/src/payload-jobs-event-bus.ts

@@ -0,0 +1,43 @@
+import type { z } from "zod";
+import type { IJobQueue } from "@repo/core-shared/jobs";
+import type { EventDescriptor } from "./event-descriptor";
+import type { EventHandler, IEventBus } from "./event-bus.interface";
+
+/**
+ * Production-grade bus: for each subscriber, enqueues one Payload task per
+ * `publish()` call. Subscribers register with their consumer-feature name so
+ * fan-out tasks are named deterministically: `__events.<event>.<consumer>`.
+ * The actual handler invocation happens inside Payload's job runner — see the
+ * matching task config generated by `gen event consume` (Task 39).
+ */
+export class PayloadJobsEventBus implements IEventBus {
+  private readonly subscribers = new Map<string, string[]>();
+
+  constructor(private readonly queue: IJobQueue) {}
+
+  async publish<T>(
+    descriptor: EventDescriptor<string, z.ZodType<T>>,
+    payload: T,
+  ): Promise<void> {
+    descriptor.schema.parse(payload);
+    const consumers = this.subscribers.get(descriptor.name) ?? [];
+    await Promise.all(
+      consumers.map((consumerFeature) =>
+        this.queue.enqueue(
+          `__events.${descriptor.name}.${consumerFeature}`,
+          payload,
+        ),
+      ),
+    );
+  }
+
+  subscribe<T>(
+    descriptor: EventDescriptor<string, z.ZodType<T>>,
+    consumerFeature: string,
+    _handler: EventHandler<T>,
+  ): void {
+    const arr = this.subscribers.get(descriptor.name) ?? [];
+    if (!arr.includes(consumerFeature)) arr.push(consumerFeature);
+    this.subscribers.set(descriptor.name, arr);
+  }
+}

packages/core-events/src/symbols.ts

@@ -0,0 +1,3 @@
+export const CORE_EVENTS_SYMBOLS = {
+  IEventBus: Symbol.for("@repo/core-events/IEventBus"),
+} as const;