agentic-dev/docs/superpowers/specs/2026-05-08-events-and-jobs-design.md

# Cross-feature events and background jobs — Design

**Date:** 2026-05-08
**Status:** Draft (pending user review)
**Supersedes:** the deferred placeholders at `docs/architecture/vertical-feature-spec.md:260` ("No `effects/`, `jobs/`, `events/` unless the feature grows them") and `:662` ("no `core-events` package yet; spec addendum v4's optional `core-events` stays deferred").
**Companion ADR:** ADR-015 (to be created during implementation; this spec is the long-form design that ADR-015 distills).

---

## 1. Context and motivation

This template currently has no convention for two real architectural concerns:

- **Cross-feature reactions.** Boundary rules forbid `feature → feature` imports (R6 in `AGENTS.md`). When `auth` should trigger work in `marketing-pages` (e.g. send a welcome email after sign-up), there is no documented seam. Today the only options are smell (illegal imports) or absence (the reaction can't be expressed cleanly).
- **Deferred / scheduled / retryable work.** Use cases run synchronously on the request path. There is no documented place for work that needs durability, retries, scheduling, or rate-shaping. Payload 3.x ships a built-in jobs queue (`payload.jobs`), but the template has no convention for *where* job code lives in a feature, *how* it is wired through DI and the span+capture sandwich, or *how* it is triggered.

This spec defines both, in one document, because they share machinery (factory + sandwich, dev/prod parity via `bindAll()`, recording-test rules) and a conceptual model (typed dispatch through a core abstraction). The two concerns are kept conceptually distinct via three load-bearing rules below.

---

## 2. Conceptual model and rules

### 2.1 What events and jobs are *for*

| | Event | Job |
|---|---|---|
| **Purpose** | A feature publishes a domain fact (e.g. `auth.user.signed-up`). Other features may react. | Deferred / scheduled / retryable work, owned and triggered by one feature. |
| **Caller** | Always the publishing feature's own use case, after it succeeds. | Any use case, controller, cron schedule, admin UI, or another job. |
| **Audience** | 0..N other features, unknown to the publisher. | One feature (itself). |
| **Transport** | `IEventBus` (in-memory in dev/test, Payload-jobs fan-out in prod). | `IJobQueue` (in-memory in dev/test, Payload jobs in prod). |
| **Why it exists** | Cross-feature decoupling — boundary rules forbid feature → feature imports, so we need a seam. | Durability, retries, scheduling, rate-shaping, getting work off the request path. |

### 2.2 The three rules

These are the load-bearing discipline; everything mechanical follows from them.

- **Rule E0 — Events are for cross-feature decoupling.** If the reaction lives in the *same* feature, do not use the bus. Just call another use case. The bus is a seam, not a router.
- **Rule E1 — Event contracts are exported; handlers are private.** A feature's `events/<name>.event.ts` is re-exported from the package root (already where contracts live per R18–R21). A feature's `events/handlers/*.handler.ts` is wired only inside that feature's own `bind-production` / `bind-dev-seed` and is never re-exported from any subpath.
- **Rule J0 — Jobs are for *deferred* work, not abstraction.** If you can do the work synchronously in the request path and it doesn't need retries, durability, or scheduling, do not make it a job. A job has operational cost (admin UI noise, retry semantics, eventual consistency) that synchronous code does not.

These rules go verbatim into ADR-015 and into `AGENTS.md` § Per-Package Conventions.

### 2.3 The seam (cross-feature event flow)

```
publisher (auth)                                consumer (marketing-pages)
─────────────────                                ──────────────────────────
events/user-signed-up.event.ts                   events/handlers/on-auth-user-signed-up.handler.ts
  └── re-exported from @repo/auth root      ←──    imports contract from @repo/auth (root, allowed)

         publishes via                                    subscribes via
         IEventBus (core-events)                          IEventBus (core-events)
                ↘                                       ↙
                       @repo/core-events bus
```

The publisher never knows the consumer exists. The consumer imports only the publisher's *contract* (event name + payload schema), which already lives behind the root export. The existing ESLint boundary rules permit this — no new boundary rule is required for the cross-feature event flow.

---

## 3. New and extended packages

### 3.1 `@repo/core-events` (new)

A new package, tagged `core` in the boundary rules, owns the bus abstraction and its two implementations.

```
packages/core-events/
  src/
    event-descriptor.ts        # defineEvent(name, schema), EventDescriptor<TName, TSchema>
    event-bus.interface.ts     # IEventBus
    in-memory-event-bus.ts     # InMemoryEventBus (dev/test)
    in-memory-event-bus.test.ts
    payload-jobs-event-bus.ts  # PayloadJobsEventBus (prod)
    payload-jobs-event-bus.test.ts
    symbols.ts                 # CORE_EVENTS_SYMBOLS.IEventBus
    index.ts                   # public surface
  package.json
  tsconfig.json
  vitest.config.ts
  eslint.config.js
  AGENTS.md
```

`core-events` is intentionally a separate package, not folded into `core-shared`, because:

- `core-shared` owns *primitives* (Zod, env, instrumentation, tRPC init). `core-events` owns *infrastructure*.
- The Payload-jobs-backed bus implementation depends on `payload`. `core-shared` does not.
- A future bus replacement (Kafka, NATS, etc.) is one-package swap — easy to spot and easy to test.

Boundary tag: **core**. Allowed dependents: `feature`, `core`, `core-composition`, `app` (everything that may already depend on `core`). Allowed dependencies: `core-shared`, `tooling`.

### 3.2 `@repo/core-shared/jobs/` (extension)

`core-shared` gains a `jobs/` subdirectory with the queue abstraction:

```
packages/core-shared/src/jobs/
  job-queue.interface.ts       # IJobQueue
  in-memory-job-queue.ts       # InMemoryJobQueue
  payload-job-queue.ts         # PayloadJobQueue
  symbols.ts                   # CORE_SHARED_JOBS_SYMBOLS.IJobQueue
  index.ts                     # exported via @repo/core-shared/jobs subpath
```

A new public subpath export `@repo/core-shared/jobs` is added (`./jobs` in `package.json` exports map). This keeps the queue addressable from features without dragging Payload into `core-shared`'s root import surface.

Boundary effect: none. `core-shared` was already `core`-tagged; the new subpath is a cosmetic extension of the existing public API.

### 3.3 Interfaces — exact shapes

```ts
// packages/core-events/src/event-descriptor.ts
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 };
}
```

```ts
// packages/core-events/src/event-bus.interface.ts
import type { z } from "zod";
import type { EventDescriptor } from "./event-descriptor";

export type EventHandler<T> = (event: T) => Promise<void>;

export interface IEventBus {
  publish<T>(
    descriptor: EventDescriptor<string, z.ZodType<T>>,
    payload: T,
  ): Promise<void>;

  subscribe<T>(
    descriptor: EventDescriptor<string, z.ZodType<T>>,
    handler: EventHandler<T>,
  ): void;
}
```

```ts
// packages/core-shared/src/jobs/job-queue.interface.ts
export interface IJobQueue {
  enqueue<T>(
    taskSlug: string,
    input: T,
    options?: { runAt?: Date },
  ): Promise<{ jobId: string }>;
}
```

The bus is generic over the schema's inferred type, so `bus.publish(userSignedUpEvent, payload)` infers `payload`'s type from `userSignedUpEvent.schema` and rejects mismatches at compile time.

The queue is intentionally minimal — a single `enqueue` method with optional `runAt`. Cron schedules live in the Payload jobs config (in `core-cms`'s `buildConfig`), not in this interface.

---

## 4. Per-feature folder layout

A feature that uses events and/or jobs has these additional directories (all optional; absent if unused):

```
packages/<feature>/src/
  events/
    <event-name>.event.ts            # publisher: contract (Zod + defineEvent)
    <event-name>.event.test.ts
    handlers/
      on-<publisher>-<event>.handler.ts        # consumer: factory
      on-<publisher>-<event>.handler.test.ts
  jobs/
    <job-name>.job.ts                # factory + Zod schema
    <job-name>.job.test.ts
  integrations/cms/jobs/
    <job-name>.task.ts               # Payload TaskConfig glue
    index.ts                         # barrel for core-cms aggregation
```

Naming rules — keep file names and wire names consistent but distinct:

- **Event contract file name:** `<event-kebab>.event.ts`, all-kebab (e.g. `user-signed-up.event.ts`).
- **Event name on the wire:** `<feature>.<event-dotted>` where `<event-dotted>` is past-tense, dot-separated (e.g. `auth.user.signed-up`). The file `user-signed-up.event.ts` defines the event named `auth.user.signed-up`.
- **Event handler file name:** `on-<publisher>-<event-kebab>.handler.ts` where `<event-kebab>` matches the publisher's contract file (e.g. `on-auth-user-signed-up.handler.ts` consumes `auth.user.signed-up`). Publisher prefix is **mandatory** to keep handler names unique when one consumer subscribes to events from multiple publishers.
- **Job file name:** `<job-kebab>.job.ts`, verb-noun kebab (e.g. `send-welcome-email.job.ts`).
- **Job slug on the wire:** `<feature>.<job-kebab>` (e.g. `marketing-pages.send-welcome-email`).

---

## 5. File shapes

### 5.1 Event contract (publisher)

```ts
// packages/auth/src/events/user-signed-up.event.ts
import { z } from "zod";
import { defineEvent } from "@repo/core-events";

export const userSignedUpEventSchema = z
  .object({
    userId: z.string(),
    email: z.string().email(),
    signedUpAt: z.string().datetime(),
  })
  .strict();

export type UserSignedUpEvent = z.infer<typeof userSignedUpEventSchema>;

export const userSignedUpEvent = defineEvent(
  "auth.user.signed-up",
  userSignedUpEventSchema,
);
```

Re-exported from `packages/auth/src/index.ts`:

```ts
// <gen:events>
export {
  userSignedUpEvent,
  userSignedUpEventSchema,
  type UserSignedUpEvent,
} from "./events/user-signed-up.event";
```

The `// <gen:events>` anchor comment is part of the generator protocol (§ 9).

### 5.2 Publisher use case

```ts
// packages/auth/src/application/use-cases/sign-up.use-case.ts
import type { IEventBus } from "@repo/core-events";
import { userSignedUpEvent } from "../../events/user-signed-up.event";

export const signUpUseCase =
  (users: IUsersRepository, bus: IEventBus) =>
  async (input: SignUpInput): Promise<SignUpOutput> => {
    const user = await users.create(input);
    await bus.publish(userSignedUpEvent, {
      userId: user.id,
      email: user.email,
      signedUpAt: new Date().toISOString(),
    });
    return signUpOutputSchema.parse(user);
  };
```

The use-case factory gains a `bus: IEventBus` constructor parameter. The publisher always `await`s `publish`. What the bus does with the await is the bus's call (in-memory: synchronous fan-out; Payload-jobs: returns after enqueue, not after delivery). The publisher's contract is "I told the bus."

DI binding for this use case is updated to inject the bus:

```ts
bind<ISignUpUseCase>(AUTH_SYMBOLS.ISignUpUseCase)
  .toDynamicValue((ctx) =>
    withSpan(
      tracer,
      { name: "auth.signUp", op: "use-case" },
      withCapture(
        logger,
        { feature: "auth", layer: "use-case", name: "auth.signUp" },
        signUpUseCase(
          ctx.container.get(AUTH_SYMBOLS.IUsersRepository),
          ctx.container.get(CORE_EVENTS_SYMBOLS.IEventBus),
        ),
      ),
    ),
  );
```

### 5.3 Event handler (consumer)

```ts
// packages/marketing-pages/src/events/handlers/on-auth-user-signed-up.handler.ts
import type { UserSignedUpEvent } from "@repo/auth";
import type { IJobQueue } from "@repo/core-shared/jobs";

export type IOnAuthUserSignedUpHandler = ReturnType<typeof onAuthUserSignedUpHandler>;

export const onAuthUserSignedUpHandler =
  (queue: IJobQueue) =>
  async (event: UserSignedUpEvent): Promise<void> => {
    await queue.enqueue("marketing-pages.send-welcome-email", {
      userId: event.userId,
      email: event.email,
    });
  };
```

The handler imports `UserSignedUpEvent` from `@repo/auth` (root, allowed). It is a factory of shape `(deps) => async (event: T) => Promise<void>` — same shape as a use case, but with `void` return and no presenter.

### 5.4 Subscription (consumer's `bind-*`)

```ts
// packages/marketing-pages/src/di/bind-production.ts (excerpt)
export function bindProductionMarketingPages(config: SanitizedConfig): void {
  const container = getMarketingPagesContainer(config);
  // ... repository bindings (existing) ...

  const tracer = container.get<ITracer>(INSTRUMENTATION_SYMBOLS.TRACER);
  const logger = container.get<ILogger>(INSTRUMENTATION_SYMBOLS.LOGGER);
  const bus = container.get<IEventBus>(CORE_EVENTS_SYMBOLS.IEventBus);
  const queue = container.get<IJobQueue>(CORE_SHARED_JOBS_SYMBOLS.IJobQueue);

  // <gen:event-handlers>
  const onAuthUserSignedUp = withSpan(
    tracer,
    { name: "marketing-pages.onAuthUserSignedUp", op: "event-handler" },
    withCapture(
      logger,
      {
        feature: "marketing-pages",
        layer: "event-handler",
        name: "marketing-pages.onAuthUserSignedUp",
      },
      onAuthUserSignedUpHandler(queue),
    ),
  );
  bus.subscribe(userSignedUpEvent, onAuthUserSignedUp);
}
```

The handler is wrapped in the **same span+capture sandwich** as use cases (R41–R44 from `docs/decisions/adr-014-instrumentation-sentry.md`), with two new tag values: `op: "event-handler"`, `layer: "event-handler"`. The `// <gen:event-handlers>` anchor marks where `gen event consume` inserts new blocks.

**Note on `bind-*` side effects.** Today the `bindProduction<Feature>` / `bindDevSeed<Feature>` functions are pure container-modification: they only call `container.bind(...)`. With this spec, they additionally call `bus.subscribe(...)` for each event handler the feature consumes. This is still boot-time-only wiring (the binders run once during `bindAll()`), but it is a small departure worth flagging. The binders remain idempotent: calling `bindAll()` twice is incorrect today and remains incorrect after this change.

### 5.5 Job

```ts
// packages/marketing-pages/src/jobs/send-welcome-email.job.ts
// Illustrative — assumes a future mailer service exists in marketing-pages.
// The shipped end-to-end test in § 13 substitutes a recording mailer.
import { z } from "zod";
import type { IMailerService } from "../application/services/mailer.service.interface";

export const sendWelcomeEmailInputSchema = z
  .object({ userId: z.string(), email: z.string().email() })
  .strict();
export type SendWelcomeEmailInput = z.infer<typeof sendWelcomeEmailInputSchema>;
export type ISendWelcomeEmailJob = ReturnType<typeof sendWelcomeEmailJob>;

export const sendWelcomeEmailJob =
  (mailer: IMailerService) =>
  async (input: SendWelcomeEmailInput): Promise<void> => {
    sendWelcomeEmailInputSchema.parse(input); // queue payload arrives as unknown
    await mailer.sendWelcome(input.userId, input.email);
  };
```

Differences from a use case:

- **Boundary parse at the top** of the body. The queue payload arrives as `unknown` (from a serialized JSON column), so the job parses it itself — same role `safeParse` plays in a controller.
- **No output schema and no presenter.** Jobs are fire-and-forget; what they return goes to the queue's bookkeeping, not to a caller.
- **Same factory + sandwich wiring** at DI bind time.

### 5.6 Payload task glue

```ts
// packages/marketing-pages/src/integrations/cms/jobs/send-welcome-email.task.ts
import type { TaskConfig } from "payload";
import { getMarketingPagesContainer } from "../../../di/container";
import { MARKETING_PAGES_SYMBOLS } from "../../../di/symbols";
import type { ISendWelcomeEmailJob } from "../../../jobs/send-welcome-email.job";

export const sendWelcomeEmailTask: TaskConfig<"marketing-pages.send-welcome-email"> = {
  slug: "marketing-pages.send-welcome-email",
  inputSchema: [
    /* Payload field config matching the Zod schema */
  ],
  retries: { attempts: 3, backoff: { type: "exponential", delay: 1000 } },
  handler: async ({ req, input }) => {
    const handler = getMarketingPagesContainer(req.payload.config).get<ISendWelcomeEmailJob>(
      MARKETING_PAGES_SYMBOLS.ISendWelcomeEmailJob,
    );
    await handler(input);
    return { output: {} };
  },
};
```

Re-exported from `packages/marketing-pages/src/integrations/cms/index.ts` alongside collections, behind the `// <gen:job-tasks>` anchor. `core-cms` then aggregates them:

```ts
// packages/core-cms/src/index.ts (excerpt)
import {
  pagesCollection,
  siteSettingsGlobal,
  sendWelcomeEmailTask,
} from "@repo/marketing-pages/cms";

export default buildConfig({
  collections: [pagesCollection /* , ... */],
  globals: [siteSettingsGlobal /* , ... */],
  jobs: { tasks: [sendWelcomeEmailTask /* , ... */] },
});
```

No new subpath, no new boundary rule. `./cms` does the same job for tasks that it already does for collections.

---

## 6. Bus and queue implementations

### 6.1 Two bus implementations, swapped by `bindAll()`

| Implementation | Behavior | Default for |
|---|---|---|
| `InMemoryEventBus` | Validates payload via `descriptor.schema.parse`, then `await Promise.allSettled(handlers)`. Publisher's `publish` resolves after all handlers settle. Per-handler errors are captured by each handler's own sandwich (`withCapture`) and **swallowed by the bus** (publisher never sees them). One config knob: `failFast: boolean` (default `false`) for tests that want to assert handler failures bubble. | dev, tests, `pnpm dev` |
| `PayloadJobsEventBus` | Validates payload, then enqueues one Payload task per subscriber (`__events.<event-name>.<consumer-feature>`). `publish` returns after enqueue, not after delivery. Retries + durability come from Payload. | production |

**Decision: swallow vs failFast in dev/test.** Swallow by default because:

1. Mirrors production semantics — `PayloadJobsEventBus` is async; a publisher in prod never sees a downstream handler error, so dev should match.
2. Per-handler sandwiches already capture and report errors via `logger.captureException`. The publisher does not need to re-handle them.
3. Tests that *want* to assert handler failure pass `failFast: true` to the bus constructor — explicit opt-in.

### 6.2 Two queue implementations, swapped by `bindAll()`

| Implementation | Behavior | Default for |
|---|---|---|
| `InMemoryJobQueue` | Resolves the task's handler from the local container and runs it on `setImmediate`. Honors `runAt` via `setTimeout`. Returns a synthetic `jobId`. | dev, tests |
| `PayloadJobQueue` | Wraps `payload.jobs.queue({ task, input, waitUntil: options?.runAt })`. Returns the Payload job id. | production |

### 6.3 Selection rule (extends existing `bindAll()`)

The existing app-level `bindAll()` dispatcher (in `apps/web-next/src/server/bind-production.ts`) gains a new bus/queue swap step that runs **before** any per-feature binder (so per-feature binders can `container.get<IEventBus>(...)` without ambiguity). It is independent of, and runs alongside, the existing Rule 0 (DSN → Sentry vs Noop instrumentation). Both the bus and the queue follow the same three-mode rule the repositories already use:

- `USE_DEV_SEED === "true"` → `InMemoryEventBus` + `InMemoryJobQueue` (any `NODE_ENV`)
- `NODE_ENV === "production"` → `PayloadJobsEventBus` + `PayloadJobQueue`
- otherwise → `InMemoryEventBus` + `InMemoryJobQueue` (developer default)

This means `pnpm dev` boots without Payload and events/jobs still work end-to-end, and `USE_DEV_SEED=true pnpm start` (or any prod-build smoke test) works without a Payload connection. Same trick that makes the existing repository binding work today.

### 6.4 Why `IJobQueue` lives in `core-shared` and `IEventBus` lives in `core-events`

- **`IJobQueue` works standalone.** A feature can have jobs without ever publishing or subscribing to events. Putting the queue in `core-shared` keeps simple cases simple — features only depend on `core-events` if they actually use the bus.
- **The bus depends on the queue (in production).** `PayloadJobsEventBus` enqueues subscriber tasks via `IJobQueue`. `core-events` therefore depends on `core-shared` — the existing direction (`core` may depend on `core`).
- **A future bus replacement does not affect the queue.** If `core-events` swaps to a non-Payload bus (Kafka, NATS), `IJobQueue` is unaffected.

---

## 7. Boundary rules and ESLint

Three new ESLint rules in `@repo/core-eslint`:

1. **No handler re-exports.** Files matching `**/events/handlers/*.handler.ts` may not appear in any `export from` or `export *` statement in any `index.ts` or barrel file. Custom rule, ~20 LOC. Enforces Rule E1.
2. **No direct `payload.jobs` outside the integration layer.** `payload.jobs` member access is forbidden outside `**/integrations/cms/jobs/**` and `packages/core-shared/src/jobs/**`. Use cases / controllers / repositories / event handlers must use `IJobQueue`. Custom rule, ~15 LOC.
3. **R40 allowlist confirmation.** The existing R40 rule (no `@sentry/*` in feature code) is verified to cover `events/`, `events/handlers/`, and `jobs/` — they are *not* added to the allowlist.

The existing five-tag boundary system already covers everything else:

- `feature → core-events` (allowed: feature → core)
- `feature → core-shared/jobs` (allowed: feature → core)
- `feature consumer → @repo/<feature publisher>` for event contracts (allowed only for the root subpath, which is contracts-only per R18–R21)
- `core-events → core-shared` (allowed: core → core)
- `core-events` cannot import from any feature (allowed: core forbids feature)

No new tag, no new package-level rule. Only the three custom-rule additions above.

---

## 8. Testing

`@repo/core-testing/instrumentation` gains two recordings:

```ts
// packages/core-testing/src/instrumentation/recording-event-bus.ts
export class RecordingEventBus implements IEventBus {
  readonly published: { name: string; payload: unknown }[] = [];
  private handlers = new Map<string, EventHandler<unknown>[]>();

  async publish<T>(d: EventDescriptor<string, z.ZodType<T>>, payload: T): Promise<void> {
    d.schema.parse(payload);
    this.published.push({ name: d.name, payload });
    for (const h of this.handlers.get(d.name) ?? []) await h(payload);
  }

  subscribe<T>(d: EventDescriptor<string, z.ZodType<T>>, h: EventHandler<T>): void {
    const arr = this.handlers.get(d.name) ?? [];
    arr.push(h as EventHandler<unknown>);
    this.handlers.set(d.name, arr);
  }
}
```

```ts
// packages/core-testing/src/instrumentation/recording-job-queue.ts
export class RecordingJobQueue implements IJobQueue {
  readonly enqueued: { taskSlug: string; input: unknown; options?: { runAt?: Date } }[] = [];

  async enqueue<T>(taskSlug: string, input: T, options?: { runAt?: Date }) {
    this.enqueued.push({ taskSlug, input, options });
    return { jobId: `recording-${this.enqueued.length}` };
  }
}
```

| Test | Strategy |
|---|---|
| Publisher use case publishes the right event | Inject `RecordingEventBus`, assert `bus.published[0]` matches. |
| Consumer handler does its job | Call factory with mocks, pass an event payload directly. No bus involved. |
| Subscription is wired | One per-feature integration test: instantiate `InMemoryEventBus`, run `bindDevSeed<Feature>(bus, queue)`, publish, assert handler side effect. |
| Job factory does its job | Identical to a use-case test. |
| Use case enqueues a job | Inject `RecordingJobQueue`, assert `queue.enqueued[0]` matches. |
| Schema enforcement at the bus | Pass an invalid payload; assert `publish` throws `ZodError`, captured by the publisher's `withCapture`. |

The `bindDevSeed<Feature>` signature gains optional `bus` and `queue` parameters (defaulted to fresh in-memory instances) so feature integration tests can substitute recordings.

---

## 9. Generators

Two new Plop generators in `turbo/generators/config.ts`, alongside the existing `feature` generator. Both **augment an existing feature package** (rather than creating a new one) using a mix of Plop `add` and `modify` actions.

### 9.1 The anchor-comment protocol

A new convention introduced by this spec: six stable single-line anchor comments, each marking an insertion point for a generator. Pre-existing features and the `feature` generator template are updated to include the anchors as no-op comments, so all features have them from day one regardless of whether they currently use events or jobs.

| Anchor | File | Inserted by |
|---|---|---|
| `// <gen:events>` | `src/index.ts` | `gen event publish` |
| `// <gen:event-handler-symbols>` | `src/di/symbols.ts` | `gen event consume` |
| `// <gen:event-handlers>` | `src/di/bind-production.ts`, `bind-dev-seed.ts` | `gen event consume` |
| `// <gen:job-tasks>` | `src/integrations/cms/index.ts` | `gen job` |
| `// <gen:job-symbols>` | `src/di/symbols.ts` | `gen job` |
| `// <gen:jobs>` | `src/di/bind-production.ts`, `bind-dev-seed.ts` | `gen job` |

Files without the required anchor cause the generator to abort with a clear `missing // <gen:xxx> anchor in <file>` error before writing partial output.

### 9.2 `pnpm turbo gen event`

A single generator with a `mode` prompt. Prompts and validation:

| Prompt | Validation | Used for |
|---|---|---|
| `mode` | `publish` \| `consume` | Branch logic |
| `feature` | kebab-case, `packages/<feature>/src/` must exist | Where the file is generated |
| `event` | dotted-kebab past tense (`user.signed-up`) | Event slug — full name becomes `<feature>.<event>` (publish) or `<publisher>.<event>` (consume) |
| `publisher` (consume only) | kebab-case, `packages/<publisher>/src/events/<event>.event.ts` must exist | Import path for the contract |

**Publish mode** emits:

- `packages/<feature>/src/events/<event>.event.ts` (Zod schema + `defineEvent`; schema body is a `z.object({}).strict()` stub)
- `packages/<feature>/src/events/<event>.event.test.ts`
- `modify` `packages/<feature>/src/index.ts` — re-export the contract behind `// <gen:events>`

It does **not** modify any use case. Wiring `bus: IEventBus` into a use-case factory is a manual edit because the user picks which use case publishes; the printed next-steps block walks through that edit.

**Consume mode** emits:

- `packages/<feature>/src/events/handlers/on-<publisher>-<event-kebab>.handler.ts`
- `packages/<feature>/src/events/handlers/on-<publisher>-<event-kebab>.handler.test.ts`
- `modify` `packages/<feature>/src/di/symbols.ts` — add `IOn<...>Handler` symbol behind `// <gen:event-handler-symbols>`
- `modify` `packages/<feature>/src/di/bind-production.ts` and `bind-dev-seed.ts` — add `bus.subscribe(...)` block with the span+capture sandwich behind `// <gen:event-handlers>`

### 9.3 `pnpm turbo gen job`

Prompts:

| Prompt | Validation | Used for |
|---|---|---|
| `feature` | kebab-case, must exist | Where the job lives |
| `job` | verb-noun kebab (`send-welcome-email`) | Slug becomes `<feature>.<job>` |
| `inputShape` | `void` \| `typed` | `z.object({}).strict()` (void) or stub with one example field (typed) |

Emits:

- `packages/<feature>/src/jobs/<job>.job.ts`
- `packages/<feature>/src/jobs/<job>.job.test.ts`
- `packages/<feature>/src/integrations/cms/jobs/<job>.task.ts`
- `modify` `packages/<feature>/src/integrations/cms/index.ts` — re-export task (`// <gen:job-tasks>`)
- `modify` `packages/<feature>/src/di/symbols.ts` — add job symbol (`// <gen:job-symbols>`)
- `modify` `packages/<feature>/src/di/bind-production.ts` and `bind-dev-seed.ts` — add factory binding with `op: "job"` sandwich (`// <gen:jobs>`)

### 9.4 Idempotency / failure modes

- **File collisions** (`add` actions) fail loudly — Plop's default. Re-running with the same slug gets a clear error.
- **Modify actions** insert at the anchor on every run. Duplicate bindings produce a TypeScript error at the next `pnpm typecheck`. Acceptable tradeoff: simple regex inserts, no AST manipulation, errors are obvious.
- **Validation order:** existence checks (feature directory, anchor presence in target files, publisher contract for consume mode) run during the `prompts` phase so the generator aborts before writing partial output.

### 9.5 What the generators do NOT do

Stays out of scope (printed in the next-steps block instead):

- Modifying the publisher use case to inject the bus (publish mode).
- Wiring custom dependencies into the handler / job factory (user edits the constructor signature manually).
- Filling in the Zod schema body or Payload `inputSchema` field config beyond a stub.
- Cron schedule definition (lives in `core-cms`'s `buildConfig`, manual edit).
- Aggregator wiring (the existing `bindAll()` in `apps/web-next/src/server/bind-production.ts` already handles per-feature binders; no per-event/per-job edits needed there).

### 9.6 Existing-feature retrofit

The five existing features (`auth`, `blog`, `media`, `marketing-pages`, `navigation`) and the `feature` generator template all gain the six anchor comments as no-op single-line comments in the appropriate files. Pure additive comment-only edits — no behavioral change. One implementation-plan task per feature plus one for the template.

---

## 10. Documentation impact

Files updated as part of this spec's implementation:

- **`AGENTS.md`** — new section under Per-Package Conventions for events and jobs (rules E0/E1/J0, folder layout, sandwich tags, `bindAll` rule, lint summary). New row in the Specification & Guides table.
- **`CLAUDE.md`** — Quick Start gains `pnpm turbo gen event` / `pnpm turbo gen job`. Read First gains a link to `docs/guides/events-and-jobs.md` (new). Key Conventions gains short bullets for E0, E1, J0.
- **`docs/guides/events-and-jobs.md`** — new long-form guide covering "publish an event", "consume an event", "add a job", with step-by-step generator-plus-manual-wiring walkthroughs.
- **`docs/guides/scaffolding-a-feature.md`** — two new sections at the bottom referencing the new generators and the events/jobs guide.
- **`docs/decisions/adr-015-events-and-jobs.md`** — new ADR distilling this spec's decisions and rules.
- **`docs/architecture/vertical-feature-spec.md`** — the deferred lines at `:260` and `:662` get updated to point at this spec instead of saying "deferred".

---

## 11. Out of scope (deferred until needed)

Each gets a one-line "deferred until needed; will be its own ADR" note in ADR-015:

- **Multi-task workflows.** Payload's `WorkflowConfig` (composing tasks with branching/retry logic). Defer until one feature has a real multi-step workflow.
- **Saga / orchestration.** Cross-feature multi-step processes with compensating actions. Defer until a real saga appears.
- **Exactly-once delivery semantics.** Current design is at-least-once for the Payload-jobs bus (each subscriber gets its own task; retries possible). If at-most-once or exactly-once is ever required, that is a new ADR with a new bus implementation.
- **Event versioning.** Schema evolution strategy (v1 / v2 event shapes, parallel publishing, consumer migration). Defer until first breaking-change need.
- **Subscriber dynamic discovery.** Currently `bus.subscribe` is called at app boot inside each consumer's `bind-production`. A feature added at runtime (plugin model) cannot subscribe. Defer.
- **`pnpm turbo gen feature --with-events --with-jobs` flags.** The Phase-1 `feature` generator stays single-purpose. If repeated patterns emerge across features, revisit.

---

## 12. Decisions locked at this stage

These are the irreversible-feeling design calls — flagged here so reviewers spot any disagreement before implementation begins:

1. **Both events and jobs in one ADR (ADR-015), not split.** They share machinery (factory + sandwich, `bindAll` rule, recording-test pattern). Splitting would force cross-references on every page.
2. **Rule E0: no in-feature events.** The bus is for cross-feature decoupling only. In-feature reactions are direct use-case calls.
3. **`@repo/core-events` is a new package, not a fold-in to `core-shared`.** Reasoning in § 3.1.
4. **`IJobQueue` lives in `core-shared/jobs/`.** Reasoning in § 6.4.
5. **In-memory bus swallows handler errors by default.** Reasoning in § 6.1.
6. **Handler files use `on-<publisher>-<event-kebab>.handler.ts`.** Publisher prefix is mandatory.
7. **Generators for event (publish/consume) and job are in scope.** Anchor-comment protocol is the convention.
8. **Existing-feature retrofit is part of the implementation plan.** All five features gain the six anchor comments as no-op edits.

---

## 13. Success criteria

The implementation is complete when:

- `pnpm turbo gen event publish` and `pnpm turbo gen event consume` run cleanly against `auth` and `marketing-pages`, producing files that pass lint + typecheck + tests on first generation.
- `pnpm turbo gen job` runs cleanly against `marketing-pages`, producing files that pass lint + typecheck + tests on first generation.
- A single end-to-end test in `apps/web-next` proves the cross-feature flow: a sign-up triggers a `marketing-pages` job that asserts a side effect against a recording mailer.
- `bindAll()` correctly swaps the bus and queue between in-memory and Payload-backed based on `USE_DEV_SEED` / `NODE_ENV`, verified by a feature integration test in each mode.
- All five existing features have the six anchor comments (verified by a tiny CI grep test).
- `AGENTS.md`, `CLAUDE.md`, `docs/guides/events-and-jobs.md`, `docs/guides/scaffolding-a-feature.md`, and `docs/decisions/adr-015-events-and-jobs.md` are written and cross-linked.
- All three new ESLint rules pass against the touched packages and reject deliberately-broken fixtures in `core-eslint`'s test suite.