@pattern-stack/codegen 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,10 @@
       "types": "./dist/runtime/subsystems/index.d.ts",
       "default": "./dist/runtime/subsystems/index.js"
     },
+    "./runtime/shared/openapi": {
+      "types": "./dist/runtime/shared/openapi/index.d.ts",
+      "default": "./dist/runtime/shared/openapi/index.js"
+    },
     "./runtime/*": {
       "types": "./dist/runtime/*.d.ts",
       "default": "./dist/runtime/*.js"

package/runtime/subsystems/analytics/analytics.tokens.ts

@@ -9,16 +9,20 @@
  * constructor(@Inject(ANALYTICS_QUERY) private readonly analytics: IAnalyticsQuery) {}
  * ```
  */
+import { tokenKey } from '../token-key';
+
 export const ANALYTICS_QUERY = 'ANALYTICS_QUERY' as const;
 
+// ADR-037: namespaced `Symbol.for(...)` keys (via `tokenKey()`) so these tokens
+// match by value across import boundaries (package vs vendored runtime copy).
 /**
  * Injection token for the cube.js API URL.
  * Provided automatically by AnalyticsModule.forRoot({ backend: 'cube' }).
  */
-export const CUBE_API_URL = Symbol('CUBE_API_URL');
+export const CUBE_API_URL = Symbol.for(tokenKey('analytics', 'cube-api-url'));
 
 /**
  * Injection token for the cube.js API secret.
  * Provided automatically by AnalyticsModule.forRoot({ backend: 'cube' }).
  */
-export const CUBE_API_SECRET = Symbol('CUBE_API_SECRET');
+export const CUBE_API_SECRET = Symbol.for(tokenKey('analytics', 'cube-api-secret'));

package/runtime/subsystems/auth/auth.tokens.ts

@@ -26,15 +26,22 @@
  * `STRATEGY_REGISTRY` (a `ReadonlyMap<slug, IProviderStrategy>`), populated
  * by per-provider modules via a `useFactory` provider.
  */
-export const ENCRYPTION_KEY = Symbol('ENCRYPTION_KEY');
-export const OAUTH_STATE_STORE = Symbol('OAUTH_STATE_STORE');
-export const AUTH_CONNECTION_READER = Symbol('AUTH_CONNECTION_READER');
-export const AUTH_CONNECTION_TOKEN_WRITER = Symbol('AUTH_CONNECTION_TOKEN_WRITER');
-export const AUTH_CONNECTION_GRANT_SINK = Symbol('AUTH_CONNECTION_GRANT_SINK');
-export const AUTH_USER_CONTEXT = Symbol('AUTH_USER_CONTEXT');
-export const STRATEGY_REGISTRY = Symbol('STRATEGY_REGISTRY');
+import { tokenKey } from '../token-key';
+
+// ADR-037: namespaced `Symbol.for(...)` keys so a token matches by VALUE across
+// import boundaries — the package copy and a (legacy) vendored copy resolve to
+// the SAME symbol, eliminating the dual-package DI-token identity hazard that
+// crashed boot once the emitter began emitting `STRATEGY_REGISTRY` as a runtime
+// value (RFC-0003 R5). Matches the convention surface packages already use.
+export const ENCRYPTION_KEY = Symbol.for(tokenKey('auth', 'encryption-key'));
+export const OAUTH_STATE_STORE = Symbol.for(tokenKey('auth', 'oauth-state-store'));
+export const AUTH_CONNECTION_READER = Symbol.for(tokenKey('auth', 'connection-reader'));
+export const AUTH_CONNECTION_TOKEN_WRITER = Symbol.for(tokenKey('auth', 'connection-token-writer'));
+export const AUTH_CONNECTION_GRANT_SINK = Symbol.for(tokenKey('auth', 'connection-grant-sink'));
+export const AUTH_USER_CONTEXT = Symbol.for(tokenKey('auth', 'user-context'));
+export const STRATEGY_REGISTRY = Symbol.for(tokenKey('auth', 'strategy-registry'));
 /**
  * Holds the resolved `AuthModuleOptions` (used by `AuthController` to read
  * `redirectUriBase` for building per-provider callback URIs).
  */
-export const AUTH_OPTIONS = Symbol('AUTH_OPTIONS');
+export const AUTH_OPTIONS = Symbol.for(tokenKey('auth', 'options'));

package/runtime/subsystems/cache/cache.tokens.ts

@@ -7,11 +7,16 @@
  * ```
  *
  * Services may also inject CACHE for reads (get, has) per ADR-003.
+ *
+ * ADR-037: namespaced `Symbol.for(...)` key (via `tokenKey()`) so the token matches
+ * by value across import boundaries (package vs vendored runtime copy).
  */
-export const CACHE = Symbol('CACHE');
+import { tokenKey } from '../token-key';
+
+export const CACHE = Symbol.for(tokenKey('cache', 'cache'));
 
 /**
  * Injection token for the default TTL (in seconds) passed from CacheModule.forRoot().
  * Optional — omit for no-expiry behavior.
  */
-export const CACHE_DEFAULT_TTL = Symbol('CACHE_DEFAULT_TTL');
+export const CACHE_DEFAULT_TTL = Symbol.for(tokenKey('cache', 'default-ttl'));

package/runtime/subsystems/events/events.tokens.ts

@@ -9,6 +9,8 @@
  * constructor(@Inject(EVENT_BUS) private readonly eventBus: IEventBus) {}
  * ```
  */
+import { tokenKey } from '../token-key';
+
 export const EVENT_BUS = 'EVENT_BUS' as const;
 
 /**
@@ -61,8 +63,13 @@ export const EVENTS_MULTI_TENANT = 'EVENTS_MULTI_TENANT' as const;
 /**
  * Injection token for the Redis connection URL used by RedisEventBus.
  * Provided automatically by EventsModule.forRoot({ backend: 'redis' }).
+ *
+ * ADR-037: namespaced `Symbol.for(...)` (via `tokenKey()`) so it matches by value
+ * across runtime copies (the sibling string tokens above are already value-stable).
+ * Note the jobs subsystem defines its own `REDIS_URL`-equivalent; this is the
+ * events one.
  */
-export const REDIS_URL = Symbol('REDIS_URL');
+export const REDIS_URL = Symbol.for(tokenKey('events', 'redis-url'));
 
 /**
  * Injection token for the resolved `EventsModuleOptions` object.

package/runtime/subsystems/index.ts

@@ -6,7 +6,11 @@
 
 // Events
 export { EVENT_BUS } from './events';
-export type { DomainEvent, IEventBus } from './events';
+// `DrizzleTransaction` is re-exported here (not just from the `events` barrel)
+// so package-mode generated code — which imports from the single
+// `@pattern-stack/codegen/subsystems` barrel — resolves it (ADR-037). Vendored
+// mode reaches it via `@shared/subsystems/events`; both must export it.
+export type { DomainEvent, IEventBus, DrizzleTransaction } from './events';
 export { EventsModule, DrizzleEventBus, MemoryEventBus } from './events';
 
 // Jobs — orchestration schema only (JOB-1). Protocols / modules land in JOB-2 / JOB-5.
@@ -80,6 +84,7 @@ export {
 export type {
   IncrementalRead,
   RandomRead,
+  ReadContext,
   ReadMode,
   ReadRequest,
   Ref,

package/runtime/subsystems/integration/incremental-read.ts

@@ -79,6 +79,26 @@ export interface ReadRequest<F = unknown> {
   readonly pageSize?: number;
 }
 
+/**
+ * Per-run context threaded from `listChanges` into the vendor read body (R5).
+ *
+ * Carries the `subscription` framing the run so `enumerate`/`hydrate` can resolve
+ * **per-connection credentials** (and raw-landing keys) from
+ * `subscription.externalRef` — the gap a multi-account consumer surfaced: a
+ * singleton change source cannot hold connection-scoped auth, and before R5 the
+ * base forwarded the subscription only into `filterFor`, never into the fetch.
+ *
+ * Optional throughout (the core contract): a direct `read()` / `get()` call — the
+ * query surface's "fill one record on click" — may omit it. An adapter that needs
+ * per-connection auth reads `ctx?.subscription?.externalRef` and asserts its
+ * presence; a provider-level-auth adapter ignores it.
+ */
+export interface ReadContext {
+  /** The subscription framing this run; `externalRef` is the upstream scope /
+   *  connection id the adapter resolves credentials + raw-landing keys from. */
+  readonly subscription?: IntegrationSubscriptionView;
+}
+
 /**
  * The `read()`-side envelope: canonical record + the raw vendor payload it came
  * from + the originating external id + the per-ref cursor.
@@ -101,7 +121,7 @@ export interface SourcedRecord<T> {
  * hydration, and cursor emission are the providing base's concern.
  */
 export interface IncrementalRead<T, F = unknown> {
-  read(req: ReadRequest<F>): AsyncIterable<SourcedRecord<T>>;
+  read(req: ReadRequest<F>, ctx?: ReadContext): AsyncIterable<SourcedRecord<T>>;
 }
 
 /**
@@ -111,7 +131,7 @@ export interface IncrementalRead<T, F = unknown> {
  * surface.
  */
 export interface RandomRead<T> {
-  get(id: string): Promise<T | null>;
+  get(id: string, ctx?: ReadContext): Promise<T | null>;
 }
 
 // ============================================================================
@@ -208,11 +228,16 @@ export abstract class IncrementalReadBase<T, F = unknown, M = Record<string, unk
    * `pageSize` (from `ReadRequest`) is the adapter's requested vendor page size
    * — also the atomic-cursor backfill blast-radius bound (§ `cursorDivisible`).
    * Honor it as a hint; vendors that cap page size clamp it.
+   *
+   * `ctx?.subscription` (R5) carries the run's subscription, so a per-connection
+   * adapter resolves credentials / upstream scope from `externalRef` here; absent
+   * on a direct `read()` with no run subscription.
    */
   protected abstract enumerate(
     mode: ReadMode,
     filter?: F,
     pageSize?: number,
+    ctx?: ReadContext,
   ): AsyncIterable<Ref<M>[]>;
 
   /**
@@ -221,8 +246,12 @@ export abstract class IncrementalReadBase<T, F = unknown, M = Record<string, unk
    * alignment. Write it over `mapConcurrent(ids, (id) => this.fetchOne(id),
    * this.hydrateConcurrency)`; override with a real `/batch` call or a
    * passthrough (full-object list) where the vendor allows.
+   *
+   * `ctx?.subscription` (R5) carries the run's subscription for per-connection
+   * credential resolution (the fetch is where the vendor call happens) and is the
+   * natural place to land raw payloads keyed by `subscription.id`.
    */
-  protected abstract hydrate(ids: string[]): Promise<Map<string, unknown>>;
+  protected abstract hydrate(ids: string[], ctx?: ReadContext): Promise<Map<string, unknown>>;
 
   /** Provider payload → canonical record. Return `null` to drop a record. */
   protected abstract toCanonical(raw: unknown): T | null;
@@ -256,11 +285,14 @@ export abstract class IncrementalReadBase<T, F = unknown, M = Record<string, unk
    * adapter cannot hydrate-then-discard. A hydrate miss (deleted mid-run) is
    * skipped, never fabricated.
    */
-  async *read(req: ReadRequest<F>): AsyncIterable<SourcedRecord<T>> {
-    for await (const refPage of this.enumerate(req.mode, req.filter, req.pageSize)) {
+  async *read(req: ReadRequest<F>, ctx?: ReadContext): AsyncIterable<SourcedRecord<T>> {
+    for await (const refPage of this.enumerate(req.mode, req.filter, req.pageSize, ctx)) {
       const kept = refPage.filter((ref) => this.matchesRef(ref, req.filter));
       if (kept.length === 0) continue;
-      const raws = await this.hydrate(kept.map((ref) => ref.externalId));
+      const raws = await this.hydrate(
+        kept.map((ref) => ref.externalId),
+        ctx,
+      );
       for (const ref of kept) {
         const raw = raws.get(ref.externalId);
         if (raw === undefined || raw === null) continue; // deleted mid-run → skip
@@ -277,8 +309,8 @@ export abstract class IncrementalReadBase<T, F = unknown, M = Record<string, unk
    * `toCanonical ∘ hydrate([id])`. Reuses the adapter's batched fetch + miss
    * tolerance; returns `null` for a missing or undecodable record.
    */
-  async get(id: string): Promise<T | null> {
-    const raws = await this.hydrate([id]);
+  async get(id: string, ctx?: ReadContext): Promise<T | null> {
+    const raws = await this.hydrate([id], ctx);
     const raw = raws.get(id);
     if (raw === undefined || raw === null) return null;
     return this.toCanonical(raw);
@@ -308,7 +340,9 @@ export abstract class IncrementalReadBase<T, F = unknown, M = Record<string, unk
         ? { kind: 'full' }
         : { kind: 'delta', cursor };
     const filter = this.filterFor(subscription);
-    const stream = this.read({ mode, filter });
+    // R5: thread the run's subscription into the read body so `enumerate`/`hydrate`
+    // can resolve per-connection credentials (and raw-landing keys) from it.
+    const stream = this.read({ mode, filter }, { subscription });
 
     if (this.cursorDivisible) {
       for await (const sourced of stream) {

package/runtime/subsystems/integration/index.ts

@@ -101,6 +101,7 @@ export {
   mapConcurrent,
   type IncrementalRead,
   type RandomRead,
+  type ReadContext,
   type ReadMode,
   type ReadRequest,
   type Ref,

package/runtime/subsystems/jobs/bullmq.config.ts

@@ -6,6 +6,7 @@
  * `jobs.extensions.bullmq.*` config namespace (CLAUDE.md core/extension
  * protocol). The Drizzle backend never reads any of it.
  */
+import { tokenKey } from '../token-key';
 import { loadPoolConfig, type PoolConfig } from './pool-config.loader';
 
 /**
@@ -78,11 +79,13 @@ export interface BullMqResolvedConfig {
   bullBoard?: { enabled: boolean; mountPath: string };
 }
 
+// ADR-037: namespaced `Symbol.for(...)` (via `tokenKey()`) — matches by value
+// across runtime copies.
 /** DI token for the resolved BullMQ `ConnectionOptions` (ioredis-compatible). */
-export const BULLMQ_CONNECTION = Symbol('BULLMQ_CONNECTION');
+export const BULLMQ_CONNECTION = Symbol.for(tokenKey('jobs', 'bullmq-connection'));
 
 /** DI token for the full resolved BullMQ config (prefix + bull board). */
-export const BULLMQ_RESOLVED_CONFIG = Symbol('BULLMQ_RESOLVED_CONFIG');
+export const BULLMQ_RESOLVED_CONFIG = Symbol.for(tokenKey('jobs', 'bullmq-resolved-config'));
 
 const DEFAULT_REDIS_URL = 'redis://localhost:6379';
 const DEFAULT_BULL_BOARD_MOUNT = '/admin/queues';

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

@@ -16,6 +16,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 { JobRun } from './job-orchestrator.protocol';
 
@@ -160,7 +161,11 @@ export const JOB_HANDLER_REGISTRY = new Map<
   }
 >();
 
-export const JOB_HANDLER_METADATA_KEY = Symbol('JobHandlerMeta');
+// ADR-037: namespaced `Symbol.for(...)` (via `tokenKey()`) so the reflection-metadata
+// key matches by value across import boundaries (the @JobHandler decorator and the
+// reader may resolve different runtime copies). Distinct from the DI tokens but
+// subject to the same dual-package identity hazard.
+export const JOB_HANDLER_METADATA_KEY = Symbol.for(tokenKey('jobs', 'handler-metadata'));
 
 /**
  * Class decorator that registers a handler with the job type, the full

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

@@ -30,6 +30,7 @@ import {
   type OnModuleInit,
 } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
+import { tokenKey } from '../token-key';
 import { DRIZZLE } from '../../constants/tokens';
 import type { DrizzleClient } from '../../types/drizzle';
 import { HandlerRegistry, type HandlerRegistryEntry } from './job-handler.base';
@@ -128,8 +129,11 @@ export interface JobWorkerModuleOptions {
  * configuration — e.g. `BridgeModule.onModuleInit` checks
  * `options.pools` against `BRIDGE_RESERVED_POOLS` to fail fast when a
  * reserved pool isn't being polled (BRIDGE-8).
+ *
+ * ADR-037: namespaced `Symbol.for(...)` (via `tokenKey()`) — matches by value
+ * across runtime copies.
  */
-export const JOB_WORKER_MODULE_OPTIONS = Symbol('JOB_WORKER_MODULE_OPTIONS');
+export const JOB_WORKER_MODULE_OPTIONS = Symbol.for(tokenKey('jobs', 'worker-module-options'));
 
 /**
  * The lifecycle holder. Named `JobWorkerOrchestrator` in the spec to avoid

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

@@ -17,6 +17,7 @@ import { Inject, Injectable, Logger, type OnModuleDestroy, type OnModuleInit } f
 import { ModuleRef } from '@nestjs/core';
 import { and, asc, desc, eq, inArray, lt, lte, sql } from 'drizzle-orm';
 import type { DrizzleClient } from '../../types/drizzle';
+import { tokenKey } from '../token-key';
 import { DRIZZLE } from '../../constants/tokens';
 import { jobRuns, type JobRunRow } from './job-orchestration.schema';
 import type { IJobOrchestrator, JobRun } from './job-orchestrator.protocol';
@@ -60,7 +61,9 @@ export interface JobWorkerOptions {
   shutdownTimeoutMs?: number;
 }
 
-export const JOB_WORKER_OPTIONS = Symbol('JOB_WORKER_OPTIONS');
+// ADR-037: namespaced `Symbol.for(...)` (via `tokenKey()`) — matches by value
+// across runtime copies.
+export const JOB_WORKER_OPTIONS = Symbol.for(tokenKey('jobs', 'worker-options'));
 
 const DEFAULT_POLL_INTERVAL_MS = 1_000;
 const DEFAULT_STALE_SWEEPER_INTERVAL_MS = 60_000;

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

@@ -5,13 +5,16 @@
  * concrete backends (JOB-3 Drizzle, JOB-4 Memory) provide the implementations
  * through `JobsDomainModule.forRoot({ backend })` in JOB-5.
  *
- * Each token is a unique `Symbol` — guaranteed distinct from every other
- * Symbol at runtime, which is exactly the uniqueness guarantee Nest's DI
- * container relies on for token-based lookup.
+ * Each token is a namespaced `Symbol.for(...)` (ADR-037, via `tokenKey()`) —
+ * distinct per key, so Nest's DI lookup is unambiguous, AND matching by VALUE
+ * across import boundaries so the package and a (legacy) vendored runtime copy
+ * resolve to the same symbol.
  */
-export const JOB_ORCHESTRATOR = Symbol('JOB_ORCHESTRATOR');
-export const JOB_RUN_SERVICE = Symbol('JOB_RUN_SERVICE');
-export const JOB_STEP_SERVICE = Symbol('JOB_STEP_SERVICE');
+import { tokenKey } from '../token-key';
+
+export const JOB_ORCHESTRATOR = Symbol.for(tokenKey('jobs', 'orchestrator'));
+export const JOB_RUN_SERVICE = Symbol.for(tokenKey('jobs', 'run-service'));
+export const JOB_STEP_SERVICE = Symbol.for(tokenKey('jobs', 'step-service'));
 
 /**
  * Multi-tenancy opt-in flag (JOB-8). Bound to the boolean passed in via
@@ -27,4 +30,4 @@ export const JOB_STEP_SERVICE = Symbol('JOB_STEP_SERVICE');
  * tenant context; `tenantId` is populated at write time and enforced on
  * targeted reads. See docs/specs/JOB-8.md.
  */
-export const JOBS_MULTI_TENANT = Symbol('JOBS_MULTI_TENANT');
+export const JOBS_MULTI_TENANT = Symbol.for(tokenKey('jobs', 'multi-tenant'));

package/runtime/subsystems/storage/storage.tokens.ts

@@ -5,5 +5,10 @@
  * ```typescript
  * constructor(@Inject(STORAGE) private readonly storage: IStorageService) {}
  * ```
+ *
+ * ADR-037: namespaced `Symbol.for(...)` key (via `tokenKey()`) so the token matches
+ * by value across import boundaries (package vs vendored runtime copy).
  */
-export const STORAGE = Symbol('STORAGE');
+import { tokenKey } from '../token-key';
+
+export const STORAGE = Symbol.for(tokenKey('storage', 'storage'));

package/runtime/subsystems/token-key.ts

@@ -0,0 +1,7 @@
+/** Canonical package namespace for cross-boundary DI token keys. MUST be a hardcoded
+ *  constant (NOT derived from package.json) so a vendored copy — which lives inside the
+ *  CONSUMER's package — produces the identical key and the two copies share the symbol. */
+export const PKG = '@pattern-stack/codegen';
+// TODO(token-version): if/when a runtime contract version is adopted, inject it HERE only
+//   (e.g. `${PKG}#${ABI}.${area}.${name}`) — this helper is the single chokepoint.
+export const tokenKey = (area: string, name: string): string => `${PKG}.${area}.${name}`;

package/src/config/runtime-mode.mjs

@@ -0,0 +1,82 @@
+/**
+ * Runtime mode resolver — `.mjs` twin of `src/cli/shared/runtime-import.ts`
+ * (ADR-037), for the Hygen entity templates that run in a subprocess and can
+ * only import plain ESM. Keep the two in sync: both map a runtime mode +
+ * logical subpath to the concrete import specifier.
+ *
+ *   - `package`  → `@pattern-stack/codegen/subsystems` +
+ *                  `@pattern-stack/codegen/runtime/<relpath>`.
+ *   - `vendored` → `@shared/subsystems/<name>` + `@shared/<relpath>` (the
+ *                  convention the entity templates have always emitted).
+ *
+ * NOT routed through here: consumer-app files the package never owns and that
+ * `project init` always scaffolds locally regardless of mode —
+ * `@shared/database/*`, `@shared/http/*`, `@shared/openapi`, `@shared/pipes/*`,
+ * `@shared/connections/*`. Those stay `@shared/*` in both modes.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "yaml";
+
+const PACKAGE = "@pattern-stack/codegen";
+
+/**
+ * Read the `runtime` mode from `codegen.config.yaml` at `cwd`. Defaults to
+ * `package` (ADR-037) when the file/key is absent or invalid.
+ * @returns {'package' | 'vendored'}
+ */
+export function loadRuntimeMode(cwd = process.cwd()) {
+  const configPath = path.resolve(cwd, "codegen.config.yaml");
+  if (!fs.existsSync(configPath)) return "package";
+  try {
+    const parsed = yaml.parse(fs.readFileSync(configPath, "utf-8"));
+    return parsed?.runtime === "vendored" ? "vendored" : "package";
+  } catch {
+    return "package";
+  }
+}
+
+/**
+ * Import specifier for a subsystem barrel.
+ * @param {'package' | 'vendored'} mode
+ * @param {string} [subsystem] logical subsystem name (`events`, `integration`,
+ *   `auth`, …) — selects the vendored per-subsystem barrel; ignored in package
+ *   mode (one barrel serves all).
+ */
+export function subsystemsImport(mode, subsystem) {
+  if (mode === "vendored") {
+    return subsystem ? `@shared/subsystems/${subsystem}` : "@shared/subsystems";
+  }
+  return `${PACKAGE}/subsystems`;
+}
+
+/**
+ * Import specifier for a non-subsystem runtime file (base-classes, types,
+ * constants, helpers). `relpath` is the path under the runtime root WITHOUT a
+ * leading slash (e.g. `base-classes/integrated-entity-repository`,
+ * `constants/tokens`, `types/drizzle`, `eav-helpers`).
+ * @param {'package' | 'vendored'} mode
+ * @param {string} relpath
+ */
+export function runtimeImport(mode, relpath) {
+  const clean = String(relpath).replace(/^\/+/, "");
+  return mode === "vendored" ? `@shared/${clean}` : `${PACKAGE}/runtime/${clean}`;
+}
+
+/**
+ * Rewrite a legacy `@shared/<relpath>` specifier to the mode-correct form. Used
+ * to convert pattern-library base-class imports (authored as `@shared/...`) to
+ * the package form in package mode without duplicating the path in every
+ * pattern. A non-`@shared/` specifier (app-defined pattern alias, e.g.
+ * `@/patterns/...`) is returned untouched.
+ * @param {'package' | 'vendored'} mode
+ * @param {string} specifier
+ */
+export function rewriteSharedImport(mode, specifier) {
+  if (mode === "vendored") return specifier;
+  if (typeof specifier !== "string" || !specifier.startsWith("@shared/")) {
+    return specifier;
+  }
+  return runtimeImport(mode, specifier.slice("@shared/".length));
+}

package/templates/entity/new/backend/modules/core/integration-source.ejs.t

@@ -5,12 +5,13 @@ force: true
 ---
 <%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Module } from '@nestjs/common';
-import { buildChangeSource } from '@shared/subsystems/integration';
+<% const _integSubsys = typeof integrationSubsystemImport !== 'undefined' ? integrationSubsystemImport : '@shared/subsystems/integration'; -%>
+import { buildChangeSource } from '<%= _integSubsys %>';
 import type {
   DetectionConfig,
   IChangeSource,
   PollFetchCallback,
-} from '@shared/subsystems/integration';
+} from '<%= _integSubsys %>';
 import type { <%= className %> } from '<%= isCleanLitePs ? clpImports.integrationSourceToEntity : imports.moduleToDomain %>';
 
 const <%= name.toUpperCase() %>_DETECTION_CONFIGS: Record<string, DetectionConfig> = <%- detectionConfigsLiteral %>;

package/templates/entity/new/clean-lite-ps/controller.ejs.t

@@ -13,7 +13,7 @@ import { <%= classNames.findByIdWithFieldsUseCase %> } from './use-cases/find-<%
 import { <%= classNames.listWithFieldsUseCase %> } from './use-cases/list-<%= entityNamePlural %>-with-fields.use-case';
 <% } -%>
 <% if (generateWrites) { -%>
-import { ZodValidationPipe } from '@shared/pipes/zod-validation.pipe';
+import { ZodValidationPipe } from '<%= typeof zodValidationPipeImport !== 'undefined' ? zodValidationPipeImport : '@shared/pipes/zod-validation.pipe' %>';
 import { <%= classNames.createUseCase %> } from './use-cases/create-<%= entityName %>.use-case';
 import { <%= classNames.updateUseCase %> } from './use-cases/update-<%= entityName %>.use-case';
 import { <%= classNames.deleteUseCase %> } from './use-cases/delete-<%= entityName %>.use-case';

package/templates/entity/new/clean-lite-ps/module.ejs.t

@@ -12,7 +12,7 @@ force: true
  */
 <% } -%>
 import { Inject, Module, type OnModuleInit } from '@nestjs/common';
-import { OPENAPI_REGISTRY, type OpenApiRegistry } from '@shared/openapi';
+import { OPENAPI_REGISTRY, type OpenApiRegistry } from '<%= typeof openApiImport !== 'undefined' ? openApiImport : '@shared/openapi' %>';
 import { DatabaseModule } from '@shared/database/database.module';
 <%_ /* CGP-358b: Import cross-entity repos needed for has_many composition */ _%>
 <%_ if (typeof clpExistingHasMany !== 'undefined') { _%>

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

@@ -15,6 +15,7 @@ import pluralizePkg from 'pluralize';
 // globs before this helper runs — we only read the registry here.
 import { getPattern } from '../../../../src/patterns/registry.js';
 import '../../../../src/patterns/library/index.js';
+import { rewriteSharedImport } from '../../../../src/config/runtime-mode.mjs';
 
 // ============================================================================
 // Pattern registry resolution
@@ -1058,14 +1059,19 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
   // emitted output is byte-identical.
   const patternBase = resolvePatternBaseClasses(entity);
   const { patternName } = patternBase;
+  // Runtime mode (ADR-037) — rewrite library base-class imports authored as
+  // `@shared/base-classes/…` to the mode-correct form (package mode →
+  // `@pattern-stack/codegen/runtime/base-classes/…`). App-defined pattern
+  // aliases (non-`@shared/`) pass through untouched.
+  const runtimeMode = baseLocals?.runtimeMode === 'vendored' ? 'vendored' : 'package';
   // FAMILY_MAP is gone (PATTERN-5); `patternConfigClasses` is the structural
   // equivalent — repository + service class names + import paths + inherited
   // method comment lists, sourced directly from the pattern registry.
   const patternConfigClasses = {
     repositoryBaseClass: patternBase.repositoryBaseClass,
     serviceBaseClass: patternBase.serviceBaseClass,
-    repositoryBaseImport: patternBase.repositoryBaseImport,
-    serviceBaseImport: patternBase.serviceBaseImport,
+    repositoryBaseImport: rewriteSharedImport(runtimeMode, patternBase.repositoryBaseImport),
+    serviceBaseImport: rewriteSharedImport(runtimeMode, patternBase.serviceBaseImport),
     repositoryInheritedMethods: patternBase.repositoryInheritedMethods,
     serviceInheritedMethods: patternBase.serviceInheritedMethods,
   };

package/templates/entity/new/clean-lite-ps/repository.ejs.t

@@ -21,14 +21,14 @@ import { eq<%= hasMultiFieldQuery ? ', and' : '' %><%= hasOrderedQuery ? ', desc
 <% if (eavValueTable) { -%>
 import { sql } from 'drizzle-orm';
 <% } -%>
-import { DRIZZLE } from '@shared/constants/tokens';
-import type { DrizzleClient<% if (eavValueTable || (typeof hasIntegrationSurface !== 'undefined' && hasIntegrationSurface)) { %>, DrizzleTx<% } %> } from '@shared/types/drizzle';
+import { DRIZZLE } from '<%= typeof drizzleTokenImport !== 'undefined' ? drizzleTokenImport : '@shared/constants/tokens' %>';
+import type { DrizzleClient<% if (eavValueTable || (typeof hasIntegrationSurface !== 'undefined' && hasIntegrationSurface)) { %>, DrizzleTx<% } %> } from '<%= typeof drizzleTypeImport !== 'undefined' ? drizzleTypeImport : '@shared/types/drizzle' %>';
 import { <%= repositoryBaseClass %> } from '<%= repositoryBaseImport %>';
 <% if (typeof hasIntegrationSurface !== 'undefined' && hasIntegrationSurface) { -%>
-import type { IntegrationUpsertConfig } from '@shared/base-classes/integration-upsert-config';
+import type { IntegrationUpsertConfig } from '<%= typeof integrationUpsertConfigImport !== 'undefined' ? integrationUpsertConfigImport : '@shared/base-classes/integration-upsert-config' %>';
 <% } -%>
 <% if (hasTimestamps || hasSoftDelete || hasUserTracking) { -%>
-import type { BehaviorConfig } from '@shared/base-classes/base-repository';
+import type { BehaviorConfig } from '<%= typeof baseRepositoryImport !== 'undefined' ? baseRepositoryImport : '@shared/base-classes/base-repository' %>';
 <% } -%>
 <% if (eavEnabled) { -%>
 import { FieldValueService } from '../field_values/field_value.service';

package/templates/entity/new/clean-lite-ps/service.ejs.t

@@ -5,8 +5,8 @@ force: true
 ---
 <%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
 import { Injectable, Inject, Optional } from '@nestjs/common';
-import { WithAnalytics } from '@shared/base-classes/with-analytics';
-import { EVENT_BUS } from '@shared/constants/tokens';
+import { WithAnalytics } from '<%= typeof withAnalyticsImport !== 'undefined' ? withAnalyticsImport : '@shared/base-classes/with-analytics' %>';
+import { EVENT_BUS } from '<%= typeof drizzleTokenImport !== 'undefined' ? drizzleTokenImport : '@shared/constants/tokens' %>';
 import { <%= serviceBaseClass %> } from '<%= serviceBaseImport %>';
 import { <%= classNames.repository %> } from './<%= entityName %>.repository';
 import type { <%= classNames.entity %> } from './<%= entityName %>.entity';
@@ -14,8 +14,8 @@ import type { <%= classNames.entity %> } from './<%= entityName %>.entity';
 import { FieldValueService } from '../field_values/field_value.service';
 <% } -%>
 <% if (eavValueTable) { -%>
-import { toEavRows, mergeEavRows } from '@shared/eav-helpers';
-import type { DrizzleTx } from '@shared/types/drizzle';
+import { toEavRows, mergeEavRows } from '<%= typeof eavHelpersImport !== 'undefined' ? eavHelpersImport : '@shared/eav-helpers' %>';
+import type { DrizzleTx } from '<%= typeof drizzleTypeImport !== 'undefined' ? drizzleTypeImport : '@shared/types/drizzle' %>';
 import { <%= eavDefinitionPascal %>Repository } from '../<%= eavDefinitionEntityPlural %>/<%= eavDefinitionEntity %>.repository';
 <% } -%>
 <%_ /* CGP-358b — service-layer composition: import target repos for belongs_to relationships */ _%>