@pattern-stack/codegen 0.13.0 → 0.14.0

package/dist/src/cli/index.js

@@ -8105,164 +8105,35 @@ function validateEntityEmits(entities, events) {
 }
 
 // src/cli/shared/provider-module-generator.ts
-import { existsSync as existsSync9, mkdirSync as mkdirSync2, readFileSync as readFileSync7, statSync as statSync5, writeFileSync as writeFileSync2 } from "fs";
-import { dirname, isAbsolute as isAbsolute2, join as join11, resolve as resolve5 } from "path";
-function providerPascalCase(slug) {
-  return slug.split("-").filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
-}
-function providerConstantCase(slug) {
-  return slug.replace(/-/g, "_").toUpperCase();
-}
-function providerModuleBanner(sourceYaml) {
-  return `// @generated by @pattern-stack/codegen from ${sourceYaml} \u2014 DO NOT EDIT.
-// Hand edits are overwritten on re-emit. Regenerate with \`bun run codegen\`. To change this provider, edit its \`definitions/providers/*.yaml\`.`;
-}
-function generateProviderModule(def, sourceYaml) {
-  const { slug } = def;
-  const Pascal = providerPascalCase(slug);
-  const CONST = providerConstantCase(slug);
-  const strategy = parseImportRef(def.auth.strategy);
-  const client = parseImportRef(def.client.class);
-  const strategyToken = `${CONST}_AUTH_STRATEGY`;
-  const clientToken = `${CONST}_CLIENT`;
-  const surfaces = def.surfaces.join(", ");
-  const title = def.display_name ? `${def.display_name} (\`${slug}\`)` : `\`${slug}\``;
-  return `${providerModuleBanner(sourceYaml)}
-/**
- * Provider module for ${title}.
- *
- * Surfaces: ${surfaces}.
- *
- * Wires the declared auth strategy and API client under the provider-specific
- * DI tokens \`${strategyToken}\` and \`${clientToken}\`. Per the auth subsystem
- * contract, strategies are registered under provider-specific tokens rather
- * than a single \`AUTH_STRATEGY\`. Registry aggregation (RFC-0001 \xA73) is
- * emitted by a later codegen step.
- */
-import { Module } from '@nestjs/common';
-import { ${strategy.exportName} } from '${strategy.path}';
-import { ${client.exportName} } from '${client.path}';
+import { existsSync as existsSync10, mkdirSync as mkdirSync3, readFileSync as readFileSync8, statSync as statSync6, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname2, isAbsolute as isAbsolute2, join as join12, resolve as resolve6 } from "path";
 
-/** DI token for the \`${slug}\` provider's auth strategy. */
-export const ${strategyToken} = Symbol('${strategyToken}');
-/** DI token for the \`${slug}\` provider's API client. */
-export const ${clientToken} = Symbol('${clientToken}');
+// src/cli/shared/adapter-emission-generator.ts
+import {
+  existsSync as existsSync9,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync7,
+  statSync as statSync5,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { dirname, join as join11 } from "path";
 
-@Module({
-  providers: [
-    ${strategy.exportName},
-    ${client.exportName},
-    { provide: ${strategyToken}, useExisting: ${strategy.exportName} },
-    { provide: ${clientToken}, useExisting: ${client.exportName} },
-  ],
-  exports: [
-    ${strategy.exportName},
-    ${client.exportName},
-    ${strategyToken},
-    ${clientToken},
-  ],
-})
-export class ${Pascal}ProviderModule {}
-`;
-}
-function resolveTsconfigAliases(consumerRoot) {
-  const tsconfigPath = join11(consumerRoot, "tsconfig.json");
-  if (!existsSync9(tsconfigPath)) return null;
-  let parsed;
-  try {
-    parsed = JSON.parse(stripJsonComments(readFileSync7(tsconfigPath, "utf-8")));
-  } catch {
-    return null;
-  }
-  const compilerOptions = parsed.compilerOptions ?? {};
-  const baseUrl = compilerOptions.baseUrl ?? ".";
-  const sourceRoot = isAbsolute2(baseUrl) ? baseUrl : resolve5(consumerRoot, baseUrl);
-  const aliases = {};
-  for (const [pattern, targets] of Object.entries(compilerOptions.paths ?? {})) {
-    if (!Array.isArray(targets) || targets.length === 0) continue;
-    const aliasKey = pattern.replace(/\/\*$/, "");
-    const target = targets[0].replace(/\/\*$/, "");
-    aliases[aliasKey] = isAbsolute2(target) ? target : resolve5(sourceRoot, target);
-  }
-  return { sourceRoot, aliases };
-}
-function stripJsonComments(input) {
-  return input.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");
+// src/cli/shared/runtime-import.ts
+var PACKAGE = "@pattern-stack/codegen";
+function resolveRuntimeMode(config) {
+  return config?.runtime === "vendored" ? "vendored" : "package";
 }
-function generateProviderModules(opts) {
-  const base = {
-    providersDir: opts.providersDir,
-    skipped: false,
-    written: [],
-    loadFailures: [],
-    issues: []
-  };
-  if (!existsSync9(opts.providersDir) || !statSync5(opts.providersDir).isDirectory()) {
-    return { ...base, skipped: true };
-  }
-  const files = findYamlFiles(opts.providersDir);
-  if (files.length === 0) return { ...base, skipped: true };
-  const { successes, failures } = loadProvidersFromYaml(files);
-  const loaded = successes.map((s) => ({
-    definition: s.definition,
-    filePath: s.filePath
-  }));
-  const issues = failures.map((f) => ({
-    severity: "error",
-    type: "provider_load_failed",
-    message: `${f.error}${f.details?.length ? ` \u2014 ${f.details.join("; ")}` : ""}`,
-    path: f.filePath
-  }));
-  issues.push(
-    ...validateProviders(loaded, {
-      entitySurfaces: opts.entitySurfaces,
-      sourceRoot: opts.sourceRoot,
-      aliases: opts.aliases,
-      skipImportCheck: opts.skipImportCheck
-    })
-  );
-  if (issues.some((i) => i.severity === "error")) {
-    return { ...base, loadFailures: failures, issues };
-  }
-  const written = [];
-  for (const { definition, filePath } of loaded) {
-    const sourceYaml = relativeSource(filePath);
-    const content = generateProviderModule(definition, sourceYaml);
-    const outPath = join11(
-      opts.outputRoot,
-      definition.slug,
-      `${definition.slug}.provider.module.ts`
-    );
-    if (!opts.dryRun) {
-      writeIfChanged(outPath, content);
-    }
-    written.push(outPath);
+function subsystemsImport(mode, subsystem) {
+  if (mode === "vendored") {
+    return subsystem ? `@shared/subsystems/${subsystem}` : "@shared/subsystems";
   }
-  return { ...base, written, loadFailures: failures, issues };
-}
-function writeIfChanged(outPath, content) {
-  if (existsSync9(outPath) && readFileSync7(outPath, "utf-8") === content) return;
-  mkdirSync2(dirname(outPath), { recursive: true });
-  writeFileSync2(outPath, content);
+  return `${PACKAGE}/subsystems`;
 }
-function relativeSource(filePath) {
-  const marker = "definitions/providers/";
-  const idx = filePath.lastIndexOf(marker);
-  if (idx !== -1) return filePath.slice(idx);
-  const slash = filePath.lastIndexOf("/");
-  return slash === -1 ? filePath : `definitions/providers/${filePath.slice(slash + 1)}`;
+function runtimeImport(mode, relpath) {
+  const clean = relpath.replace(/^\/+/, "");
+  return mode === "vendored" ? `@shared/${clean}` : `${PACKAGE}/runtime/${clean}`;
 }
 
-// src/cli/shared/adapter-emission-generator.ts
-import {
-  existsSync as existsSync10,
-  mkdirSync as mkdirSync3,
-  readFileSync as readFileSync8,
-  statSync as statSync6,
-  writeFileSync as writeFileSync3
-} from "fs";
-import { dirname as dirname2, join as join12 } from "path";
-
 // src/cli/shared/sink-emission-generator.ts
 var SCAFFOLD_SENTINEL = "// <CODEGEN-SCAFFOLD-V1>";
 var USER_ID_FIELD = "userId";
@@ -8321,7 +8192,7 @@ function generateDefaultSink(input) {
 // for entities with external FK join-keys, fill the marked TODO(s) below.
 // Source: definitions entity '${input.entityName}' (surface: ${input.surface}).
 import { Injectable } from '@nestjs/common';
-import type { IIntegrationSink } from '@pattern-stack/codegen/subsystems';
+import type { IIntegrationSink } from '${subsystemsImport(input.mode ?? "package", "integration")}';
 import {
   ${n.repoClass},
   type ${n.projectionType},
@@ -8374,7 +8245,7 @@ function relationLabel(writeKey) {
 }
 
 // src/cli/shared/assembly-emission-generator.ts
-import { relative, resolve as resolve6, sep } from "path";
+import { relative, resolve as resolve5, sep } from "path";
 function generatedBanner(sourceDesc) {
   return `// @generated by @pattern-stack/codegen from ${sourceDesc} \u2014 DO NOT EDIT.
 // Hand edits are overwritten on re-emit. Regenerate with \`bun run codegen\`.`;
@@ -8412,7 +8283,7 @@ import {
   ExecuteIntegrationUseCase,
   INTEGRATION_CHANGE_SOURCE,
   INTEGRATION_SINK,
-} from '@pattern-stack/codegen/subsystems';
+} from '${subsystemsImport(input.mode ?? "package", "integration")}';
 import { ${adapterClass} } from '${adapterImport}';
 import { ${adapterModuleClass} } from '${adapterModuleImport}';
 import { ${sinkClass} } from '${sinkImport}';
@@ -8425,7 +8296,7 @@ import { ${token} } from '${tokensImport}';
  * inbound-integration assembly (RFC-0002 \xA72, Option A).
  *
  * Binds this module's INTEGRATION_CHANGE_SOURCE from the adapter's
- * \`changeSources['${input.entityName}']\` and INTEGRATION_SINK from
+ * \`changeSources.${input.entityName}\` and INTEGRATION_SINK from
  * ${sinkClass}, provides a local ExecuteIntegrationUseCase, and aliases+exports
  * it under ${token} (the bare class token is ambiguous at app root \u2014 every
  * assembly provides it). The substrate (cursor store, run recorder, differ,
@@ -8437,7 +8308,7 @@ import { ${token} } from '${tokensImport}';
   providers: [
     {
       provide: INTEGRATION_CHANGE_SOURCE,
-      useFactory: (adapter: ${adapterClass}) => adapter.changeSources['${input.entityName}'],
+      useFactory: (adapter: ${adapterClass}) => adapter.changeSources.${input.entityName},
       inject: [${adapterClass}],
     },
     {
@@ -8539,17 +8410,17 @@ function resolveEntityModuleImports(input) {
   const repoClass = `${entityClass}Repository`;
   const moduleClass = `${pluralPascalCase(input.entityPlural)}Module`;
   const moduleGroupSegs = input.context ? ["modules", input.context, input.entityPlural] : ["modules", input.entityPlural];
-  const repoFileAbs = resolve6(
+  const repoFileAbs = resolve5(
     input.backendSrcAbs,
     ...moduleGroupSegs,
     `${input.entityName}.repository.ts`
   );
-  const moduleFileAbs = resolve6(
+  const moduleFileAbs = resolve5(
     input.backendSrcAbs,
     ...moduleGroupSegs,
     `${input.entityPlural}.module.ts`
   );
-  const assemblyDirAbs = resolve6(
+  const assemblyDirAbs = resolve5(
     input.backendSrcAbs,
     "integrations",
     input.surface,
@@ -8623,8 +8494,24 @@ var SURFACE_REGISTRY = {
     noCapsConst: "NO_TRANSCRIPT_CAPABILITIES",
     l2Ports: [],
     readPrimitive: true
+  },
+  // messaging (swe-brain ADR-0008) — interaction surface like transcript: the
+  // adapter contributes per-entity change sources for `channel` + `message`
+  // (`conversation` is domain-derived by segmentation, not vendor-read). The
+  // capability descriptor adds an optional `canWrite` flag for the bot-user write
+  // path, which ships dark in v1; the scaffold still only constructs `entities`.
+  messaging: {
+    packageName: "@pattern-stack/codegen-messaging",
+    portType: "MessagingPort",
+    capabilitiesType: "MessagingCapabilities",
+    noCapsConst: "NO_MESSAGING_CAPABILITIES",
+    l2Ports: [],
+    readPrimitive: true
   }
 };
+function isClientlessProvider(surfaces) {
+  return surfaces.length > 0 && surfaces.every((s) => SURFACE_REGISTRY[s]?.readPrimitive === true);
+}
 var SCAFFOLD_SENTINEL2 = "// <CODEGEN-SCAFFOLD-V1>";
 function generatedBanner2(sourceDesc) {
   return `// @generated by @pattern-stack/codegen from ${sourceDesc} \u2014 DO NOT EDIT.
@@ -8679,7 +8566,7 @@ function serializeFilterArray(filters) {
 ${items.join("\n")}
 ]`;
 }
-function buildReadPrimitiveEmission(providerSlug, providerPascal, surface, entities, entityDetection, clientExportName) {
+function buildReadPrimitiveEmission(providerSlug, providerPascal, surface, entities, entityDetection) {
   const canonicalTypes = [];
   const blocks = [];
   const entries = [];
@@ -8711,24 +8598,32 @@ export class ${className} extends IncrementalReadBase<${canonical}, ResolvedFilt
   // (e.g. Gmail \`q=\`); leave \`false\` to filter post-hydrate via \`matchesRecord\`.
   protected override readonly filterPushdown = false;${cursorOverride}
 
-  constructor(
-    private readonly auth: IAuthStrategy,
-    private readonly client: ${clientExportName},
-  ) {
+  constructor(private readonly auth: IAuthStrategy) {
     super();
   }
 
-  /** TODO: walk the vendor list endpoint \u2192 pages of \`Ref\` (id + cursor + meta). */
+  /**
+   * TODO: walk the vendor list endpoint \u2192 pages of \`Ref\` (id + cursor + meta).
+   * Per-connection (multi-account) adapters resolve credentials here from the
+   * threaded subscription, e.g.
+   * \`const client = <vendorClientFactory>({ accessToken: async () => (await this.auth.resolve(_ctx!.subscription!.externalRef)).accessToken });\`
+   * \u2014 there is no provider-level singleton client. Provider-level-auth adapters
+   * ignore \`_ctx\`.
+   */
   protected async *enumerate(
     _mode: ReadMode,
     _filter?: ResolvedFilter[],
     _pageSize?: number,
+    _ctx?: ReadContext,
   ): AsyncIterable<Ref[]> {
     throw new Error('not implemented: ${className}.enumerate');
   }
 
-  /** TODO: batched fetch-by-id \u2192 \`Map<id, raw>\` (\`mapConcurrent\`, or a vendor /batch). */
-  protected async hydrate(_ids: string[]): Promise<Map<string, unknown>> {
+  /**
+   * TODO: batched fetch-by-id \u2192 \`Map<id, raw>\` (\`mapConcurrent\`, or a vendor /batch).
+   * Use \`_ctx?.subscription?.id\` to key raw-landing rows per connection.
+   */
+  protected async hydrate(_ids: string[], _ctx?: ReadContext): Promise<Map<string, unknown>> {
     throw new Error('not implemented: ${className}.hydrate');
   }
 
@@ -8743,15 +8638,16 @@ export class ${className} extends IncrementalReadBase<${canonical}, ResolvedFilt
     return ${constName};
   }
 }`);
-    entries.push(`      ${entity}: new ${className}(this.auth, this.client),`);
+    entries.push(`      ${entity}: new ${className}(this.auth),`);
   }
   return { canonicalTypes, preamble: blocks.join("\n\n"), changeSourceEntries: entries };
 }
-function generateAdapterScaffold(def, surface, entities, entityDetection) {
+function generateAdapterScaffold(def, surface, entities, entityDetection, mode = "package") {
   const spec = SURFACE_REGISTRY[surface];
   if (!spec) throw new Error(`no surface package for '${surface}'`);
   const n = names(def.slug, surface);
   const client = parseImportRef(def.client.class);
+  const subsystemsSpec = subsystemsImport(mode, "integration");
   const entitiesLiteral = entities.length ? `[${entities.map((e) => `'${e}'`).join(", ")}]` : "[]";
   const readPrimitive = !!spec.readPrimitive && entities.length > 0;
   const rp = readPrimitive ? buildReadPrimitiveEmission(
@@ -8759,21 +8655,26 @@ function generateAdapterScaffold(def, surface, entities, entityDetection) {
     n.providerPascal,
     surface,
     entities,
-    entityDetection,
-    client.exportName
+    entityDetection
   ) : null;
   const surfaceTypeImports = [
     spec.portType,
     ...spec.l2Ports.map((p) => p.type),
     spec.capabilitiesType,
     ...rp ? rp.canonicalTypes : []
-  ].map((t) => `  ${t},`).join("\n");
-  const subsystemValueImport = rp ? `import { IncrementalReadBase } from '@pattern-stack/codegen/subsystems';
+  ].sort().map((t) => `  ${t},`).join("\n");
+  const subsystemValueImport = rp ? `import { IncrementalReadBase } from '${subsystemsSpec}';
 ` : "";
   const subsystemTypeImports = [
     "IAuthStrategy",
     "IChangeSource",
-    ...rp ? ["IntegrationSubscriptionView", "ReadMode", "Ref", "ResolvedFilter"] : []
+    ...rp ? [
+      "IntegrationSubscriptionView",
+      "ReadContext",
+      "ReadMode",
+      "Ref",
+      "ResolvedFilter"
+    ] : []
   ].map((t) => `  ${t},`).join("\n");
   const changeSourcesAssign = rp ? `
     this.changeSources = {
@@ -8813,6 +8714,14 @@ ${rp.preamble}
   const l2Section = l2Members ? `
 ${l2Members}
 ` : "";
+  const clientTypeImport = rp ? "" : `import type { ${client.exportName} } from '${client.path}';
+`;
+  const providerTokenImport = rp ? `import { ${n.strategyToken} } from '../../../providers/${def.slug}/${def.slug}.provider.module';` : `import { ${n.strategyToken}, ${n.clientToken} } from '../../../providers/${def.slug}/${def.slug}.provider.module';`;
+  const ctorClientParam = rp ? "" : `
+    @Inject(${n.clientToken}) private readonly client: ${client.exportName},`;
+  const ctorOpen = rp ? `  constructor(@Inject(${n.strategyToken}) readonly auth: IAuthStrategy) {${changeSourcesAssign}}` : `  constructor(
+    @Inject(${n.strategyToken}) readonly auth: IAuthStrategy,${ctorClientParam}
+  ) {${changeSourcesAssign}}`;
   return `${SCAFFOLD_SENTINEL2}
 // Scaffolded once by @pattern-stack/codegen, then author-owned. Re-running
 // codegen detects the sentinel above and SKIPS this file \u2014 your edits are safe.
@@ -8824,9 +8733,8 @@ ${surfaceTypeImports}
 import { ${spec.noCapsConst} } from '${spec.packageName}';
 ${subsystemValueImport}import type {
 ${subsystemTypeImports}
-} from '@pattern-stack/codegen/subsystems';
-import type { ${client.exportName} } from '${client.path}';
-import { ${n.strategyToken}, ${n.clientToken} } from '../../../providers/${def.slug}/${def.slug}.provider.module';
+} from '${subsystemsSpec}';
+${clientTypeImport}${providerTokenImport}
 ${preambleSection}
 @Injectable()
 export class ${n.adapterClass} implements ${spec.portType} {
@@ -8835,10 +8743,7 @@ export class ${n.adapterClass} implements ${spec.portType} {
 ${capabilityBody}
   };
 
-  constructor(
-    @Inject(${n.strategyToken}) readonly auth: IAuthStrategy,
-    @Inject(${n.clientToken}) private readonly client: ${client.exportName},
-  ) {${changeSourcesAssign}}
+${ctorOpen}
 ${l2Section}
 ${changeSourcesDecl}
 
@@ -8870,10 +8775,10 @@ function generateAdaptersBarrel(surface, providerSlugs) {
 ${lines}
 `;
 }
-function generateSurfaceTokens(surface) {
+function generateSurfaceTokens(surface, mode = "package") {
   const n = names("__placeholder__", surface);
   return `${generatedBanner2(`surface: ${surface}`)}
-import type { IChangeSource } from '@pattern-stack/codegen/subsystems';
+import type { IChangeSource } from '${subsystemsImport(mode, "integration")}';
 
 /** The assembled list of every ${surface} adapter's contribution. */
 export const ${n.contributionsToken} = Symbol.for('@app/integrations/${surface}.adapter-contributions');
@@ -8890,7 +8795,7 @@ export interface AdapterContribution {
 }
 `;
 }
-function generateSurfaceAggregator(surface, providerSlugs) {
+function generateSurfaceAggregator(surface, providerSlugs, mode = "package") {
   const n = names("__placeholder__", surface);
   const slugs = [...providerSlugs].sort();
   const per = slugs.map((slug) => names(slug, surface));
@@ -8917,7 +8822,7 @@ import {
   MemoryEntityChangeSourceRegistry,
   type IChangeSource,
   type IEntityChangeSourceRegistry,
-} from '@pattern-stack/codegen/subsystems';
+} from '${subsystemsImport(mode, "integration")}';
 ${moduleImport}
 ${adapterImports}
 import {
@@ -9006,6 +8911,7 @@ function jsKey(key) {
   return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : `'${key}'`;
 }
 function emitAdapters(opts) {
+  const mode = opts.mode ?? "package";
   const result = {
     written: [],
     scaffoldsWritten: [],
@@ -9036,14 +8942,14 @@ function emitAdapters(opts) {
   }
   const defBySlug = new Map(opts.providers.map((p) => [p.definition.slug, p.definition]));
   for (const [surface, slugs] of bySurface) {
-    const surfaceDir = join12(opts.outputRoot, surface);
-    const adaptersDir = join12(surfaceDir, "adapters");
+    const surfaceDir = join11(opts.outputRoot, surface);
+    const adaptersDir = join11(surfaceDir, "adapters");
     for (const slug of slugs) {
       const def = defBySlug.get(slug);
-      const providerDir = join12(adaptersDir, slug);
-      const scaffoldPath = join12(providerDir, `${slug}-${surface}.adapter.ts`);
-      const modulePath = join12(providerDir, `${slug}-${surface}.adapter.module.ts`);
-      if (existsSync10(scaffoldPath)) {
+      const providerDir = join11(adaptersDir, slug);
+      const scaffoldPath = join11(providerDir, `${slug}-${surface}.adapter.ts`);
+      const modulePath = join11(providerDir, `${slug}-${surface}.adapter.module.ts`);
+      if (existsSync9(scaffoldPath)) {
         result.scaffoldsSkipped.push(scaffoldPath);
       } else {
         const surfaceEntityNames = entitiesBySurface.get(surface) ?? [];
@@ -9056,27 +8962,28 @@ function emitAdapters(opts) {
           def,
           surface,
           surfaceEntityNames,
-          entityDetection
+          entityDetection,
+          mode
         );
         if (!opts.dryRun) writeFile(scaffoldPath, content);
         result.scaffoldsWritten.push(scaffoldPath);
       }
       const moduleContent = generateAdapterModule(def, surface);
-      if (!opts.dryRun) writeIfChanged2(modulePath, moduleContent);
+      if (!opts.dryRun) writeIfChanged(modulePath, moduleContent);
       result.written.push(modulePath);
     }
-    const barrelPath = join12(adaptersDir, "index.ts");
-    const tokensPath = join12(surfaceDir, `${surface}-adapters.tokens.ts`);
-    const aggregatorPath = join12(surfaceDir, `${surface}-adapters.module.ts`);
-    const typedViewPath = join12(surfaceDir, "types.generated.ts");
+    const barrelPath = join11(adaptersDir, "index.ts");
+    const tokensPath = join11(surfaceDir, `${surface}-adapters.tokens.ts`);
+    const aggregatorPath = join11(surfaceDir, `${surface}-adapters.module.ts`);
+    const typedViewPath = join11(surfaceDir, "types.generated.ts");
     const files = [
       [barrelPath, generateAdaptersBarrel(surface, slugs)],
-      [tokensPath, generateSurfaceTokens(surface)],
-      [aggregatorPath, generateSurfaceAggregator(surface, slugs)],
+      [tokensPath, generateSurfaceTokens(surface, mode)],
+      [aggregatorPath, generateSurfaceAggregator(surface, slugs, mode)],
       [typedViewPath, generateTypedView(surface, slugs, entitiesBySurface.get(surface) ?? [])]
     ];
     for (const [path34, content] of files) {
-      if (!opts.dryRun) writeIfChanged2(path34, content);
+      if (!opts.dryRun) writeIfChanged(path34, content);
       result.written.push(path34);
     }
     if (opts.backendSrcAbs) {
@@ -9084,8 +8991,8 @@ function emitAdapters(opts) {
       const surfaceEntities = entitiesBySurface.get(surface) ?? [];
       const tokenEntries = [];
       const assemblyEntries = [];
-      const sinksDir = join12(surfaceDir, "sinks");
-      const modulesDir = join12(surfaceDir, "modules");
+      const sinksDir = join11(surfaceDir, "sinks");
+      const modulesDir = join11(surfaceDir, "modules");
       for (const entityName of surfaceEntities) {
         const def = entityByName.get(entityName);
         const pattern = def?.entity.pattern ?? (Array.isArray(def?.entity.patterns) ? def?.entity.patterns?.[0] : void 0);
@@ -9110,17 +9017,17 @@ function emitAdapters(opts) {
           backendSrcAbs: opts.backendSrcAbs,
           aliases
         });
-        const sinkPath = join12(sinksDir, `${entityName}.sink.ts`);
-        if (existsSync10(sinkPath)) {
+        const sinkPath = join11(sinksDir, `${entityName}.sink.ts`);
+        if (existsSync9(sinkPath)) {
           result.scaffoldsSkipped.push(sinkPath);
         } else {
           const sinkInput = buildSinkInput(def, surface, slugs[0], loc.repoImportSpecifier);
-          const sinkContent = generateDefaultSink(sinkInput);
+          const sinkContent = generateDefaultSink({ ...sinkInput, mode });
           if (!opts.dryRun) writeFile(sinkPath, sinkContent);
           result.scaffoldsWritten.push(sinkPath);
         }
         for (const slug of slugs) {
-          const assemblyPath = join12(
+          const assemblyPath = join11(
             modulesDir,
             slug,
             `${entityName}-integration.module.ts`
@@ -9134,23 +9041,24 @@ function emitAdapters(opts) {
             moduleClass: loc.moduleClass,
             repoImportSpecifier: loc.repoImportSpecifier,
             repoClass: loc.repoClass,
-            sourceDesc: `definitions/providers/${slug}.yaml`
+            sourceDesc: `definitions/providers/${slug}.yaml`,
+            mode
           });
-          if (!opts.dryRun) writeIfChanged2(assemblyPath, assemblyContent);
+          if (!opts.dryRun) writeIfChanged(assemblyPath, assemblyContent);
           result.assembliesWritten.push(assemblyPath);
           tokenEntries.push({ entityName, entityClass: loc.entityClass, provider: slug });
           assemblyEntries.push({ entityName, provider: slug });
         }
       }
-      const integrationTokensPath = join12(
+      const integrationTokensPath = join11(
         surfaceDir,
         `${surface}-integration.tokens.ts`
       );
       const tokensContent = generateIntegrationTokens(surface, tokenEntries);
-      if (!opts.dryRun) writeIfChanged2(integrationTokensPath, tokensContent);
+      if (!opts.dryRun) writeIfChanged(integrationTokensPath, tokensContent);
       result.tokensWritten.push(integrationTokensPath);
       if (assemblyEntries.length > 0) {
-        const integrationAggregatorPath = join12(
+        const integrationAggregatorPath = join11(
           surfaceDir,
           `${surface}-integration.module.ts`
         );
@@ -9158,7 +9066,7 @@ function emitAdapters(opts) {
           surface,
           assemblyEntries
         );
-        if (!opts.dryRun) writeIfChanged2(integrationAggregatorPath, aggregatorContent);
+        if (!opts.dryRun) writeIfChanged(integrationAggregatorPath, aggregatorContent);
         result.integrationAggregatorsWritten.push(integrationAggregatorPath);
       }
     }
@@ -9215,16 +9123,212 @@ function pascalFromSnake(s) {
   return camel.charAt(0).toUpperCase() + camel.slice(1);
 }
 function writeFile(outPath, content) {
-  mkdirSync3(dirname2(outPath), { recursive: true });
-  writeFileSync3(outPath, content);
+  mkdirSync2(dirname(outPath), { recursive: true });
+  writeFileSync2(outPath, content);
 }
-function writeIfChanged2(outPath, content) {
-  if (existsSync10(outPath) && statSync6(outPath).isFile() && readFileSync8(outPath, "utf-8") === content) {
+function writeIfChanged(outPath, content) {
+  if (existsSync9(outPath) && statSync5(outPath).isFile() && readFileSync7(outPath, "utf-8") === content) {
     return;
   }
   writeFile(outPath, content);
 }
 
+// src/cli/shared/provider-module-generator.ts
+function providerPascalCase(slug) {
+  return slug.split("-").filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function providerConstantCase(slug) {
+  return slug.replace(/-/g, "_").toUpperCase();
+}
+function providerModuleBanner(sourceYaml) {
+  return `// @generated by @pattern-stack/codegen from ${sourceYaml} \u2014 DO NOT EDIT.
+// Hand edits are overwritten on re-emit. Regenerate with \`bun run codegen\`. To change this provider, edit its \`definitions/providers/*.yaml\`.`;
+}
+function generateProviderModule(def, sourceYaml, mode = "package") {
+  const { slug } = def;
+  const Pascal = providerPascalCase(slug);
+  const CONST = providerConstantCase(slug);
+  const strategy = parseImportRef(def.auth.strategy);
+  const client = parseImportRef(def.client.class);
+  const strategyToken = `${CONST}_AUTH_STRATEGY`;
+  const clientToken = `${CONST}_CLIENT`;
+  const surfaces = def.surfaces.join(", ");
+  const title = def.display_name ? `${def.display_name} (\`${slug}\`)` : `\`${slug}\``;
+  if (isClientlessProvider(def.surfaces)) {
+    return `${providerModuleBanner(sourceYaml)}
+/**
+ * Provider module for ${title}.
+ *
+ * Surfaces: ${surfaces}.
+ *
+ * Per-connection (read-primitive) provider \u2014 exposes \`${strategyToken}\`, the
+ * per-connection credential resolver the interaction adapters use (RFC-0003 R5:
+ * \`auth.resolve(ctx.subscription.externalRef)\`). There is NO provider-level
+ * singleton client; adapters build a per-connection client inside their
+ * \`enumerate\`/\`hydrate\`. \`${strategyToken}\` resolves the already-built
+ * \`${slug}\` strategy from the @Global \`STRATEGY_REGISTRY\` (wired by the
+ * consumer's AuthBindings module) \u2014 the strategy may need DI deps a bare class
+ * can't satisfy, so it is registry-resolved, not provided directly.
+ */
+import { Module } from '@nestjs/common';
+import {
+  type ProviderStrategyRegistry,
+  STRATEGY_REGISTRY,
+} from '${subsystemsImport(mode, "auth")}';
+
+/** DI token for the \`${slug}\` provider's auth strategy (resolved from STRATEGY_REGISTRY). */
+export const ${strategyToken} = Symbol('${strategyToken}');
+
+const PROVIDER_SLUG = '${slug}';
+
+@Module({
+  providers: [
+    {
+      provide: ${strategyToken},
+      useFactory: (registry: ProviderStrategyRegistry) => {
+        const strategy = registry.get(PROVIDER_SLUG);
+        if (!strategy) {
+          throw new Error(
+            \`${Pascal}ProviderModule: no '\${PROVIDER_SLUG}' strategy registered in STRATEGY_REGISTRY (wire it in your consumer AuthBindings module)\`,
+          );
+        }
+        return strategy;
+      },
+      inject: [STRATEGY_REGISTRY],
+    },
+  ],
+  exports: [${strategyToken}],
+})
+export class ${Pascal}ProviderModule {}
+`;
+  }
+  return `${providerModuleBanner(sourceYaml)}
+/**
+ * Provider module for ${title}.
+ *
+ * Surfaces: ${surfaces}.
+ *
+ * Wires the declared auth strategy and API client under the provider-specific
+ * DI tokens \`${strategyToken}\` and \`${clientToken}\`. Per the auth subsystem
+ * contract, strategies are registered under provider-specific tokens rather
+ * than a single \`AUTH_STRATEGY\`. Registry aggregation (RFC-0001 \xA73) is
+ * emitted by a later codegen step.
+ */
+import { Module } from '@nestjs/common';
+import { ${strategy.exportName} } from '${strategy.path}';
+import { ${client.exportName} } from '${client.path}';
+
+/** DI token for the \`${slug}\` provider's auth strategy. */
+export const ${strategyToken} = Symbol('${strategyToken}');
+/** DI token for the \`${slug}\` provider's API client. */
+export const ${clientToken} = Symbol('${clientToken}');
+
+@Module({
+  providers: [
+    ${strategy.exportName},
+    ${client.exportName},
+    { provide: ${strategyToken}, useExisting: ${strategy.exportName} },
+    { provide: ${clientToken}, useExisting: ${client.exportName} },
+  ],
+  exports: [
+    ${strategy.exportName},
+    ${client.exportName},
+    ${strategyToken},
+    ${clientToken},
+  ],
+})
+export class ${Pascal}ProviderModule {}
+`;
+}
+function resolveTsconfigAliases(consumerRoot) {
+  const tsconfigPath = join12(consumerRoot, "tsconfig.json");
+  if (!existsSync10(tsconfigPath)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(stripJsonComments(readFileSync8(tsconfigPath, "utf-8")));
+  } catch {
+    return null;
+  }
+  const compilerOptions = parsed.compilerOptions ?? {};
+  const baseUrl = compilerOptions.baseUrl ?? ".";
+  const sourceRoot = isAbsolute2(baseUrl) ? baseUrl : resolve6(consumerRoot, baseUrl);
+  const aliases = {};
+  for (const [pattern, targets] of Object.entries(compilerOptions.paths ?? {})) {
+    if (!Array.isArray(targets) || targets.length === 0) continue;
+    const aliasKey = pattern.replace(/\/\*$/, "");
+    const target = targets[0].replace(/\/\*$/, "");
+    aliases[aliasKey] = isAbsolute2(target) ? target : resolve6(sourceRoot, target);
+  }
+  return { sourceRoot, aliases };
+}
+function stripJsonComments(input) {
+  return input.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");
+}
+function generateProviderModules(opts) {
+  const base = {
+    providersDir: opts.providersDir,
+    skipped: false,
+    written: [],
+    loadFailures: [],
+    issues: []
+  };
+  if (!existsSync10(opts.providersDir) || !statSync6(opts.providersDir).isDirectory()) {
+    return { ...base, skipped: true };
+  }
+  const files = findYamlFiles(opts.providersDir);
+  if (files.length === 0) return { ...base, skipped: true };
+  const { successes, failures } = loadProvidersFromYaml(files);
+  const loaded = successes.map((s) => ({
+    definition: s.definition,
+    filePath: s.filePath
+  }));
+  const issues = failures.map((f) => ({
+    severity: "error",
+    type: "provider_load_failed",
+    message: `${f.error}${f.details?.length ? ` \u2014 ${f.details.join("; ")}` : ""}`,
+    path: f.filePath
+  }));
+  issues.push(
+    ...validateProviders(loaded, {
+      entitySurfaces: opts.entitySurfaces,
+      sourceRoot: opts.sourceRoot,
+      aliases: opts.aliases,
+      skipImportCheck: opts.skipImportCheck
+    })
+  );
+  if (issues.some((i) => i.severity === "error")) {
+    return { ...base, loadFailures: failures, issues };
+  }
+  const mode = opts.mode ?? "package";
+  const written = [];
+  for (const { definition, filePath } of loaded) {
+    const sourceYaml = relativeSource(filePath);
+    const content = generateProviderModule(definition, sourceYaml, mode);
+    const outPath = join12(
+      opts.outputRoot,
+      definition.slug,
+      `${definition.slug}.provider.module.ts`
+    );
+    if (!opts.dryRun) {
+      writeIfChanged2(outPath, content);
+    }
+    written.push(outPath);
+  }
+  return { ...base, written, loadFailures: failures, issues };
+}
+function writeIfChanged2(outPath, content) {
+  if (existsSync10(outPath) && readFileSync8(outPath, "utf-8") === content) return;
+  mkdirSync3(dirname2(outPath), { recursive: true });
+  writeFileSync3(outPath, content);
+}
+function relativeSource(filePath) {
+  const marker = "definitions/providers/";
+  const idx = filePath.lastIndexOf(marker);
+  if (idx !== -1) return filePath.slice(idx);
+  const slash = filePath.lastIndexOf("/");
+  return slash === -1 ? filePath : `definitions/providers/${filePath.slice(slash + 1)}`;
+}
+
 // src/cli/shared/events-path.ts
 import path12 from "path";
 var FALLBACK = "events";
@@ -9504,6 +9608,7 @@ var EntityNewCommand = class extends Command2 {
       "bridge/generated"
     );
     const backendSrcForHandlers = ctx.config?.paths?.backend_src ?? "src";
+    const runtimeMode = resolveRuntimeMode(ctx.config);
     const bridgeHandlersDir = path13.resolve(
       ctx.cwd,
       backendSrcForHandlers,
@@ -9790,7 +9895,8 @@ var EntityNewCommand = class extends Command2 {
         entitySurfaces,
         sourceRoot: tsAliases?.sourceRoot,
         aliases: tsAliases?.aliases,
-        skipImportCheck: tsAliases === null
+        skipImportCheck: tsAliases === null,
+        mode: runtimeMode
       });
       if (!providerResult.skipped && !isJsonMode()) {
         for (const issue of providerResult.issues) {
@@ -9834,7 +9940,8 @@ var EntityNewCommand = class extends Command2 {
           entities: entityDefs,
           outputRoot: adapterOutputRoot,
           backendSrcAbs: path13.resolve(ctx.cwd, backendSrcForHandlers),
-          aliases: assemblyTsAliases?.aliases ?? {}
+          aliases: assemblyTsAliases?.aliases ?? {},
+          mode: runtimeMode
         });
         if (!isJsonMode()) {
           if (adapterResult.written.length || adapterResult.scaffoldsWritten.length) {
@@ -11907,12 +12014,13 @@ var VENDORED_RUNTIME_FILES = [
   },
   { runtime: "shared/openapi/index.ts", target: "src/shared/openapi/index.ts" }
 ];
-function databaseModuleContent() {
+function databaseModuleContent(mode) {
+  const drizzleTokenImport = mode === "vendored" ? "../constants/tokens" : runtimeImport(mode, "constants/tokens");
   return `import { Module, Global } from '@nestjs/common';
 import { drizzle } from 'drizzle-orm/node-postgres';
 import { Pool } from 'pg';
 import * as schema from '../../schema';
-import { DRIZZLE } from '../constants/tokens';
+import { DRIZZLE } from '${drizzleTokenImport}';
 
 export { DRIZZLE };
 export type DrizzleDB = ReturnType<typeof drizzle<typeof schema>>;
@@ -11939,11 +12047,12 @@ export type DrizzleDB = ReturnType<typeof drizzle<typeof schema>>;
 export class DatabaseModule {}
 `;
 }
-function appModuleContent() {
+function appModuleContent(mode) {
+  const openApiImport = mode === "vendored" ? "./shared/openapi" : runtimeImport(mode, "shared/openapi");
   return `import { Global, Module } from '@nestjs/common';
 import { DatabaseModule } from './shared/database/database.module';
 import { GENERATED_MODULES } from './generated/modules';
-import { OPENAPI_REGISTRY, OpenApiRegistry } from './shared/openapi';
+import { OPENAPI_REGISTRY, OpenApiRegistry } from '${openApiImport}';
 
 /**
  * OpenApiModule \u2014 @Global() wrapper around the OPENAPI_REGISTRY singleton.
@@ -11985,7 +12094,8 @@ class OpenApiModule {}
 export class AppModule {}
 `;
 }
-function mainTsContent() {
+function mainTsContent(mode) {
+  const openApiImport = mode === "vendored" ? "./shared/openapi" : runtimeImport(mode, "shared/openapi");
   return `import 'reflect-metadata';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -11993,7 +12103,7 @@ import { NestFactory } from '@nestjs/core';
 import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
 import { parse as parseYaml } from 'yaml';
 import { AppModule } from './app.module';
-import { OPENAPI_REGISTRY, OpenApiRegistry } from './shared/openapi';
+import { OPENAPI_REGISTRY, OpenApiRegistry } from '${openApiImport}';
 
 interface OpenApiConfig {
   enabled?: boolean;
@@ -12302,6 +12412,7 @@ function dirEntry(cwd, absPath) {
 async function buildInitPlan(ctx, options) {
   const cwd = options.cwd;
   const force = Boolean(options.force);
+  const runtimeMode = options.runtimeMode === "vendored" ? "vendored" : "package";
   let framework = "nestjs";
   let orm = "drizzle";
   let architecture = "clean-lite-ps";
@@ -12324,6 +12435,11 @@ async function buildInitPlan(ctx, options) {
   {
     const configPath = path23.join(cwd, "codegen.config.yaml");
     const config = {
+      // Runtime mode (ADR-037). `package` (default) imports the runtime from
+      // `@pattern-stack/codegen/*`; `vendored` imports it via `@shared/*` and
+      // vendors `src/shared/**`. Existing vendored projects MUST set this to
+      // `vendored` explicitly — the default does not silently flip them.
+      runtime: runtimeMode,
       paths: {
         backend_src: "src",
         entities_dir: "entities",
@@ -12400,14 +12516,16 @@ async function buildInitPlan(ctx, options) {
     fileEntry(
       cwd,
       path23.join(cwd, "src", "shared", "database", "database.module.ts"),
-      databaseModuleContent(),
+      databaseModuleContent(runtimeMode),
       { force }
     )
   );
-  for (const v of VENDORED_RUNTIME_FILES) {
-    entries.push(
-      fileEntry(cwd, path23.join(cwd, v.target), loadRuntimeFile(v.runtime), { force })
-    );
+  if (runtimeMode === "vendored") {
+    for (const v of VENDORED_RUNTIME_FILES) {
+      entries.push(
+        fileEntry(cwd, path23.join(cwd, v.target), loadRuntimeFile(v.runtime), { force })
+      );
+    }
   }
   entries.push(
     fileEntry(
@@ -12432,7 +12550,7 @@ async function buildInitPlan(ctx, options) {
         path: appModulePath,
         relPath: relOf(cwd, appModulePath),
         action: "create",
-        content: appModuleContent()
+        content: appModuleContent(runtimeMode)
       });
     } else {
       entries.push({
@@ -12450,7 +12568,7 @@ async function buildInitPlan(ctx, options) {
         path: mainPath,
         relPath: relOf(cwd, mainPath),
         action: "create",
-        content: mainTsContent()
+        content: mainTsContent(runtimeMode)
       });
     } else {
       entries.push({
@@ -13593,7 +13711,8 @@ var ProjectInitCommand = class extends Command7 {
   static usage = Command7.Usage({
     description: "Scaffold a consumer project (config, shims, barrels, app.module)",
     examples: [
-      ["Initialize with defaults", "codegen project init --yes"],
+      ["Initialize with defaults (package runtime)", "codegen project init --yes"],
+      ["Vendored runtime (legacy @shared/** model)", "codegen project init --yes --runtime vendored"],
       ["Preview without writing", "codegen project init --dry-run"],
       ["Create tsconfig if missing", "codegen project init --yes --with-tsconfig"],
       ["Overwrite existing shims", "codegen project init --force"]
@@ -13603,6 +13722,9 @@ var ProjectInitCommand = class extends Command7 {
   dryRun = Option7.Boolean("--dry-run", false);
   force = Option7.Boolean("--force", false);
   withTsconfig = Option7.Boolean("--with-tsconfig", false);
+  // Runtime mode (ADR-037). `package` (default) ⇒ depend on the npm package,
+  // vendor nothing; `vendored` ⇒ vendor src/shared/** and import via @shared/*.
+  runtime = Option7.String("--runtime", "package");
   // Vendor consumer skills into .claude/skills by default; opt out with --no-skills.
   skills = Option7.Boolean("--skills", true);
   json = Option7.Boolean("--json", false);
@@ -13614,11 +13736,18 @@ var ProjectInitCommand = class extends Command7 {
       json: this.json,
       skipDetection: false
     });
+    const runtimeMode = this.runtime === "vendored" ? "vendored" : "package";
+    if (this.runtime !== "package" && this.runtime !== "vendored" && !isJsonMode()) {
+      printWarning(
+        `--runtime '${this.runtime}' is not recognized (expected 'package' or 'vendored'); using 'package'.`
+      );
+    }
     const plan = await buildInitPlan(ctx, {
       cwd: ctx.cwd,
       force: this.force,
       withTsconfig: this.withTsconfig,
-      skipScan: false
+      skipScan: false,
+      runtimeMode
     });
     if (this.force && !isJsonMode()) {
       printWarning("--force: existing scaffold files will be overwritten.");