@pattern-stack/codegen 0.4.0 → 0.4.2

package/runtime/base-classes/metadata-entity-repository.ts

@@ -0,0 +1,80 @@
+/**
+ * MetadataEntityRepository<TEntity>
+ *
+ * Family-specific base for metadata entities (field values, field history, tags).
+ * Adds entity-scoped lookups, type filtering, history ordering, and bulk upsert.
+ *
+ * Concrete repos extend this and declare their table + behaviors.
+ */
+import { eq, and, desc } from 'drizzle-orm';
+import type { PgTableWithColumns } from 'drizzle-orm/pg-core';
+import { BaseRepository } from './base-repository';
+import type { DrizzleTx } from '../types/drizzle';
+
+export abstract class MetadataEntityRepository<TEntity> extends BaseRepository<TEntity> {
+  /**
+   * Bulk upsert with a caller-specified conflict target.
+   * Uses Drizzle's onConflictDoUpdate to merge records.
+   */
+  override async upsertMany(
+    inputs: Array<Partial<TEntity>>,
+    tx?: DrizzleTx,
+    options?: { conflictTarget?: keyof PgTableWithColumns<any>['_']['columns'] }, // eslint-disable-line @typescript-eslint/no-explicit-any
+  ): Promise<TEntity[]> {
+    if (inputs.length === 0) return [];
+    const conflictTarget = options?.conflictTarget;
+
+    // Fall back to base class naive upsert when no conflict target provided.
+    if (!conflictTarget) {
+      return super.upsertMany(inputs, tx);
+    }
+
+    const data = inputs.map((input) =>
+      this.withTimestamps(input as Record<string, unknown>, 'create'),
+    );
+
+    const rows = await this.runner(tx)
+      .insert(this.table)
+      .values(data as any) // eslint-disable-line @typescript-eslint/no-explicit-any
+      .onConflictDoUpdate({
+        target: this.table[conflictTarget as string],
+        set: data[0] as any, // eslint-disable-line @typescript-eslint/no-explicit-any
+      })
+      .returning();
+
+    return rows as TEntity[];
+  }
+
+  /**
+   * Find metadata by entity ID and entity type (compound lookup).
+   */
+  async findByEntityIdAndType(entityId: string, entityType: string): Promise<TEntity[]> {
+    const rows = await this.baseQuery()
+      .where(
+        and(
+          eq(this.table['entityId'], entityId),
+          eq(this.table['entityType'], entityType),
+        ),
+      );
+    return rows as TEntity[];
+  }
+
+  /**
+   * List all metadata records for an entity.
+   */
+  async listByEntityId(entityId: string): Promise<TEntity[]> {
+    const rows = await this.baseQuery()
+      .where(eq(this.table['entityId'], entityId));
+    return rows as TEntity[];
+  }
+
+  /**
+   * List metadata history for an entity, ordered by validFrom descending.
+   */
+  async listHistoryByEntityId(entityId: string): Promise<TEntity[]> {
+    const rows = await this.baseQuery()
+      .where(eq(this.table['entityId'], entityId))
+      .orderBy(desc(this.table['validFrom']));
+    return rows as TEntity[];
+  }
+}

package/runtime/base-classes/metadata-entity-service.ts

@@ -0,0 +1,48 @@
+/**
+ * MetadataEntityService<TRepo, TEntity>
+ *
+ * Family-specific base service for metadata entities.
+ * Delegates to a metadata repository that provides entity-scoped
+ * lookups, history, and bulk upsert.
+ */
+import { BaseService, type IBaseRepository } from './base-service';
+
+export interface IMetadataEntityRepository<TEntity> extends IBaseRepository<TEntity> {
+  findByEntityIdAndType(entityId: string, entityType: string): Promise<TEntity[]>;
+  listByEntityId(entityId: string): Promise<TEntity[]>;
+  listHistoryByEntityId(entityId: string): Promise<TEntity[]>;
+  upsertMany(inputs: Array<Partial<TEntity>>, tx?: unknown, options?: { conflictTarget?: string }): Promise<TEntity[]>;
+}
+
+export abstract class MetadataEntityService<
+  TRepo extends IMetadataEntityRepository<TEntity>,
+  TEntity,
+> extends BaseService<TRepo, TEntity> {
+  /**
+   * Find metadata records by entity ID and entity type (EAV polymorphic lookup).
+   */
+  findByEntityIdAndType(entityId: string, entityType: string): Promise<TEntity[]> {
+    return this.repository.findByEntityIdAndType(entityId, entityType);
+  }
+
+  /**
+   * List all metadata records for an entity.
+   */
+  listByEntity(entityId: string): Promise<TEntity[]> {
+    return this.repository.listByEntityId(entityId);
+  }
+
+  /**
+   * List metadata history for an entity, ordered by validFrom desc.
+   */
+  listHistory(entityId: string): Promise<TEntity[]> {
+    return this.repository.listHistoryByEntityId(entityId);
+  }
+
+  /**
+   * Bulk upsert metadata values.
+   */
+  upsertValues(inputs: Array<Partial<TEntity>>, conflictTarget: string, tx?: unknown): Promise<TEntity[]> {
+    return this.repository.upsertMany(inputs, tx, { conflictTarget });
+  }
+}

package/runtime/base-classes/synced-entity-repository.ts

@@ -0,0 +1,57 @@
+/**
+ * SyncedEntityRepository<TEntity>
+ *
+ * Family-specific base for Synced entities (contacts, accounts, opportunities).
+ * Adds external ID lookups, user-scoped queries, and sync stubs.
+ *
+ * Concrete repos extend this and declare their table + behaviors.
+ */
+import { eq, inArray } from 'drizzle-orm';
+import { BaseRepository } from './base-repository';
+
+export abstract class SyncedEntityRepository<TEntity> extends BaseRepository<TEntity> {
+  /**
+   * Find a single entity by its external CRM identifier.
+   */
+  async findByExternalId(externalId: string): Promise<TEntity | null> {
+    const rows = await this.baseQuery()
+      .where(eq(this.table['externalId'], externalId))
+      .limit(1);
+    return (rows[0] as TEntity) ?? null;
+  }
+
+  /**
+   * Find multiple entities by external CRM identifiers.
+   */
+  async findManyByExternalIds(externalIds: string[]): Promise<TEntity[]> {
+    if (externalIds.length === 0) return [];
+    const rows = await this.baseQuery()
+      .where(inArray(this.table['externalId'], externalIds));
+    return rows as TEntity[];
+  }
+
+  /**
+   * Find all entities owned by a specific user.
+   */
+  async findAllByUserId(userId: string): Promise<TEntity[]> {
+    const rows = await this.baseQuery()
+      .where(eq(this.table['userId'], userId));
+    return rows as TEntity[];
+  }
+
+  /**
+   * Sync upsert — bulk insert-or-update from external CRM data.
+   * Concrete repositories must implement with the appropriate conflict target.
+   */
+  async syncUpsert(_inputs: Array<Partial<TEntity>>): Promise<TEntity[]> {
+    throw new Error('syncUpsert not implemented — override in concrete repository');
+  }
+
+  /**
+   * Find entities visible to a user (ownership + sharing rules).
+   * Concrete repositories must implement with visibility logic.
+   */
+  async findVisibleByUserId(_userId: string): Promise<TEntity[]> {
+    throw new Error('findVisibleByUserId not implemented — override in concrete repository');
+  }
+}

package/runtime/base-classes/synced-entity-service.ts

@@ -0,0 +1,50 @@
+/**
+ * SyncedEntityService<TRepo, TEntity>
+ *
+ * Family-specific base service for Synced entities.
+ * Delegates to a CRM repository that provides external ID lookups
+ * and user-scoped queries.
+ */
+import { BaseService, type IBaseRepository } from './base-service';
+
+export interface ISyncedEntityRepository<TEntity> extends IBaseRepository<TEntity> {
+  findByExternalId(externalId: string): Promise<TEntity | null>;
+  findManyByExternalIds(externalIds: string[]): Promise<TEntity[]>;
+  findAllByUserId(userId: string): Promise<TEntity[]>;
+  findVisibleByUserId(userId: string): Promise<TEntity[]>;
+  syncUpsert(inputs: Array<Partial<TEntity>>): Promise<TEntity[]>;
+}
+
+export abstract class SyncedEntityService<
+  TRepo extends ISyncedEntityRepository<TEntity>,
+  TEntity,
+> extends BaseService<TRepo, TEntity> {
+  /**
+   * Find a single entity by its external CRM identifier.
+   */
+  findByExternalId(externalId: string): Promise<TEntity | null> {
+    return this.repository.findByExternalId(externalId);
+  }
+
+  /**
+   * Find multiple entities by external CRM identifiers.
+   */
+  findManyByExternalIds(externalIds: string[]): Promise<TEntity[]> {
+    return this.repository.findManyByExternalIds(externalIds);
+  }
+
+  /**
+   * Find all entities owned by a specific user.
+   */
+  findAllByUser(userId: string): Promise<TEntity[]> {
+    return this.repository.findAllByUserId(userId);
+  }
+
+  /**
+   * Find entities visible to a user (ownership + sharing rules).
+   * Concrete services may override with domain-specific visibility logic.
+   */
+  findVisibleByUser(userId: string): Promise<TEntity[]> {
+    return this.repository.findVisibleByUserId(userId);
+  }
+}

package/runtime/base-classes/with-analytics.ts

@@ -0,0 +1,22 @@
+/**
+ * WithAnalytics mixin
+ *
+ * Adds an optional `.analytics` property to the service class.
+ * The analytics provider is a per-entity @Injectable (e.g., AccountAnalytics)
+ * injected via @Optional() in the generated service constructor.
+ *
+ * Usage: class MyService extends WithAnalytics(BaseService<...>) { ... }
+ *
+ * The generated service adds:
+ *   @Optional() @Inject(AccountAnalytics) override analytics?: AccountAnalytics
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T = {}> = abstract new (...args: any[]) => T;
+
+export function WithAnalytics<TBase extends Constructor>(Base: TBase) {
+  abstract class WithAnalyticsMixin extends Base {
+    analytics?: any;
+  }
+  return WithAnalyticsMixin as TBase & typeof WithAnalyticsMixin;
+}

package/runtime/constants/tokens.ts

@@ -0,0 +1,29 @@
+/**
+ * NestJS injection tokens
+ *
+ * Used with @Inject() decorator in concrete repository constructors.
+ */
+
+/**
+ * Injection token for the Drizzle ORM database client.
+ *
+ * Usage in concrete repositories:
+ * ```typescript
+ * constructor(@Inject(DRIZZLE) db: DrizzleClient) { super(db); }
+ * ```
+ */
+export const DRIZZLE = 'DRIZZLE' as const;
+
+/**
+ * Injection token for the event bus (IEventBus).
+ *
+ * Optional — only resolved when EventsModule.forRoot() is registered.
+ * BaseService uses this with @Optional() to emit lifecycle events
+ * without requiring the events subsystem to be installed.
+ *
+ * Usage in services/use cases:
+ * ```typescript
+ * @Optional() @Inject(EVENT_BUS) eventBus?: IEventBus
+ * ```
+ */
+export const EVENT_BUS = 'EVENT_BUS' as const;

package/runtime/eav-helpers.ts

@@ -0,0 +1,74 @@
+/**
+ * EAV helpers
+ *
+ * Small, pure utilities used by services that dual-write to the EAV value
+ * table alongside their own table.
+ *
+ * - `toEavRows` builds value-table insert rows from a flat `{ key: value }`
+ *   bag, resolving the `fieldDefinitionId` via a caller-supplied map.
+ *   Callers own the field-definitions lookup / cache.
+ * - `mergeEavRows` inverts: given value-table rows + a definition `id -> key`
+ *   map, collapses them into a flat `{ key: value }` bag.
+ *
+ * Both are sync + allocation-light. They do not touch the DB.
+ */
+
+/**
+ * Map of field key -> field_definitions.id, scoped to a single entityType.
+ */
+export type FieldDefinitionIdMap = ReadonlyMap<string, string>;
+
+/**
+ * Minimal shape of a value-table row accepted by toEavRows output. Consumers
+ * pass their entity's `Insert` type; these are the columns the helper sets.
+ */
+export interface EavInsertShape {
+  entityId: string;
+  entityType: string;
+  userId: string;
+  fieldDefinitionId: string;
+  value: unknown;
+}
+
+/**
+ * Build value-table insert rows from a flat field bag. Keys present in
+ * `fields` but missing from `fieldDefIds` are skipped — caller is expected
+ * to ensure the definitions exist (first-cut; auto-create is a later step).
+ */
+export function toEavRows(
+  entityId: string,
+  entityType: string,
+  userId: string,
+  fields: Record<string, unknown>,
+  fieldDefIds: FieldDefinitionIdMap,
+): EavInsertShape[] {
+  const rows: EavInsertShape[] = [];
+  for (const [key, value] of Object.entries(fields)) {
+    const fieldDefinitionId = fieldDefIds.get(key);
+    if (!fieldDefinitionId) continue;
+    rows.push({ entityId, entityType, userId, fieldDefinitionId, value });
+  }
+  return rows;
+}
+
+/**
+ * Collapse EAV rows back into a flat `{ key: value }` bag.
+ *
+ * Accepts bare value-table rows plus a separate `id -> { key }` map. Later
+ * rows win if the same key appears more than once. Call with temporal
+ * filtering already applied (e.g. validTo IS NULL) — this function does not
+ * interpret validFrom / validTo.
+ */
+export function mergeEavRows(
+  rows: Array<{ fieldDefinitionId: string | null; value: unknown }>,
+  defsById: ReadonlyMap<string, { key: string }>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const row of rows) {
+    if (!row.fieldDefinitionId) continue;
+    const def = defsById.get(row.fieldDefinitionId);
+    if (!def) continue;
+    out[def.key] = row.value;
+  }
+  return out;
+}

package/runtime/pipes/zod-validation.pipe.ts

@@ -0,0 +1,64 @@
+/**
+ * ZodValidationPipe
+ *
+ * Validates an incoming request body (or any decorated value) against a
+ * Zod schema at the controller boundary. Intended for use with Nest's
+ * `@Body(new ZodValidationPipe(MySchema))` pattern so generated
+ * controllers get runtime validation without relying on a global pipe
+ * that every consumer would have to opt into.
+ *
+ * Why a pipe (vs. validating inside the use case): validation is a
+ * presentation-layer concern (ADR-003). The use case should receive a
+ * type-safe, already-validated DTO; surfacing a `ZodError` at the pipe
+ * stage produces the standard 400 BadRequest response shape that HTTP
+ * clients expect.
+ *
+ * On success: returns parsed, coerced data.
+ * On failure: throws BadRequestException with a structured `issues` array
+ * (path / code / message) — richer than `.flatten()` for API consumers.
+ *
+ * One pipe instance per route (cheap — instantiated at module load). Keeps
+ * validation explicit in the generated code; no metadata/reflection magic.
+ *
+ * Vendored into consumer projects at `src/shared/pipes/zod-validation.pipe.ts`
+ * via `codegen project init` (see init-scaffold's VENDORED_RUNTIME_FILES).
+ */
+import {
+  BadRequestException,
+  Injectable,
+  PipeTransform,
+  type ArgumentMetadata,
+} from '@nestjs/common';
+import type { ZodIssue, ZodSchema } from 'zod';
+
+@Injectable()
+export class ZodValidationPipe<TSchema extends ZodSchema = ZodSchema>
+  implements PipeTransform
+{
+  constructor(private readonly schema: TSchema) {}
+
+  transform(value: unknown, _metadata: ArgumentMetadata): unknown {
+    const result = this.schema.safeParse(value);
+    if (result.success) {
+      return result.data;
+    }
+    throw new BadRequestException({
+      statusCode: 400,
+      error: 'Bad Request',
+      message: 'Validation failed',
+      issues: formatIssues(result.error.issues),
+    });
+  }
+}
+
+function formatIssues(issues: readonly ZodIssue[]): Array<{
+  path: string;
+  code: string;
+  message: string;
+}> {
+  return issues.map((issue) => ({
+    path: issue.path.join('.'),
+    code: issue.code,
+    message: issue.message,
+  }));
+}

package/runtime/shared/openapi/error-response.dto.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared error response schema (OPENAPI-3).
+ *
+ * Generated controllers `@ApiResponse(...)` decorators reference this
+ * schema by `$ref` (name `ErrorResponseDto`) for non-success status codes
+ * (400, 401, 404, etc.). Shape matches NestJS's default `HttpException`
+ * JSON body — see `packages/common/src/exceptions/http.exception.ts`.
+ *
+ * The registry auto-registers this schema on construction so every
+ * consumer project exposes `components.schemas.ErrorResponseDto` on
+ * `/docs-json` without per-entity duplication.
+ */
+import { z } from 'zod';
+
+export const errorResponseSchema = z.object({
+  statusCode: z.number().int(),
+  message: z.union([z.string(), z.array(z.string())]),
+  error: z.string().optional(),
+});
+
+export type ErrorResponseDto = z.infer<typeof errorResponseSchema>;
+
+/** Canonical name used across `$ref` URIs in generated controllers. */
+export const ERROR_RESPONSE_SCHEMA_NAME = 'ErrorResponseDto';

package/runtime/shared/openapi/errors.ts

@@ -0,0 +1,39 @@
+/**
+ * Typed errors for the OpenAPI registry (OPENAPI-1).
+ *
+ * Same shape as `runtime/subsystems/bridge/bridge-errors.ts` so consumers
+ * can catch them with the same exception-filter pattern used elsewhere.
+ */
+
+/**
+ * Thrown by `OpenApiRegistry.build()` when `@anatine/zod-openapi` is not
+ * resolvable. The peer is declared optional (`peerDependenciesMeta`) so
+ * consumer apps that don't care about OpenAPI still boot; the cost is a
+ * deferred failure here on first `build()`.
+ */
+export class OpenApiPeerDepMissingError extends Error {
+  override readonly name = 'OpenApiPeerDepMissingError';
+  constructor(message?: string) {
+    super(
+      message ??
+        'OpenApiRegistry requires @anatine/zod-openapi. Install it: bun add @anatine/zod-openapi',
+    );
+  }
+}
+
+/**
+ * Thrown by `OpenApiRegistry.registerSchema(name, ...)` when `name` is
+ * already registered. Silent overwrite would make debugging
+ * double-registration bugs (e.g. two entity pipelines both emitting a
+ * `User` DTO) painful; loud failure lets the mismatch surface at module
+ * init where the stack trace is clear.
+ */
+export class DuplicateSchemaError extends Error {
+  override readonly name = 'DuplicateSchemaError';
+  constructor(public readonly schemaName: string) {
+    super(
+      `DuplicateSchemaError: schema '${schemaName}' is already registered. ` +
+        `Each schema name must be unique within the OpenApiRegistry.`,
+    );
+  }
+}

package/runtime/shared/openapi/index.ts

@@ -0,0 +1,20 @@
+/**
+ * OpenAPI shared subsystem — public API (OPENAPI-1).
+ *
+ * Consumed by generated DTO providers (OPENAPI-2), controller decorators
+ * (OPENAPI-3), and the Swagger UI bootstrap (OPENAPI-4).
+ */
+export { OpenApiRegistry } from './registry';
+export type {
+  HttpMethod,
+  PathSpec,
+  OpenAPIInfo,
+  OpenAPIObject,
+} from './registry';
+export { OPENAPI_REGISTRY } from './registry.tokens';
+export { OpenApiPeerDepMissingError, DuplicateSchemaError } from './errors';
+export {
+  ERROR_RESPONSE_SCHEMA_NAME,
+  errorResponseSchema,
+} from './error-response.dto';
+export type { ErrorResponseDto } from './error-response.dto';

package/runtime/shared/openapi/registry.tokens.ts

@@ -0,0 +1,13 @@
+/**
+ * Injection token for the OpenAPI registry (OPENAPI-1).
+ *
+ * String constant (not a Symbol) so it matches by value across import
+ * boundaries — same convention as `ANALYTICS_QUERY` in analytics and
+ * `EVENT_BUS` / `BRIDGE_DELIVERY_REPO` in events / bridge. The OPENAPI-1
+ * spec sketched a Symbol, but the repo-wide convention wins — codebase
+ * consistency matters more than the spec's initial guess.
+ *
+ * Consumed by generated DTO providers (OPENAPI-2), controllers
+ * (OPENAPI-3), and the Swagger bootstrap (OPENAPI-4).
+ */
+export const OPENAPI_REGISTRY = 'OPENAPI_REGISTRY' as const;

package/runtime/shared/openapi/registry.ts

@@ -0,0 +1,151 @@
+/**
+ * OpenApiRegistry — collects Zod schemas and path specs, emits a
+ * complete `OpenAPIObject` on `build()` (OPENAPI-1).
+ *
+ * Wraps `@anatine/zod-openapi` as an **optional peer dependency** using
+ * the lazy-import pattern from `runtime/subsystems/analytics/cube-backend.ts`
+ * — consumer apps that never call `build()` still boot even if
+ * `@anatine/zod-openapi` isn't installed.
+ *
+ * The registry is the single source of truth consumed by OPENAPI-2
+ * (generated DTOs register their Zod schemas at module init), OPENAPI-3
+ * (controller decorators reference those schemas), and OPENAPI-4
+ * (Swagger UI bootstrap calls `build()` once at startup).
+ */
+import type { z } from 'zod';
+
+import { ERROR_RESPONSE_SCHEMA_NAME, errorResponseSchema } from './error-response.dto';
+import { OpenApiPeerDepMissingError, DuplicateSchemaError } from './errors';
+
+export type HttpMethod = 'get' | 'post' | 'patch' | 'delete' | 'put';
+
+/**
+ * OpenAPI path spec. Structurally compatible with `openapi3-ts`'s
+ * `OperationObject` but typed loosely here because the peer type package
+ * isn't installed as a direct dep — consumers supply whatever their
+ * codegen emits.
+ */
+export interface PathSpec {
+  summary?: string;
+  description?: string;
+  operationId?: string;
+  tags?: string[];
+  parameters?: unknown[];
+  requestBody?: unknown;
+  responses?: Record<string, unknown>;
+  security?: unknown[];
+  [key: string]: unknown;
+}
+
+export interface OpenAPIInfo {
+  title: string;
+  version: string;
+  description?: string;
+}
+
+/**
+ * Minimal OpenAPIObject shape. We redeclare rather than pull
+ * `openapi3-ts` types through the peer — the peer's `generateSchema`
+ * returns a `SchemaObject`, but the final document assembly is ours.
+ */
+export interface OpenAPIObject {
+  openapi: string;
+  info: OpenAPIInfo;
+  paths: Record<string, Record<string, PathSpec>>;
+  components: {
+    schemas: Record<string, unknown>;
+  };
+}
+
+interface PeerModule {
+  generateSchema: (zodRef: unknown, useOutput?: boolean, version?: '3.0' | '3.1') => unknown;
+}
+
+export class OpenApiRegistry {
+  private zodSchemas = new Map<string, z.ZodType>();
+  private pathEntries = new Map<string, Map<HttpMethod, PathSpec>>();
+  private peer: PeerModule | null = null;
+
+  constructor() {
+    // Auto-register the shared error response schema so controllers that
+    // reference `#/components/schemas/ErrorResponseDto` always resolve
+    // (OPENAPI-3). Consumers can `reset()` + re-register in tests.
+    this.zodSchemas.set(ERROR_RESPONSE_SCHEMA_NAME, errorResponseSchema);
+  }
+
+  registerSchema(name: string, schema: z.ZodType): void {
+    if (this.zodSchemas.has(name)) {
+      throw new DuplicateSchemaError(name);
+    }
+    this.zodSchemas.set(name, schema);
+  }
+
+  registerPath(path: string, method: HttpMethod, spec: PathSpec): void {
+    let methods = this.pathEntries.get(path);
+    if (!methods) {
+      methods = new Map();
+      this.pathEntries.set(path, methods);
+    }
+    methods.set(method, spec);
+  }
+
+  /**
+   * Emit the full OpenAPI document. Lazy-imports `@anatine/zod-openapi`
+   * on first call; failure to resolve raises `OpenApiPeerDepMissingError`
+   * (matches the `CubeAnalyticsBackend.onModuleInit` precedent).
+   *
+   * OpenAPI version is pinned to `3.0.3` — Swagger UI tooling is most
+   * stable on 3.0.x (see OPENAPI-PHASE-1-PLAN §Four locked decisions).
+   */
+  async build(info: OpenAPIInfo): Promise<OpenAPIObject> {
+    const peer = await this.loadPeer();
+
+    const schemas: Record<string, unknown> = {};
+    for (const [name, zodSchema] of this.zodSchemas) {
+      schemas[name] = peer.generateSchema(zodSchema, false, '3.0');
+    }
+
+    const paths: Record<string, Record<string, PathSpec>> = {};
+    for (const [path, methods] of this.pathEntries) {
+      const methodMap: Record<string, PathSpec> = {};
+      for (const [method, spec] of methods) {
+        methodMap[method] = spec;
+      }
+      paths[path] = methodMap;
+    }
+
+    return {
+      openapi: '3.0.3',
+      info,
+      paths,
+      components: { schemas },
+    };
+  }
+
+  /**
+   * Test helper — clears registered schemas and paths, then re-seeds the
+   * core `ErrorResponseDto` entry so post-reset state matches the
+   * invariant established in the constructor.
+   */
+  reset(): void {
+    this.zodSchemas.clear();
+    this.pathEntries.clear();
+    this.peer = null;
+    this.zodSchemas.set(ERROR_RESPONSE_SCHEMA_NAME, errorResponseSchema);
+  }
+
+  protected async loadPeer(): Promise<PeerModule> {
+    if (this.peer) return this.peer;
+    try {
+      // Computed specifier: prevents tsc from resolving this import at
+      // typecheck time. Consumers vendor this file but may not install
+      // @anatine/zod-openapi (optional peer).
+      const specifier: string = '@anatine/zod-openapi';
+      const mod = (await import(specifier)) as PeerModule;
+      this.peer = mod;
+      return mod;
+    } catch {
+      throw new OpenApiPeerDepMissingError();
+    }
+  }
+}