@pattern-stack/codegen 0.8.0 → 0.9.0

package/runtime/subsystems/jobs/job-worker.module.ts

@@ -47,10 +47,19 @@ import type { IJobRunService } from './job-run-service.protocol';
 import type { IJobStepService } from './job-step-service.protocol';
 import {
   allNonReservedPoolNames,
+  allPoolNames,
   loadPoolConfig,
   type PoolConfig,
 } from './pool-config.loader';
 import { JobWorker, type JobWorkerOptions } from './job-worker';
+import { BullMQJobWorker } from './job-worker.bullmq-backend';
+import type { ConnectionOptions } from 'bullmq';
+import {
+  BULLMQ_CONNECTION,
+  BULLMQ_RESOLVED_CONFIG,
+  resolvePoolQueueName,
+  type BullMqResolvedConfig,
+} from './bullmq.config';
 import {
   BootValidationError,
   ReservedPoolViolationError,
@@ -62,10 +71,11 @@ export interface JobWorkerModuleOptions {
   mode: 'embedded' | 'standalone';
   /**
    * Threads into the internal `JobsDomainModule.forRoot({ backend })`
-   * import. Default `'drizzle'`. The boot-time validator runs only when
-   * this is `'drizzle'`.
+   * import. Default `'drizzle'`. The boot-time validator runs for both
+   * `'drizzle'` and `'bullmq'` (both persist `job` rows to Postgres);
+   * `'memory'` skips it.
    */
-  backend?: 'drizzle' | 'memory';
+  backend?: 'drizzle' | 'memory' | 'bullmq';
   /**
    * Active pool names. Defaults to every non-reserved pool in the resolved
    * config (i.e. `interactive`, `batch`, plus any user-defined pools).
@@ -73,6 +83,18 @@ export interface JobWorkerModuleOptions {
    * horizontally.
    */
   pools?: string[];
+  /**
+   * BULLMQ-1 Phase 1 — when `true`, `onModuleInit` activates **every** pool
+   * in the resolved config, including the reserved `events_*` lanes. This is
+   * how the standalone worker (`worker.ts`) drains bridge wrappers without
+   * the consumer hand-listing `...BRIDGE_RESERVED_POOLS`. Mutually exclusive
+   * with an explicit `pools` list — when both are set, `pools` wins (explicit
+   * beats blanket) and `allPools` is ignored.
+   *
+   * `BridgeModule`'s reserved-pool guard short-circuits to "pass" when this
+   * is `true`, since every reserved pool is provably being polled.
+   */
+  allPools?: boolean;
   /** SIGTERM drain budget. Default 30_000 ms. */
   shutdownTimeoutMs?: number;
   /**
@@ -128,6 +150,17 @@ export class JobWorkerOrchestrator implements OnModuleInit, OnModuleDestroy {
      */
     @Optional() @Inject(DRIZZLE) private readonly db: DrizzleClient | null = null,
     private readonly moduleRef?: ModuleRef,
+    /**
+     * BULLMQ-1 — resolved BullMQ connection + config, only bound when the
+     * inner `JobsDomainModule` was booted with `backend: 'bullmq'`. `@Optional()`
+     * so drizzle/memory boots see `null`.
+     */
+    @Optional()
+    @Inject(BULLMQ_CONNECTION)
+    private readonly bullConnection: ConnectionOptions | null = null,
+    @Optional()
+    @Inject(BULLMQ_RESOLVED_CONFIG)
+    private readonly bullConfig: BullMqResolvedConfig | null = null,
   ) {}
 
   // ============================================================================
@@ -166,8 +199,14 @@ export class JobWorkerOrchestrator implements OnModuleInit, OnModuleDestroy {
     }
 
     // (6) Resolve active pool list and spawn one worker per pool.
-    const activePools =
-      this.options.pools ?? allNonReservedPoolNames(poolConfig);
+    //     Precedence: explicit `pools` > `allPools` (incl. reserved) >
+    //     non-reserved default. BULLMQ-1 Phase 1 adds the `allPools` rung so
+    //     the standalone worker drains the reserved `events_*` bridge lanes.
+    const activePools = this.options.pools
+      ? this.options.pools
+      : this.options.allPools
+        ? allPoolNames(poolConfig)
+        : allNonReservedPoolNames(poolConfig);
 
     for (const poolName of activePools) {
       const def = poolConfig.get(poolName);
@@ -193,14 +232,20 @@ export class JobWorkerOrchestrator implements OnModuleInit, OnModuleDestroy {
       };
       const worker = this.options.workerFactory
         ? this.options.workerFactory(workerOptions)
-        : this.spawnWorker(workerOptions);
+        : backend === 'bullmq'
+          ? this.spawnBullMQWorker(poolName, def.queue, def.concurrency, poolConfig)
+          : this.spawnWorker(workerOptions);
       // `JobWorker` extends Nest's lifecycle hooks but the worker isn't
       // a Nest provider here (we manage the array ourselves). Call
-      // `onModuleInit` synchronously to start the polling loop.
-      worker.onModuleInit();
+      // `onModuleInit` to start the loop. The Drizzle/stub workers return
+      // void; `BullMQJobWorker.onModuleInit` is async (it lazily loads the
+      // optional `bullmq` package), so we `await` — awaiting a `void` is a
+      // harmless no-op for the synchronous workers.
+      await worker.onModuleInit();
       this.workers.push(worker);
       this.logger.log(
-        `JobWorker started: pool='${poolName}' (queue='${def.queue}') concurrency=${def.concurrency}`,
+        `JobWorker started: pool='${poolName}' (queue='${def.queue}') ` +
+          `concurrency=${def.concurrency} backend='${backend}'`,
       );
     }
   }
@@ -220,6 +265,20 @@ export class JobWorkerOrchestrator implements OnModuleInit, OnModuleDestroy {
       }
     }
     this.workers.length = 0;
+
+    // BULLMQ-1 — close the orchestrator's producer-side Queue/FlowProducer
+    // connections so the process can exit cleanly. The orchestrator is the
+    // BullMQ producer; workers are the consumers (closed above).
+    const orch = this.orchestrator as { closeConnections?: () => Promise<void> };
+    if (typeof orch.closeConnections === 'function') {
+      try {
+        await orch.closeConnections();
+      } catch (err) {
+        this.logger.error(
+          `BullMQ orchestrator connection close failed: ${(err as Error).message}`,
+        );
+      }
+    }
   }
 
   // ============================================================================
@@ -296,6 +355,54 @@ export class JobWorkerOrchestrator implements OnModuleInit, OnModuleDestroy {
       this.moduleRef,
     );
   }
+
+  /**
+   * BULLMQ-1 — spawn a per-pool `BullMQJobWorker`. Requires the Drizzle
+   * client (the worker drives `job_run` as the source of truth) AND the
+   * resolved BullMQ connection (bound by `JobsDomainModule` when
+   * `backend: 'bullmq'`). The queue name is derived identically to the
+   * orchestrator's `dispatch` via `resolvePoolQueueName(pool, …)` so producer
+   * and consumer agree.
+   */
+  private spawnBullMQWorker(
+    pool: string,
+    _queueAlias: string,
+    concurrency: number,
+    poolConfig: PoolConfig,
+  ): BullMQJobWorker {
+    if (!this.db) {
+      throw new Error(
+        `JobWorkerModule: BullMQ worker spawning requires the Drizzle client ` +
+          `(no DRIZZLE provider available) — job_run remains the source of truth.`,
+      );
+    }
+    if (!this.bullConnection) {
+      throw new Error(
+        `JobWorkerModule: BullMQ worker spawning requires a resolved ` +
+          `BULLMQ_CONNECTION. Ensure JobsDomainModule was booted with ` +
+          `backend: 'bullmq'.`,
+      );
+    }
+    if (!this.moduleRef) {
+      throw new Error(
+        `JobWorkerModule: ModuleRef not available — cannot construct ` +
+          `BullMQJobWorker with handler DI support.`,
+      );
+    }
+    const queueName = resolvePoolQueueName(pool, this.bullConfig, poolConfig);
+    return new BullMQJobWorker(
+      this.db,
+      this.orchestrator,
+      this.stepService,
+      {
+        pool,
+        queueName,
+        concurrency,
+        connection: this.bullConnection,
+      },
+      this.moduleRef,
+    );
+  }
 }
 
 @Module({})
@@ -314,7 +421,14 @@ export class JobWorkerModule {
         { provide: JOB_WORKER_MODULE_OPTIONS, useValue: opts },
         JobWorkerOrchestrator,
       ],
-      exports: [],
+      // BULLMQ-1 Phase 1 — export the options token so `BridgeModule`'s
+      // reserved-pool guard (`onModuleInit`) can actually inject it.
+      // Previously `exports: []` left the `@Optional()` inject resolving to
+      // `undefined` and the guard silently no-opped (a dead check). With the
+      // token exported the guard fires for real; consumers that omit the
+      // reserved pools (and don't set `allPools`) now fail fast with
+      // `BridgeReservedPoolsNotPolledError` — which is correct.
+      exports: [JOB_WORKER_MODULE_OPTIONS],
     };
   }
 }

package/runtime/subsystems/jobs/jobs-domain.module.ts

@@ -24,10 +24,17 @@ import {
 import { DrizzleJobOrchestrator } from './job-orchestrator.drizzle-backend';
 import { DrizzleJobRunService } from './job-run-service.drizzle-backend';
 import { DrizzleJobStepService } from './job-step-service.drizzle-backend';
+import { BullMQJobOrchestrator } from './job-orchestrator.bullmq-backend';
 import { MemoryJobOrchestrator } from './job-orchestrator.memory-backend';
 import { MemoryJobRunService } from './job-run-service.memory-backend';
 import { MemoryJobStepService } from './job-step-service.memory-backend';
 import { MemoryJobStore } from './memory-job-store';
+import {
+  BULLMQ_CONNECTION,
+  BULLMQ_RESOLVED_CONFIG,
+  resolveBullMqConfig,
+  type BullMqExtensionsConfig,
+} from './bullmq.config';
 
 /**
  * Drizzle backend extensions surface. None are wired into the Drizzle
@@ -44,19 +51,8 @@ export interface DrizzleBackendExtensions {
   pollIntervalMs?: number;
 }
 
-// Phase 6+ — typed-but-unimplemented BullMQ extension slot. Kept as a
-// commented-out interface to make the future shape discoverable without
-// shipping dead runtime code. Per CLAUDE.md "no feature-flag-guarded dead
-// code" we don't ship the option in `JobsDomainModuleOptions.extensions`
-// either; flip it on when JOB-Phase-6 lands the BullMQ orchestrator.
-//
-// export interface BullMqBackendExtensions {
-//   bullBoard?: { enabled: boolean; mountPath?: string };
-//   redisUrl?: string;
-// }
-
 export interface JobsDomainModuleOptions {
-  backend: 'drizzle' | 'memory';
+  backend: 'drizzle' | 'memory' | 'bullmq';
   /**
    * Backend-specific extensions. Only the matching backend's extensions
    * are read at boot; non-matching keys are ignored. This is the
@@ -64,7 +60,12 @@ export interface JobsDomainModuleOptions {
    */
   extensions?: {
     drizzle?: DrizzleBackendExtensions;
-    // bullmq?: BullMqBackendExtensions;   // Phase 6+
+    /**
+     * BullMQ backend extensions (BULLMQ-1). Snake_case mirrors the YAML
+     * under `jobs.extensions.bullmq`. `redis_url` falls back to
+     * `process.env.REDIS_URL` then `redis://localhost:6379`.
+     */
+    bullmq?: BullMqExtensionsConfig;
   };
   /** Multi-tenancy opt-in. Wired by JOB-8; module signature stays stable. */
   multiTenant?: boolean;
@@ -73,8 +74,6 @@ export interface JobsDomainModuleOptions {
 @Module({})
 export class JobsDomainModule {
   static forRoot(opts: JobsDomainModuleOptions): DynamicModule {
-    void opts.extensions; // typed reservation; consumed by Phase 6+ wiring
-
     const multiTenant = opts.multiTenant ?? false;
 
     const providers: Provider[] = [
@@ -98,22 +97,42 @@ export class JobsDomainModule {
       providers.push({ provide: JOB_ORCHESTRATOR, useExisting: MemoryJobOrchestrator });
       providers.push(MemoryJobRunService);
       providers.push({ provide: JOB_RUN_SERVICE, useExisting: MemoryJobRunService });
+    } else if (opts.backend === 'bullmq') {
+      // BULLMQ-1 — BullMQ orchestrator over a Postgres source of truth. The
+      // run/step services stay Drizzle (domain reads + `listForScope` are
+      // Postgres queries, unchanged per spec). Only the orchestrator's
+      // claim/dispatch half swaps to BullMQ.
+      const resolved = resolveBullMqConfig(opts.extensions?.bullmq);
+      providers.push({ provide: BULLMQ_CONNECTION, useValue: resolved.connection });
+      providers.push({ provide: BULLMQ_RESOLVED_CONFIG, useValue: resolved });
+      providers.push({ provide: JOB_ORCHESTRATOR, useClass: BullMQJobOrchestrator });
+      providers.push({ provide: JOB_RUN_SERVICE, useClass: DrizzleJobRunService });
+      providers.push({ provide: JOB_STEP_SERVICE, useClass: DrizzleJobStepService });
     } else {
       providers.push({ provide: JOB_ORCHESTRATOR, useClass: DrizzleJobOrchestrator });
       providers.push({ provide: JOB_RUN_SERVICE, useClass: DrizzleJobRunService });
       providers.push({ provide: JOB_STEP_SERVICE, useClass: DrizzleJobStepService });
     }
 
+    const exports = [
+      JOB_ORCHESTRATOR,
+      JOB_RUN_SERVICE,
+      JOB_STEP_SERVICE,
+      JOBS_MULTI_TENANT,
+    ];
+    // BULLMQ-1 — only export the BullMQ tokens when they were actually
+    // provided. Nest throws "exported but not provided" otherwise. Exported so
+    // JobWorkerModule (which imports this module) can read the resolved
+    // connection/config to spawn BullMQ workers.
+    if (opts.backend === 'bullmq') {
+      exports.push(BULLMQ_CONNECTION, BULLMQ_RESOLVED_CONFIG);
+    }
+
     return {
       module: JobsDomainModule,
       global: true,
       providers,
-      exports: [
-        JOB_ORCHESTRATOR,
-        JOB_RUN_SERVICE,
-        JOB_STEP_SERVICE,
-        JOBS_MULTI_TENANT,
-      ],
+      exports,
     };
   }
 }

package/runtime/subsystems/jobs/pool-config.loader.ts

@@ -194,6 +194,17 @@ export function allNonReservedPoolNames(config: PoolConfig): string[] {
   return out;
 }
 
+/**
+ * Names of **every** pool in the resolved config, reserved `events_*` lanes
+ * included. The activation set for a standalone worker booted with
+ * `JobWorkerModule.forRoot({ allPools: true })` (BULLMQ-1 Phase 1) — the
+ * single worker process drains both user pools and the bridge's reserved
+ * pools so wrapper `job_run` rows are never stranded.
+ */
+export function allPoolNames(config: PoolConfig): string[] {
+  return [...config.keys()];
+}
+
 // ─── internals ──────────────────────────────────────────────────────────────
 
 interface UserPoolShape {

package/runtime/subsystems/observability/index.ts

@@ -30,6 +30,14 @@ export type {
   IObservability,
   PoolStatusCount,
   JobRunFailure,
+  JobRunSummary,
+  JobRunPage,
+  ListJobRunsQuery,
+  EventSummary,
+  EventPage,
+  ListEventsQuery,
+  CorrelationTimeline,
+  CorrelationTimelineEntry,
   StatusHistogram,
   SyncRunSummary,
   CursorSnapshot,

package/runtime/subsystems/observability/observability.protocol.ts

@@ -21,12 +21,49 @@
 
 import type {
   JobRunFailure,
+  JobRunPage,
+  JobRunSummary,
+  ListJobRunsQuery,
   PoolStatusCount,
 } from '../jobs/job-run-service.protocol';
+import type {
+  EventPage,
+  EventSummary,
+  ListEventsQuery,
+} from '../events/event-read.protocol';
 import type { StatusHistogram } from '../bridge/bridge.protocol';
 import type { SyncRunSummary } from '../sync/sync-run-recorder.protocol';
 import type { CursorSnapshot } from '../sync/sync-cursor-store.protocol';
 
+/**
+ * One chronological entry in a correlation timeline (OBS-LIST-1). Either a
+ * `job_run` or a `domain_event` sharing the same `rootRunId`, tagged with a
+ * `kind` discriminator and a single `at` timestamp used for ordering.
+ */
+export type CorrelationTimelineEntry =
+  | { kind: 'job_run'; at: Date; run: JobRunSummary }
+  | { kind: 'event'; at: Date; event: EventSummary };
+
+/**
+ * Stitched view of everything correlated to a single `rootRunId`
+ * (OBS-LIST-1): the job runs sharing that root plus the domain events whose
+ * `metadata.rootRunId` matches, merged into one ascending timeline with a
+ * small roll-up summary.
+ */
+export interface CorrelationTimeline {
+  rootRunId: string;
+  /** Ascending by `at`. Job runs ordered by `createdAt`; events by `occurredAt`. */
+  entries: CorrelationTimelineEntry[];
+  summary: {
+    runCount: number;
+    eventCount: number;
+    /** Earliest `at` across all entries, or `null` when empty. */
+    startedAt: Date | null;
+    /** Latest `at` across all entries, or `null` when empty. */
+    lastActivityAt: Date | null;
+  };
+}
+
 export interface IObservability {
   /**
    * Live `(pool, status)` counts across `job_run`. Delegates to
@@ -79,6 +116,39 @@ export interface IObservability {
    * Empty array when the sync subsystem is not installed.
    */
   getCursors(tenantId?: string | null): Promise<CursorSnapshot[]>;
+
+  /**
+   * Paginated, filterable `job_run` list (OBS-LIST-1). Delegates to
+   * `IJobRunService.listJobRuns`. Keyset pagination on `created_at`.
+   *
+   * Returns an empty page (`{ items: [], nextCursor: null }`) when the jobs
+   * subsystem is not installed.
+   */
+  listJobRuns(query?: ListJobRunsQuery): Promise<JobRunPage>;
+
+  /**
+   * Paginated, filterable `domain_events` list (OBS-LIST-1). Delegates to
+   * `IEventReadPort.listEvents`. Keyset pagination on `occurred_at`.
+   *
+   * Returns an empty page when the events read port is not installed (e.g.
+   * the events subsystem is absent, or its backend is `redis` which retains
+   * no history).
+   */
+  listEvents(query?: ListEventsQuery): Promise<EventPage>;
+
+  /**
+   * Stitch the job runs and domain events sharing a `rootRunId` into a
+   * single ascending timeline + summary (OBS-LIST-1). Composes
+   * `IJobRunService.listJobRuns` (filtered by the run tree) and
+   * `IEventReadPort.listEvents({ rootRunId })`.
+   *
+   * Returns an empty timeline (zero counts, null bounds) when neither the
+   * jobs subsystem nor the events read port is installed.
+   */
+  getCorrelationTimeline(
+    rootRunId: string,
+    tenantId?: string | null,
+  ): Promise<CorrelationTimeline>;
 }
 
 // Re-export composed return types so consumers of IObservability can import
@@ -86,6 +156,12 @@ export interface IObservability {
 export type {
   PoolStatusCount,
   JobRunFailure,
+  JobRunSummary,
+  JobRunPage,
+  ListJobRunsQuery,
+  EventSummary,
+  EventPage,
+  ListEventsQuery,
   StatusHistogram,
   SyncRunSummary,
   CursorSnapshot,

package/runtime/subsystems/observability/observability.service.ts

@@ -33,9 +33,20 @@ import { JOB_RUN_SERVICE } from '../jobs/jobs-domain.tokens';
 import type {
   IJobRunService,
   JobRunFailure,
+  JobRunPage,
+  JobRunSummary,
+  ListJobRunsQuery,
   PoolStatusCount,
 } from '../jobs/job-run-service.protocol';
 
+import { EVENT_READ_PORT } from '../events/events.tokens';
+import type {
+  EventPage,
+  EventSummary,
+  IEventReadPort,
+  ListEventsQuery,
+} from '../events/event-read.protocol';
+
 import { BRIDGE_DELIVERY_REPO } from '../bridge/bridge.tokens';
 import type { IJobBridge, StatusHistogram } from '../bridge/bridge.protocol';
 
@@ -49,7 +60,19 @@ import type {
   ICursorStore,
 } from '../sync/sync-cursor-store.protocol';
 
-import type { IObservability } from './observability.protocol';
+import type {
+  CorrelationTimeline,
+  CorrelationTimelineEntry,
+  IObservability,
+} from './observability.protocol';
+
+/**
+ * Safety bound on how many pages the correlation timeline will walk when
+ * draining a sibling port. A single run tree producing more than
+ * 50 pages × default page size of correlated rows is pathological; cap to
+ * keep the stitch bounded rather than unbounded-loop on bad data.
+ */
+const MAX_TIMELINE_PAGES = 50;
 
 @Injectable()
 export class ObservabilityService implements IObservability {
@@ -65,6 +88,16 @@ export class ObservabilityService implements IObservability {
     failed: 0,
   };
 
+  /** Empty page used when a sibling read port is absent. */
+  private static readonly EMPTY_JOB_RUN_PAGE: JobRunPage = {
+    items: [],
+    nextCursor: null,
+  };
+  private static readonly EMPTY_EVENT_PAGE: EventPage = {
+    items: [],
+    nextCursor: null,
+  };
+
   constructor(
     @Optional()
     @Inject(JOB_RUN_SERVICE)
@@ -78,6 +111,9 @@ export class ObservabilityService implements IObservability {
     @Optional()
     @Inject(SYNC_CURSOR_STORE)
     private readonly cursors?: ICursorStore,
+    @Optional()
+    @Inject(EVENT_READ_PORT)
+    private readonly events?: IEventReadPort | null,
   ) {}
 
   async getPoolDepths(tenantId?: string | null): Promise<PoolStatusCount[]> {
@@ -114,4 +150,115 @@ export class ObservabilityService implements IObservability {
     if (!this.cursors) return [];
     return this.cursors.listAll(tenantId);
   }
+
+  async listJobRuns(query?: ListJobRunsQuery): Promise<JobRunPage> {
+    if (!this.jobRuns) {
+      return { ...ObservabilityService.EMPTY_JOB_RUN_PAGE };
+    }
+    return this.jobRuns.listJobRuns(query);
+  }
+
+  async listEvents(query?: ListEventsQuery): Promise<EventPage> {
+    if (!this.events) {
+      return { ...ObservabilityService.EMPTY_EVENT_PAGE };
+    }
+    return this.events.listEvents(query);
+  }
+
+  async getCorrelationTimeline(
+    rootRunId: string,
+    tenantId?: string | null,
+  ): Promise<CorrelationTimeline> {
+    const runs = await this.collectRuns(rootRunId, tenantId);
+    const events = await this.collectEvents(rootRunId, tenantId);
+
+    const entries: CorrelationTimelineEntry[] = [
+      ...runs.map(
+        (run): CorrelationTimelineEntry => ({
+          kind: 'job_run',
+          at: run.createdAt,
+          run,
+        }),
+      ),
+      ...events.map(
+        (event): CorrelationTimelineEntry => ({
+          kind: 'event',
+          at: event.occurredAt,
+          event,
+        }),
+      ),
+    ];
+
+    // Ascending chronological order. Stable tie-break: job runs before
+    // events at the same instant (the run that emits an event precedes it).
+    entries.sort((a, b) => {
+      const dt = a.at.getTime() - b.at.getTime();
+      if (dt !== 0) return dt;
+      if (a.kind === b.kind) return 0;
+      return a.kind === 'job_run' ? -1 : 1;
+    });
+
+    const startedAt = entries.length > 0 ? entries[0]!.at : null;
+    const lastActivityAt =
+      entries.length > 0 ? entries[entries.length - 1]!.at : null;
+
+    return {
+      rootRunId,
+      entries,
+      summary: {
+        runCount: runs.length,
+        eventCount: events.length,
+        startedAt,
+        lastActivityAt,
+      },
+    };
+  }
+
+  /**
+   * Drain every `job_run` sharing `rootRunId` by walking the keyset cursor.
+   * Empty when the jobs subsystem is absent.
+   */
+  private async collectRuns(
+    rootRunId: string,
+    tenantId?: string | null,
+  ): Promise<JobRunSummary[]> {
+    if (!this.jobRuns) return [];
+    const out: JobRunSummary[] = [];
+    let cursor: string | undefined;
+    for (let page = 0; page < MAX_TIMELINE_PAGES; page += 1) {
+      const result = await this.jobRuns.listJobRuns({
+        rootRunId,
+        tenantId,
+        cursor,
+      });
+      out.push(...result.items);
+      if (!result.nextCursor) break;
+      cursor = result.nextCursor;
+    }
+    return out;
+  }
+
+  /**
+   * Drain every `domain_event` whose `metadata.rootRunId` matches by walking
+   * the keyset cursor. Empty when the events read port is absent.
+   */
+  private async collectEvents(
+    rootRunId: string,
+    tenantId?: string | null,
+  ): Promise<EventSummary[]> {
+    if (!this.events) return [];
+    const out: EventSummary[] = [];
+    let cursor: string | undefined;
+    for (let page = 0; page < MAX_TIMELINE_PAGES; page += 1) {
+      const result = await this.events.listEvents({
+        rootRunId,
+        tenantId,
+        cursor,
+      });
+      out.push(...result.items);
+      if (!result.nextCursor) break;
+      cursor = result.nextCursor;
+    }
+    return out;
+  }
 }

package/templates/entity/new/clean-lite-ps/prompt-extension.js

@@ -495,28 +495,30 @@ function collectDrizzleImports(processedFields, belongsTo, hasTimestamps, hasSof
 function zodChainForCreate(field) {
   const { type, nullable, required, hasDefault, hasChoices, choices } = field;
 
+  // Apply nullability and optionality INDEPENDENTLY. A nullable column accepts
+  // null (`.nullable()`); a field without `required: true` may be omitted from
+  // the create payload (`.optional()`). A field that is both gets
+  // `.nullable().optional()`. Previously the `nullable` branch returned early,
+  // so a nullable-and-optional field never got `.optional()` — forcing callers
+  // to send an explicit `null` for every optional column (e.g. POST /accounts
+  // rejecting a body that omits `domain`/`industry`).
   if (hasChoices) {
-    const base = `z.enum([${choices.map((c) => `'${c}'`).join(', ')}])`;
-    if (!required && !nullable) return base + '.optional()';
-    if (nullable) return base + '.nullable()';
+    let base = `z.enum([${choices.map((c) => `'${c}'`).join(', ')}])`;
+    if (nullable) base += '.nullable()';
+    if (!required) base += '.optional()';
     return base;
   }
 
   let base = ZOD_TYPE_MAP[type] || 'z.unknown()';
 
   if (type === 'boolean' && hasDefault) {
+    // `.default()` already makes the input optional in Zod.
     base += `.default(${field.default ?? false})`;
     return base;
   }
 
-  if (nullable) {
-    return base + '.nullable()';
-  }
-
-  if (!required) {
-    return base + '.optional()';
-  }
-
+  if (nullable) base += '.nullable()';
+  if (!required) base += '.optional()';
   return base;
 }
 
@@ -1132,7 +1134,7 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
   // FK fields from belongs_to for create/output DTOs
   const belongsToFkFields = belongsTo.map((rel) => ({
     camelName: rel.camelField,
-    zodChainCreate: rel.nullable ? 'z.string().uuid().nullable()' : 'z.string().uuid()',
+    zodChainCreate: rel.nullable ? 'z.string().uuid().nullable().optional()' : 'z.string().uuid()',
     zodChainOutput: rel.nullable ? 'z.string().uuid().nullable()' : 'z.string().uuid()',
     nullable: rel.nullable,
   }));