@pattern-stack/codegen 0.14.2 → 0.15.1

package/package.json

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

package/runtime/subsystems/bridge/bridge-delivery-handler.ts

@@ -64,7 +64,7 @@ import {
 
 import { EVENT_BUS } from '../events/events.tokens';
 import type { IEventBus, DomainEvent } from '../events/event-bus.protocol';
-import type { EventTypeName } from '../events/generated/types';
+import type { EventTypeName } from '../events/event-registry';
 
 import {
   BRIDGE_DELIVERY_REPO,

package/runtime/subsystems/bridge/bridge-outbox-drain-hook.ts

@@ -45,7 +45,7 @@ import type {
   IBridgeOutboxDrainHook,
 } from './bridge.protocol';
 import { BRIDGE_DELIVERY_JOB_TYPE } from './bridge-delivery-handler';
-import type { EventTypeName } from '../events/generated/types';
+import type { EventTypeName } from '../events/event-registry';
 
 /** Reserved pools the wrapper rows route into; ADR-022 / ADR-024. */
 const POOL_BY_DIRECTION: Record<string, string> = {

package/runtime/subsystems/bridge/bridge.protocol.ts

@@ -29,7 +29,7 @@ import type { DrizzleTransaction, DomainEvent } from '../events/event-bus.protoc
 import type {
   EventOfType,
   EventTypeName,
-} from '../events/generated/types';
+} from '../events/event-registry';
 
 import type {
   BridgeDeliveryRecord,

package/runtime/subsystems/bridge/event-flow.service.ts

@@ -52,7 +52,7 @@ import type {
 import type {
   EventOfType,
   EventTypeName,
-} from '../events/generated/types';
+} from '../events/event-registry';
 
 import { JOB_ORCHESTRATOR } from '../jobs/jobs-domain.tokens';
 import type { IJobOrchestrator } from '../jobs/job-orchestrator.protocol';

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

@@ -0,0 +1,77 @@
+/**
+ * Augmentable domain-event registry (ADR-037, package-mode trigger typing).
+ *
+ * This is the seam that lets the bridge + job-trigger types see a PACKAGE-MODE
+ * consumer's OWN events with full per-event payload typing — without the
+ * package shipping (and leaking) its internal test-fixture event union.
+ *
+ * ── The problem ──────────────────────────────────────────────────────────────
+ * In vendored mode, `bridge.protocol.ts` / `job-handler.base.ts` could import
+ * `EventTypeName` / `EventOfType` straight from the consumer's vendored
+ * `./generated/types` (a sibling file). In package mode the runtime is consumed
+ * from the published `@pattern-stack/codegen`, whose bundled
+ * `events/generated/types.ts` is the codegen-patterns repo's OWN fixture union
+ * (`contact_created`, `deal_created`, …). Keying the bridge/trigger types off
+ * THAT union rejects the consumer's events (`'inbound_webhook_received' is not
+ * assignable to '"contact_created" | …'`).
+ *
+ * ── The fix ──────────────────────────────────────────────────────────────────
+ * `EventTypeName` (as used by the bridge/trigger types) derives from an EMPTY,
+ * augmentable `DomainEventRegistry` interface instead of the bundled concrete
+ * union. A package-mode consumer's generated events code emits a
+ * `declare module '@pattern-stack/codegen/runtime/subsystems/events/index' {
+ *    interface DomainEventRegistry { <their_event>: <TheirEvent>; … } }`
+ * augmentation, so in the consumer's tsc program `keyof DomainEventRegistry`
+ * picks up THEIR events and `EventOfType<T>` resolves THEIR concrete payloads.
+ *
+ * In the package's OWN program (and any consumer that authors no events) the
+ * interface is never augmented, so `keyof DomainEventRegistry` is `never` and
+ * `EventTypeName` falls back to `string` — the bridge/trigger types degrade to
+ * `Record<string, …>` / `(event: DomainEvent) => …`, exactly the loose-but-
+ * sound shape that keeps the package's fixture-based runtime tests green.
+ *
+ * The bundled `events/generated/{types,bus,schemas}.ts` keep their concrete
+ * fixture union locally (the bundled `TypedEventBus` keys off `./types`, NOT
+ * this file), so they do NOT augment `DomainEventRegistry` and never leak the
+ * fixtures into a consumer's `EventTypeName` — even though the consumer pulls
+ * `generated/types.d.ts` in transitively via the events index barrel.
+ */
+import type { DomainEvent } from './event-bus.protocol';
+
+/**
+ * Empty marker interface, augmented by a consumer's generated events code via
+ * declaration merging on the events index module specifier
+ * (`@pattern-stack/codegen/runtime/subsystems/events/index`). Each key is an
+ * event `type` literal; each value is the event's concrete interface (extends
+ * `DomainEvent`). Empty in the package and in any project that declares no
+ * `events/*.yaml`.
+ *
+ * Intentionally NOT augmented by the package's own bundled
+ * `events/generated/types.ts` — those fixtures stay local to the bundled
+ * `TypedEventBus` so they never widen a consumer's `EventTypeName`.
+ *
+ * Must be an `interface` (only interfaces merge across module boundaries) and
+ * empty by design — a consumer augments it via declaration merging.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface DomainEventRegistry {}
+
+/**
+ * Union of registered event `type` literals. When the registry is augmented
+ * (package-mode consumer with events) this is their event-type union; when it's
+ * empty (the package itself, or a no-events project) it falls back to `string`
+ * so the bridge/trigger types stay sound rather than collapsing to `never`.
+ */
+export type EventTypeName = keyof DomainEventRegistry extends never
+  ? string
+  : keyof DomainEventRegistry & string;
+
+/**
+ * The concrete event interface for a given `type`. Resolves to the consumer's
+ * registered interface when the registry knows `T`; otherwise (the fallback
+ * `string` case, or an unregistered literal) widens to the structural
+ * `DomainEvent` base so `event.type` / `event.id` / `event.payload` are still
+ * typed (payloads as `Record<string, unknown>`).
+ */
+export type EventOfType<T extends EventTypeName> =
+  T extends keyof DomainEventRegistry ? DomainEventRegistry[T] : DomainEvent;

package/runtime/subsystems/events/events.module.ts

@@ -44,7 +44,7 @@
  * `new Class()` which silently left `db` / `redisUrl` undefined
  * (issue #108).
  */
-import { Module, type DynamicModule, type Provider } from '@nestjs/common';
+import { Module, type DynamicModule, type Provider, type Type } from '@nestjs/common';
 import {
   EVENT_BUS,
   EVENT_READ_PORT,
@@ -112,6 +112,31 @@ export interface EventsModuleOptions {
    * Defaults to `false`.
    */
   multiTenant?: boolean;
+  /**
+   * The generated `TypedEventBus` class to bind to `TYPED_EVENT_BUS`.
+   *
+   * **Package mode (ADR-037).** When the runtime is imported from
+   * `@pattern-stack/codegen` (not vendored), the bundled `./generated/bus`
+   * `TypedEventBus` is typed to an EMPTY event union and reads the bundled
+   * empty `eventRegistry` — a consumer's `events/*.yaml` are scanned into
+   * `src/generated/events/bus.ts` (typed to THEIR union, reading THEIR
+   * registry), which the package can't import. The generated subsystem barrel
+   * therefore threads that class in here:
+   * `EventsModule.forRoot({ ..., typedBus: TypedEventBus })`. Nest constructs
+   * it with this module's `EVENT_BUS` + `EVENTS_MULTI_TENANT` providers (the
+   * generated class injects the same string-valued tokens, which match across
+   * the package boundary).
+   *
+   * Omitted (vendored mode / tests) ⇒ falls back to the bundled
+   * `./generated/bus`, which in a vendored tree IS the consumer's generated
+   * file. Without this, a package-mode consumer's typed `publish<'…'>()` calls
+   * resolve against the empty union and their events never get the right
+   * `pool` / `direction` stamped.
+   *
+   * Only consulted by `forRoot` (the path the barrel emits); `forRootAsync`
+   * keeps the bundled bus.
+   */
+  typedBus?: Type<unknown>;
 }
 
 export interface EventsModuleAsyncOptions {
@@ -125,10 +150,18 @@ export interface EventsModuleAsyncOptions {
  * binding, and the resolved `EVENTS_MULTI_TENANT` flag. Returned from one
  * place so every `forRoot` branch and `forRootAsync` agree.
  */
-function buildTypedBusProviders(multiTenant: boolean): Provider[] {
+function buildTypedBusProviders(
+  multiTenant: boolean,
+  typedBus?: Type<unknown>,
+): Provider[] {
+  // Package mode threads the consumer's generated `TypedEventBus` (typed to
+  // their event union, reading their registry) via `typedBus`; vendored mode
+  // omits it and we fall back to the bundled `./generated/bus` (which IS the
+  // consumer's generated file in a vendored tree). See `EventsModuleOptions.typedBus`.
+  const BusClass = typedBus ?? TypedEventBus;
   return [
-    TypedEventBus,
-    { provide: TYPED_EVENT_BUS, useExisting: TypedEventBus },
+    BusClass,
+    { provide: TYPED_EVENT_BUS, useExisting: BusClass },
     { provide: EVENTS_MULTI_TENANT, useValue: multiTenant },
   ];
 }
@@ -249,7 +282,7 @@ export class EventsModule {
             },
             inject: [REDIS_URL],
           },
-          ...buildTypedBusProviders(multiTenant),
+          ...buildTypedBusProviders(multiTenant, options.typedBus),
         ],
         exports: [EVENT_BUS, TYPED_EVENT_BUS, EVENTS_MULTI_TENANT],
       };
@@ -270,7 +303,7 @@ export class EventsModule {
         // IEventReadPort on the same instance as EVENT_BUS. The redis
         // backend retains no history and does not provide this token.
         { provide: EVENT_READ_PORT, useExisting: EVENT_BUS },
-        ...buildTypedBusProviders(multiTenant),
+        ...buildTypedBusProviders(multiTenant, options.typedBus),
       ],
       exports: [EVENT_BUS, EVENT_READ_PORT, TYPED_EVENT_BUS, EVENTS_MULTI_TENANT],
     };

package/runtime/subsystems/events/index.ts

@@ -4,6 +4,18 @@
  * Import the module in AppModule, inject the bus via EVENT_BUS token.
  */
 export type { DomainEvent, IEventBus, DrizzleTransaction } from './event-bus.protocol';
+// Augmentable event registry (ADR-037, package-mode trigger typing). A
+// package-mode consumer's generated events code augments `DomainEventRegistry`
+// via `declare module '@pattern-stack/codegen/runtime/subsystems/events/index'`
+// so the bridge + job-trigger types pick up THEIR events with full payload
+// typing. `EventTypeName` / `EventOfType` are re-exported here (the public
+// barrel is the stable augmentation target); they derive from the registry, NOT
+// the bundled fixture union the generated `./generated/types` re-export carries.
+export type {
+  DomainEventRegistry,
+  EventTypeName,
+  EventOfType,
+} from './event-registry';
 export type {
   IEventReadPort,
   ListEventsQuery,

package/runtime/subsystems/jobs/job-handler.base.ts

@@ -17,7 +17,7 @@
 // TODO(logging-subsystem): swap to ILogger once ADR-028 lands
 import type { Logger } from '@nestjs/common';
 import { tokenKey } from '../token-key';
-import type { EventOfType, EventTypeName } from '../events/generated/types';
+import type { EventOfType, EventTypeName } from '../events/event-registry';
 import type { JobRun } from './job-orchestrator.protocol';
 
 // ─── ParentClosePolicy ──────────────────────────────────────────────────────