@pattern-stack/codegen 0.11.0 → 0.12.0

package/dist/src/cli/index.js

@@ -12,8 +12,8 @@ var __decorateClass = (decorators, target, key, kind) => {
 var __decorateParam = (index2, decorator) => (target, key) => decorator(target, key, index2);
 
 // src/cli/index.ts
-import { readFileSync as readFileSync6 } from "fs";
-import { join as join10 } from "path";
+import { readFileSync as readFileSync9 } from "fs";
+import { join as join13 } from "path";
 import { Builtins, Cli, Command as Command13 } from "clipanion";
 
 // src/cli/noun-module.ts
@@ -2465,6 +2465,36 @@ var EntityDefinitionSchema = z3.object({
   // appear in `integration.providers` — see the superRefine on
   // `EntityDefinitionSchema` below.
   detection: z3.record(z3.string(), DetectionConfigSchema).optional(),
+  // RFC-0001 §1/§8: the integration *surface* this entity belongs to
+  // (e.g. 'calendar', 'mail', 'crm'). Surfaces span provider contexts
+  // (ADR-0006) — one Google OAuth feeds calendar+mail+transcript. The union
+  // of `surface:` values across all entity YAML is the closed set that a
+  // provider's `surfaces:` must be a subset of (cross-checked in
+  // src/parser/validate-providers.ts). Optional: entities without an
+  // integration surface omit it. The surface-package *emission* convention
+  // is Track C (#329); this field is only the declarative input both tracks
+  // read.
+  surface: z3.string().optional(),
+  // Bounded-context declaration (ADR-0004) — "which bounded context this
+  // entity belongs to". This is the DURABLE decision; it is a plain
+  // bounded-context slug, NOT a folder knob. Different features consume it:
+  //
+  //   - #403 (this PR, the FIRST consumer): drives the generated code's
+  //     module output folder. clean-lite-ps nests the entity's module under
+  //     `<modules>/<context>/<entity>/` so same-context entities group
+  //     together; untagged entities stay flat (`<modules>/<entity>/`).
+  //   - ADR-0004 (deferred): a later `naming: prefix | schema` knob reads
+  //     this SAME field to drive the Postgres physical layout —
+  //     `prefix` → `pgTable('<context>__<table>')`, then the flip to
+  //     `schema` → `pgSchema('<context>').table('<table>')`. NOT wired here;
+  //     #403 makes no table/column/schema changes.
+  //
+  // Sibling to `surface:` and orthogonal to it (ADR-0006): context = model
+  // cohesion (which domain), surface = vendor composition (which integration).
+  context: z3.string().regex(
+    /^[a-z][a-z0-9_]*$/,
+    "context must be lowercase snake_case (e.g. 'integration')"
+  ).optional(),
   // v2: Domain event declarations (CODEGEN-EVOLUTION-PLAN Phase 2)
   // Generates typed event classes, handlers, and queue registration
   events: z3.array(EventDeclarationSchema).optional(),
@@ -2483,7 +2513,18 @@ var EntityDefinitionSchema = z3.object({
   ).optional(),
   // v2: Analytics / semantic layer configuration
   // Cube.js measure packs, custom cube name, and metric definitions
-  analytics: AnalyticsBlockSchema.optional()
+  analytics: AnalyticsBlockSchema.optional(),
+  // Composite (multi-column) unique indexes (#356). Single-column uniqueness
+  // is `unique: true` on the field itself; this declares constraints that
+  // span 2+ columns, e.g. UNIQUE (conversation_id, sequence). Emitted as a
+  // `uniqueIndex(...).on(...)` entry in the generated entity's pgTable
+  // extra-config callback. `name` defaults to <table>_<col1>_<col2>_uniq.
+  unique_indexes: z3.array(
+    z3.object({
+      fields: z3.array(z3.string()).min(2, "unique_indexes entries span 2+ columns \u2014 use `unique: true` on the field for single-column uniqueness"),
+      name: z3.string().optional()
+    }).strict()
+  ).optional()
 }).strict().refine(
   (data) => !data.eav_value_table || typeof data.eav_definition_table === "string",
   {
@@ -2910,6 +2951,60 @@ var JunctionDefinitionSchema = z6.object({
   }
 );
 
+// src/schema/provider-definition.schema.ts
+import { z as z7 } from "zod";
+var IMPORT_REF_RE = /^[^#\s]+#[A-Za-z_$][A-Za-z0-9_$]*$/;
+var ImportRefSchema = z7.string().regex(
+  IMPORT_REF_RE,
+  "must be an 'import-path#Export' reference (e.g. '@app/foo/bar.strategy#BarStrategy')"
+);
+function parseImportRef(ref) {
+  const hash = ref.indexOf("#");
+  return { path: ref.slice(0, hash), exportName: ref.slice(hash + 1) };
+}
+var AuthTypeSchema = z7.enum(["oauth2", "api-key", "app-password"]);
+var AuthSchema = z7.object({
+  type: AuthTypeSchema,
+  // Class implementing the auth subsystem's strategy contract (ADR-031).
+  // Pre-flight verified against a real export at codegen time.
+  strategy: ImportRefSchema,
+  // Required (and non-empty) iff type === 'oauth2'; see refine below.
+  scopes: z7.array(z7.string()).optional()
+}).strict().refine(
+  (a) => a.type !== "oauth2" || a.scopes !== void 0 && a.scopes.length > 0,
+  {
+    message: "auth.scopes is required and must be non-empty when auth.type is 'oauth2'",
+    path: ["scopes"]
+  }
+);
+var ClientSchema = z7.object({
+  // API client class. Pre-flight verified against a real export.
+  class: ImportRefSchema,
+  base_url: z7.string().url("client.base_url must be an absolute URL")
+}).strict();
+var ProviderDefinitionSchema = z7.object({
+  // Provider id — the canonical string used as detection: keys, audit rows,
+  // subscription rows. kebab/lower; unique across definitions/providers/
+  // (uniqueness is a cross-file check in validate-providers.ts).
+  slug: z7.string().regex(
+    /^[a-z][a-z0-9-]*$/,
+    "slug must be kebab-case lower (e.g. 'google', 'hubspot')"
+  ),
+  display_name: z7.string().optional(),
+  auth: AuthSchema,
+  client: ClientSchema,
+  // Surfaces this provider serves (ADR-0006: surfaces span contexts — one
+  // Google OAuth feeds calendar+mail+transcript). Each must reference a real
+  // `surface:` declared on some entity; that cross-check is in
+  // validate-providers.ts. Non-empty enforced here.
+  surfaces: z7.array(z7.string()).min(1, "surfaces must list at least one surface"),
+  // Optional auth lifecycle hints consumed by provider-module emission (D2).
+  // `refresh_behavior` is left as a free string in D1 — its domain firms up
+  // when D2 consumes it; carrying it now keeps the YAML lossless.
+  token_lifetime: z7.number().int().positive().optional(),
+  refresh_behavior: z7.string().optional()
+}).strict();
+
 // src/utils/yaml-loader.ts
 function loadEntityFromYaml(filePath) {
   if (!existsSync6(filePath)) {
@@ -2963,6 +3058,19 @@ function formatZodErrors(error) {
     return `${err.message} ${location}`;
   });
 }
+function loadEntitiesFromYaml(filePaths) {
+  const successes = [];
+  const failures = [];
+  for (const filePath of filePaths) {
+    const result = loadEntityFromYaml(filePath);
+    if (result.success) {
+      successes.push(result);
+    } else {
+      failures.push(result);
+    }
+  }
+  return { successes, failures };
+}
 function loadRelationshipFromYaml(filePath) {
   if (!existsSync6(filePath)) {
     return {
@@ -3098,6 +3206,64 @@ function loadJunctionFromYaml(filePath) {
     filePath
   };
 }
+function loadProviderFromYaml(filePath) {
+  if (!existsSync6(filePath)) {
+    return {
+      success: false,
+      error: `File not found: ${filePath}`,
+      filePath
+    };
+  }
+  let content;
+  try {
+    content = readFileSync4(filePath, "utf-8");
+  } catch (err) {
+    return {
+      success: false,
+      error: `Failed to read file: ${filePath}`,
+      details: [err instanceof Error ? err.message : String(err)],
+      filePath
+    };
+  }
+  let parsed;
+  try {
+    parsed = parseYaml(content);
+  } catch (err) {
+    return {
+      success: false,
+      error: `Invalid YAML syntax in ${filePath}`,
+      details: [err instanceof Error ? err.message : String(err)],
+      filePath
+    };
+  }
+  const result = ProviderDefinitionSchema.safeParse(parsed);
+  if (!result.success) {
+    return {
+      success: false,
+      error: `Validation failed for ${filePath}`,
+      details: formatZodErrors(result.error),
+      filePath
+    };
+  }
+  return {
+    success: true,
+    definition: result.data,
+    filePath
+  };
+}
+function loadProvidersFromYaml(filePaths) {
+  const successes = [];
+  const failures = [];
+  for (const filePath of filePaths) {
+    const result = loadProviderFromYaml(filePath);
+    if (result.success) {
+      successes.push(result);
+    } else {
+      failures.push(result);
+    }
+  }
+  return { successes, failures };
+}
 function detectYamlType(filePath) {
   if (!existsSync6(filePath)) return "unknown";
   try {
@@ -3477,6 +3643,160 @@ function resolveRelationshipReferences(relationshipDefs, entities) {
   return issues;
 }
 
+// src/parser/validate-providers.ts
+import { existsSync as existsSync7, readFileSync as readFileSync5, statSync as statSync3 } from "fs";
+import { isAbsolute, join as join8, resolve as resolve3 } from "path";
+import ts from "typescript";
+function collectEntitySurfaces(entities) {
+  const surfaces = /* @__PURE__ */ new Set();
+  for (const e of entities) {
+    if (e.surface) surfaces.add(e.surface);
+  }
+  return surfaces;
+}
+function resolveImportRef(ref, opts) {
+  const { path: path34, exportName } = parseImportRef(ref);
+  const file = resolveModuleFile(path34, opts);
+  if (!file) {
+    return { status: "module-not-found", resolvedFrom: opts.sourceRoot };
+  }
+  const content = readFileSync5(file, "utf-8");
+  const { names: names2, hasWildcard } = collectExportedNames(file, content);
+  if (names2.has(exportName) || hasWildcard) {
+    return { status: "ok", file };
+  }
+  return { status: "export-not-found", file };
+}
+function resolveModuleFile(importPath, opts) {
+  let base = null;
+  for (const [alias, target] of Object.entries(opts.aliases ?? {})) {
+    if (importPath === alias || importPath.startsWith(`${alias}/`)) {
+      const rest = importPath.slice(alias.length);
+      base = join8(target, rest);
+      break;
+    }
+  }
+  if (base === null) {
+    base = isAbsolute(importPath) ? importPath : resolve3(opts.sourceRoot, importPath);
+  }
+  const candidates = [
+    base,
+    `${base}.ts`,
+    `${base}.tsx`,
+    join8(base, "index.ts"),
+    join8(base, "index.tsx")
+  ];
+  for (const c of candidates) {
+    if (existsSync7(c) && statSync3(c).isFile()) return c;
+  }
+  return null;
+}
+function collectExportedNames(fileName, content) {
+  const sf = ts.createSourceFile(
+    fileName,
+    content,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */
+    true
+  );
+  const names2 = /* @__PURE__ */ new Set();
+  let hasWildcard = false;
+  const hasExportModifier = (node) => ts.canHaveModifiers(node) && (ts.getModifiers(node)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false);
+  sf.forEachChild((node) => {
+    if (hasExportModifier(node)) {
+      if ((ts.isClassDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isEnumDeclaration(node) || ts.isModuleDeclaration(node)) && node.name && ts.isIdentifier(node.name)) {
+        names2.add(node.name.text);
+      } else if (ts.isVariableStatement(node)) {
+        for (const decl of node.declarationList.declarations) {
+          if (ts.isIdentifier(decl.name)) names2.add(decl.name.text);
+        }
+      }
+    }
+    if (ts.isExportDeclaration(node)) {
+      if (!node.exportClause) {
+        hasWildcard = true;
+      } else if (ts.isNamedExports(node.exportClause)) {
+        for (const el of node.exportClause.elements) names2.add(el.name.text);
+      } else if (ts.isNamespaceExport(node.exportClause)) {
+        names2.add(node.exportClause.name.text);
+      }
+    }
+  });
+  return { names: names2, hasWildcard };
+}
+function validateProviders(providers, opts) {
+  const issues = [];
+  const knownSurfaces = new Set(opts.entitySurfaces);
+  const slugToFiles = /* @__PURE__ */ new Map();
+  for (const p of providers) {
+    const files = slugToFiles.get(p.definition.slug) ?? [];
+    files.push(p.filePath);
+    slugToFiles.set(p.definition.slug, files);
+  }
+  for (const [slug, files] of slugToFiles) {
+    if (files.length > 1) {
+      for (const file of files) {
+        const others = files.filter((f) => f !== file);
+        issues.push({
+          severity: "error",
+          type: "provider_duplicate_slug",
+          message: `provider slug '${slug}' is declared more than once (also in: ${others.join(", ")})`,
+          path: file
+        });
+      }
+    }
+  }
+  for (const { definition, filePath } of providers) {
+    const { slug } = definition;
+    for (const surface of definition.surfaces) {
+      if (!knownSurfaces.has(surface)) {
+        const known = [...knownSurfaces].sort().join(", ") || "(none declared)";
+        issues.push({
+          severity: "error",
+          type: "provider_unknown_surface",
+          message: `provider ${slug}: surface '${surface}' is not declared by any entity (known surfaces: ${known})`,
+          path: filePath
+        });
+      }
+    }
+    if (!opts.skipImportCheck) {
+      if (!opts.sourceRoot) {
+        throw new Error(
+          "validateProviders: sourceRoot is required for the import pre-flight check (or set skipImportCheck: true)"
+        );
+      }
+      const resolveOpts = {
+        sourceRoot: opts.sourceRoot,
+        aliases: opts.aliases
+      };
+      const refs = [
+        { field: "auth.strategy", ref: definition.auth.strategy },
+        { field: "client.class", ref: definition.client.class }
+      ];
+      for (const { field, ref } of refs) {
+        const result = resolveImportRef(ref, resolveOpts);
+        if (result.status === "module-not-found") {
+          issues.push({
+            severity: "error",
+            type: "provider_import_unresolved",
+            message: `provider ${slug}: ${field} '${ref}' not found \u2014 module could not be resolved from ${result.resolvedFrom}`,
+            path: filePath
+          });
+        } else if (result.status === "export-not-found") {
+          const { exportName } = parseImportRef(ref);
+          issues.push({
+            severity: "error",
+            type: "provider_import_unresolved",
+            message: `provider ${slug}: ${field} '${ref}' not found \u2014 export '${exportName}' is missing from ${result.file}`,
+            path: filePath
+          });
+        }
+      }
+    }
+  }
+  return issues;
+}
+
 // src/analyzer/graph-builder.ts
 function inferCardinality(type) {
   switch (type) {
@@ -4290,28 +4610,28 @@ function createSuggestion(path34) {
 
 // src/analyzer/manifest.ts
 import { createHash } from "crypto";
-import { readFileSync as readFileSync5, writeFileSync, existsSync as existsSync7, mkdirSync, readdirSync as readdirSync6, statSync as statSync3 } from "fs";
-import { join as join8 } from "path";
+import { readFileSync as readFileSync6, writeFileSync, existsSync as existsSync8, mkdirSync, readdirSync as readdirSync6, statSync as statSync4 } from "fs";
+import { join as join9 } from "path";
 var MANIFEST_FILE = "manifest.json";
 var MANIFEST_VERSION = 1;
 function getManifestDir() {
   return process.env.CODEGEN_MANIFEST_DIR || ".codegen";
 }
 function getManifestPaths(projectRoot) {
-  const dir = join8(projectRoot, getManifestDir());
-  const file = join8(dir, MANIFEST_FILE);
+  const dir = join9(projectRoot, getManifestDir());
+  const file = join9(dir, MANIFEST_FILE);
   return { dir, file };
 }
 async function computeEntityFilesHash(entitiesDir) {
-  if (!existsSync7(entitiesDir)) {
+  if (!existsSync8(entitiesDir)) {
     return createHash("sha256").update("").digest("hex");
   }
   const yamlFiles = [];
   function walkDir(dir) {
     const entries = readdirSync6(dir);
     for (const entry of entries) {
-      const fullPath = join8(dir, entry);
-      const stat = statSync3(fullPath);
+      const fullPath = join9(dir, entry);
+      const stat = statSync4(fullPath);
       if (stat.isDirectory()) {
         walkDir(fullPath);
       } else if (stat.isFile() && (entry.endsWith(".yaml") || entry.endsWith(".yml"))) {
@@ -4323,7 +4643,7 @@ async function computeEntityFilesHash(entitiesDir) {
   yamlFiles.sort();
   const hash = createHash("sha256");
   for (const file of yamlFiles) {
-    const content = readFileSync5(file, "utf-8");
+    const content = readFileSync6(file, "utf-8");
     hash.update(file);
     hash.update(content);
   }
@@ -4331,11 +4651,11 @@ async function computeEntityFilesHash(entitiesDir) {
 }
 function readManifest(projectRoot) {
   const { file } = getManifestPaths(projectRoot);
-  if (!existsSync7(file)) {
+  if (!existsSync8(file)) {
     return null;
   }
   try {
-    const content = readFileSync5(file, "utf-8");
+    const content = readFileSync6(file, "utf-8");
     const manifest = JSON.parse(content);
     if (manifest.version !== MANIFEST_VERSION) {
       return null;
@@ -4347,7 +4667,7 @@ function readManifest(projectRoot) {
 }
 function writeManifest(projectRoot, manifest) {
   const { dir, file } = getManifestPaths(projectRoot);
-  if (!existsSync7(dir)) {
+  if (!existsSync8(dir)) {
     mkdirSync(dir, { recursive: true });
   }
   const content = JSON.stringify(manifest, null, 2);
@@ -5442,8 +5762,8 @@ var BasePattern = definePattern({
 });
 
 // src/patterns/library/junction.pattern.ts
-import { z as z7 } from "zod";
-var JunctionPatternConfigSchema = z7.object({}).strict();
+import { z as z8 } from "zod";
+var JunctionPatternConfigSchema = z8.object({}).strict();
 var JunctionPattern = definePattern({
   name: "Junction",
   description: "Explicit many-to-many junction with role + temporal + sourcing metadata",
@@ -5572,9 +5892,9 @@ function validateEntities(entitiesDir) {
 
 // src/cli/shared/hygen.ts
 import { execSync } from "child_process";
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 function defaultTemplateRoot() {
-  return join9(import.meta.dirname, "..", "..", "..", "templates");
+  return join10(import.meta.dirname, "..", "..", "..", "templates");
 }
 function quoteArg(a) {
   if (a === "" || /[\s"'$`\\]/.test(a)) {
@@ -5698,7 +6018,9 @@ function collectEntities(entitiesDir) {
     const def = result.definition;
     entities.push({
       name: def.entity.name,
-      plural: def.entity.plural
+      plural: def.entity.plural,
+      // #403: top-level `context:` nests the module folder; undefined → flat.
+      context: def.context
     });
   }
   entities.sort((a, b) => a.name.localeCompare(b.name));
@@ -5754,11 +6076,12 @@ function entityFilePaths(info, architecture, backendSrc) {
   const pluralKebab = toKebabCase(plural);
   if (architecture === "clean-lite-ps") {
     const prefix = backendSrc && backendSrc !== "." ? `${backendSrc}/` : "";
+    const ctxSeg = info.context ? `${info.context}/` : "";
     return {
-      moduleFile: `${prefix}modules/${plural}/${plural}.module.ts`,
+      moduleFile: `${prefix}modules/${ctxSeg}${plural}/${plural}.module.ts`,
       moduleClass: `${toPascalCase(plural)}Module`,
       // Drizzle entity schema lives alongside the entity file in clean-lite-ps.
-      schemaFile: `${prefix}modules/${plural}/${name}.entity.ts`
+      schemaFile: `${prefix}modules/${ctxSeg}${plural}/${name}.entity.ts`
     };
   }
   return {
@@ -5879,22 +6202,22 @@ var HEADER2 = `// AUTO-GENERATED by @pattern-stack/codegen. Do not edit.
 function collectScopeableNames(entitiesDir) {
   if (!fs3.existsSync(entitiesDir)) return [];
   const files = findYamlFiles(entitiesDir);
-  const names = [];
+  const names2 = [];
   for (const file of files) {
     const result = loadEntityFromYaml(file);
     if (!result.success) continue;
     if (result.definition.entity.scopeable === true) {
-      names.push(result.definition.entity.name);
+      names2.push(result.definition.entity.name);
     }
   }
-  names.sort((a, b) => a.localeCompare(b));
-  return names;
+  names2.sort((a, b) => a.localeCompare(b));
+  return names2;
 }
-function buildScopeEntityTypeContent(names) {
-  if (names.length === 0) {
+function buildScopeEntityTypeContent(names2) {
+  if (names2.length === 0) {
     return HEADER2 + "\nexport type ScopeEntityType = never;\n\nexport const SCOPE_ENTITY_TYPES = [] as const;\n";
   }
-  const quoted = names.map((n) => `'${n}'`);
+  const quoted = names2.map((n) => `'${n}'`);
   const unionLiteral = quoted.join(" | ");
   const tupleLiteral = quoted.join(", ");
   return HEADER2 + `
@@ -6305,7 +6628,7 @@ async function regenerateSubsystemBarrel(opts) {
 // src/cli/shared/bridge-registry-generator.ts
 import fs6 from "fs";
 import path9 from "path";
-import ts from "typescript";
+import ts2 from "typescript";
 var HEADER4 = `// AUTO-GENERATED by @pattern-stack/codegen. Do not edit.
 // Run \`codegen entity new --all\` to refresh.
 `;
@@ -6381,34 +6704,34 @@ function findHandlerFiles(dir) {
 function extractTriggersFromSourceFile(sourceFile, filePath) {
   const triggers = [];
   function visit(node) {
-    if (ts.isClassDeclaration(node)) {
-      const modifiers = ts.canHaveDecorators(node) ? ts.getDecorators(node) ?? [] : [];
+    if (ts2.isClassDeclaration(node)) {
+      const modifiers = ts2.canHaveDecorators(node) ? ts2.getDecorators(node) ?? [] : [];
       for (const decorator of modifiers) {
         const call = decorator.expression;
-        if (!ts.isCallExpression(call)) continue;
-        if (!ts.isIdentifier(call.expression)) continue;
+        if (!ts2.isCallExpression(call)) continue;
+        if (!ts2.isIdentifier(call.expression)) continue;
         if (call.expression.text !== "JobHandler") continue;
         const [typeArg, metaArg] = call.arguments;
-        if (!typeArg || !ts.isStringLiteralLike(typeArg)) continue;
-        if (!metaArg || !ts.isObjectLiteralExpression(metaArg)) continue;
+        if (!typeArg || !ts2.isStringLiteralLike(typeArg)) continue;
+        if (!metaArg || !ts2.isObjectLiteralExpression(metaArg)) continue;
         const jobType = typeArg.text;
         const triggersProp = metaArg.properties.find(
-          (p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === "triggers"
+          (p) => ts2.isPropertyAssignment(p) && ts2.isIdentifier(p.name) && p.name.text === "triggers"
         );
         if (!triggersProp) continue;
-        if (!ts.isArrayLiteralExpression(triggersProp.initializer)) continue;
+        if (!ts2.isArrayLiteralExpression(triggersProp.initializer)) continue;
         triggersProp.initializer.elements.forEach((el, index2) => {
-          if (!ts.isObjectLiteralExpression(el)) return;
+          if (!ts2.isObjectLiteralExpression(el)) return;
           const eventProp = el.properties.find(
-            (p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === "event"
+            (p) => ts2.isPropertyAssignment(p) && ts2.isIdentifier(p.name) && p.name.text === "event"
           );
           const mapProp = el.properties.find(
-            (p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === "map"
+            (p) => ts2.isPropertyAssignment(p) && ts2.isIdentifier(p.name) && p.name.text === "map"
           );
           const whenProp = el.properties.find(
-            (p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === "when"
+            (p) => ts2.isPropertyAssignment(p) && ts2.isIdentifier(p.name) && p.name.text === "when"
           );
-          if (!eventProp || !ts.isStringLiteralLike(eventProp.initializer)) return;
+          if (!eventProp || !ts2.isStringLiteralLike(eventProp.initializer)) return;
           if (!mapProp) return;
           const { line } = sourceFile.getLineAndCharacterOfPosition(el.getStart(sourceFile));
           triggers.push({
@@ -6423,7 +6746,7 @@ function extractTriggersFromSourceFile(sourceFile, filePath) {
         });
       }
     }
-    ts.forEachChild(node, visit);
+    ts2.forEachChild(node, visit);
   }
   visit(sourceFile);
   return triggers;
@@ -6433,13 +6756,13 @@ function scanHandlerFiles(handlersDir) {
   const out = [];
   for (const filePath of files) {
     const text2 = fs6.readFileSync(filePath, "utf8");
-    const sourceFile = ts.createSourceFile(
+    const sourceFile = ts2.createSourceFile(
       filePath,
       text2,
-      ts.ScriptTarget.Latest,
+      ts2.ScriptTarget.Latest,
       /* setParentNodes */
       true,
-      ts.ScriptKind.TS
+      ts2.ScriptKind.TS
     );
     out.push(...extractTriggersFromSourceFile(sourceFile, filePath));
   }
@@ -6738,8 +7061,8 @@ function emitTypeImports(imports) {
   }
   const out = [];
   for (const specifier of [...grouped.keys()].sort()) {
-    const names = [...grouped.get(specifier)].sort();
-    out.push(`import type { ${names.join(", ")} } from '${specifier}';`);
+    const names2 = [...grouped.get(specifier)].sort();
+    out.push(`import type { ${names2.join(", ")} } from '${specifier}';`);
   }
   return out;
 }
@@ -6752,8 +7075,8 @@ function emitValueImports(imports) {
   }
   const out = [];
   for (const specifier of [...grouped.keys()].sort()) {
-    const names = [...grouped.get(specifier)].sort();
-    out.push(`import { ${names.join(", ")} } from '${specifier}';`);
+    const names2 = [...grouped.get(specifier)].sort();
+    out.push(`import { ${names2.join(", ")} } from '${specifier}';`);
   }
   return out;
 }
@@ -6785,13 +7108,13 @@ function buildTokensTs(pattern) {
   lines.push("");
   for (const i of emitTypeImports(typeImports)) lines.push(i);
   lines.push("");
-  for (const { names } of registries) {
-    lines.push(`export const ${names.tokenConst} = Symbol('${names.tokenConst}');`);
+  for (const { names: names2 } of registries) {
+    lines.push(`export const ${names2.tokenConst} = Symbol('${names2.tokenConst}');`);
   }
   lines.push("");
-  for (const { reg, names } of registries) {
+  for (const { reg, names: names2 } of registries) {
     lines.push(
-      `export type ${names.mapType} = Map<${reg.keyType}, ${reg.valueType}>;`
+      `export type ${names2.mapType} = Map<${reg.keyType}, ${reg.valueType}>;`
     );
   }
   lines.push("");
@@ -6805,8 +7128,8 @@ function buildProvidersTs(pattern) {
       providerImports.push({ specifier: e.providerImport, name: e.provider });
     }
   }
-  const tokenValueImports = registries.map(({ names }) => names.tokenConst);
-  const mapTypeImports = registries.map(({ names }) => names.mapType);
+  const tokenValueImports = registries.map(({ names: names2 }) => names2.tokenConst);
+  const mapTypeImports = registries.map(({ names: names2 }) => names2.mapType);
   const typeImports = [];
   for (const { reg } of registries) {
     typeImports.push({ specifier: reg.keyTypeImport, name: reg.keyType });
@@ -6831,24 +7154,24 @@ function buildProvidersTs(pattern) {
     `export function build${pascal}RegistryProviders(opts?: ${optsType}): Provider[] {`
   );
   lines.push("	return [");
-  for (const { reg, names } of registries) {
+  for (const { reg, names: names2 } of registries) {
     const factoryArgs = reg.entries.map((e, i) => `${camelArg(e.provider, i)}: ${e.provider}`).join(", ");
     lines.push("		{");
-    lines.push(`			provide: ${names.tokenConst},`);
+    lines.push(`			provide: ${names2.tokenConst},`);
     lines.push(`			useFactory: (${factoryArgs}) => {`);
-    lines.push(`				const base: ${names.mapType} = new Map<${reg.keyType}, ${reg.valueType}>([`);
+    lines.push(`				const base: ${names2.mapType} = new Map<${reg.keyType}, ${reg.valueType}>([`);
     for (const [i, e] of reg.entries.entries()) {
       lines.push(
         `					['${e.key}' as ${reg.keyType}, ${camelArg(e.provider, i)}],`
       );
     }
     lines.push("				]);");
-    lines.push(`				if (opts?.${names.overrideField}) {`);
-    lines.push(`					for (const [k, v] of Object.entries(opts.${names.overrideField})) {`);
+    lines.push(`				if (opts?.${names2.overrideField}) {`);
+    lines.push(`					for (const [k, v] of Object.entries(opts.${names2.overrideField})) {`);
     lines.push(`						if (v !== undefined) base.set(k as ${reg.keyType}, v as ${reg.valueType});`);
     lines.push("					}");
     lines.push("				}");
-    lines.push(`				return base as ${names.mapType};`);
+    lines.push(`				return base as ${names2.mapType};`);
     lines.push("			},");
     const injectList = reg.entries.map((e) => e.provider).join(", ");
     lines.push(`			inject: [${injectList}],`);
@@ -6878,8 +7201,8 @@ function buildDispatcherTs(pattern) {
       providerImports.push({ specifier: e.providerImport, name: e.provider });
     }
   }
-  const tokenValues = registries.map(({ names }) => names.tokenConst);
-  const mapTypes = registries.map(({ names }) => names.mapType);
+  const tokenValues = registries.map(({ names: names2 }) => names2.tokenConst);
+  const mapTypes = registries.map(({ names: names2 }) => names2.mapType);
   const lines = [];
   lines.push(HEADER5.trimEnd());
   lines.push("");
@@ -6897,21 +7220,21 @@ function buildDispatcherTs(pattern) {
   lines.push("@Injectable()");
   lines.push(`export class ${className} {`);
   lines.push("	constructor(");
-  for (const { names } of registries) {
-    const fieldName = names.method === "select" ? "registry" : `${camelFromMethod(names.method)}Registry`;
+  for (const { names: names2 } of registries) {
+    const fieldName = names2.method === "select" ? "registry" : `${camelFromMethod(names2.method)}Registry`;
     lines.push(
-      `		@Inject(${names.tokenConst}) protected readonly ${fieldName}: ${names.mapType},`
+      `		@Inject(${names2.tokenConst}) protected readonly ${fieldName}: ${names2.mapType},`
     );
   }
   lines.push("	) {}");
   lines.push("");
-  for (const { reg, names } of registries) {
-    const fieldName = names.method === "select" ? "registry" : `${camelFromMethod(names.method)}Registry`;
+  for (const { reg, names: names2 } of registries) {
+    const fieldName = names2.method === "select" ? "registry" : `${camelFromMethod(names2.method)}Registry`;
     for (const e of reg.entries) {
-      lines.push(`	${names.method}(key: '${e.key}'): ${e.provider};`);
+      lines.push(`	${names2.method}(key: '${e.key}'): ${e.provider};`);
     }
-    lines.push(`	${names.method}(key: ${reg.keyType}): ${reg.valueType};`);
-    lines.push(`	${names.method}(key: ${reg.keyType}): ${reg.valueType} {`);
+    lines.push(`	${names2.method}(key: ${reg.keyType}): ${reg.valueType};`);
+    lines.push(`	${names2.method}(key: ${reg.keyType}): ${reg.valueType} {`);
     lines.push(`		const entry = this.${fieldName}.get(key);`);
     lines.push(
       `		if (!entry) throw new ${errorClass}(\`Unknown ${reg.keyType}: \${String(key)}\`);`
@@ -6953,7 +7276,7 @@ function buildModuleTs(pattern) {
     typeImports.push({ specifier: reg.keyTypeImport, name: reg.keyType });
     typeImports.push({ specifier: reg.valueTypeImport, name: reg.valueType });
   }
-  const tokenValues = registries.map(({ names }) => names.tokenConst);
+  const tokenValues = registries.map(({ names: names2 }) => names2.tokenConst);
   const lines = [];
   lines.push(HEADER5.trimEnd());
   lines.push("");
@@ -6964,9 +7287,9 @@ function buildModuleTs(pattern) {
   lines.push(`import { ${tokenValues.sort().join(", ")} } from './tokens.js';`);
   lines.push("");
   lines.push(`export interface ${optsType} {`);
-  for (const { reg, names } of registries) {
+  for (const { reg, names: names2 } of registries) {
     lines.push(
-      `	${names.overrideField}?: Partial<Record<${reg.keyType}, ${reg.valueType}>>;`
+      `	${names2.overrideField}?: Partial<Record<${reg.keyType}, ${reg.valueType}>>;`
     );
   }
   lines.push("}");
@@ -7080,7 +7403,7 @@ import fs8 from "fs";
 import path11 from "path";
 
 // src/parser/load-events.ts
-import { basename as basename2, resolve as resolve3 } from "path";
+import { basename as basename2, resolve as resolve4 } from "path";
 function loadErrorToIssue2(error) {
   const issues = [];
   issues.push({
@@ -7110,7 +7433,7 @@ function stripYamlExt(file) {
 function loadEvents(eventsDir, entityNames) {
   const events = [];
   const issues = [];
-  const resolvedDir = resolve3(eventsDir);
+  const resolvedDir = resolve4(eventsDir);
   let files;
   try {
     files = findYamlFiles(resolvedDir);
@@ -7752,6 +8075,564 @@ function validateEntityEmits(entities, events) {
   return issues;
 }
 
+// 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}';
+
+/** 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 = 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");
+}
+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);
+  }
+  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);
+}
+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/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";
+var SURFACE_REGISTRY = {
+  crm: {
+    packageName: "@pattern-stack/codegen-crm",
+    portType: "CrmPort",
+    capabilitiesType: "CrmCapabilities",
+    noCapsConst: "NO_CRM_CAPABILITIES",
+    l2Ports: [
+      {
+        prop: "fields",
+        type: "IFieldDefinitionReader",
+        method: "list",
+        params: "(_integrationId, _entity)",
+        capFlag: "fieldDefinitions"
+      },
+      {
+        prop: "picklists",
+        type: "IPicklistReader",
+        method: "values",
+        params: "(_integrationId, _entity, _fieldId)",
+        capFlag: "picklists"
+      },
+      {
+        prop: "associations",
+        type: "IAssociationReader",
+        method: "list",
+        params: "(_integrationId, _fromEntity, _fromId, _toEntity)",
+        capFlag: "associations"
+      }
+    ]
+  },
+  // Interaction surfaces (#416) are incremental-read with no L2 sub-ports — the
+  // port composes L1 (auth + sources) + a capabilities descriptor whose only
+  // field is `entities`; reads go through the change-source registry. So
+  // `l2Ports: []` and the scaffold emits no L2 readers/stubs/capability flags.
+  calendar: {
+    packageName: "@pattern-stack/codegen-calendar",
+    portType: "CalendarPort",
+    capabilitiesType: "CalendarCapabilities",
+    noCapsConst: "NO_CALENDAR_CAPABILITIES",
+    l2Ports: []
+  },
+  mail: {
+    packageName: "@pattern-stack/codegen-mail",
+    portType: "MailPort",
+    capabilitiesType: "MailCapabilities",
+    noCapsConst: "NO_MAIL_CAPABILITIES",
+    l2Ports: []
+  },
+  transcript: {
+    packageName: "@pattern-stack/codegen-transcript",
+    portType: "TranscriptPort",
+    capabilitiesType: "TranscriptCapabilities",
+    noCapsConst: "NO_TRANSCRIPT_CAPABILITIES",
+    l2Ports: []
+  }
+};
+var SCAFFOLD_SENTINEL = "// <CODEGEN-SCAFFOLD-V1>";
+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\`.`;
+}
+function collectEntitiesBySurface(entities) {
+  const bySurface = /* @__PURE__ */ new Map();
+  for (const e of entities) {
+    if (!e.surface) continue;
+    const list = bySurface.get(e.surface) ?? [];
+    list.push(e.entity.name);
+    bySurface.set(e.surface, list);
+  }
+  for (const [surface, list] of bySurface) {
+    bySurface.set(surface, [...list].sort());
+  }
+  return bySurface;
+}
+function names(providerSlug, surface) {
+  const providerPascal = providerPascalCase(providerSlug);
+  const providerConst = providerConstantCase(providerSlug);
+  const surfacePascal = providerPascalCase(surface);
+  const surfaceConst = providerConstantCase(surface);
+  return {
+    providerPascal,
+    providerConst,
+    surfacePascal,
+    surfaceConst,
+    adapterClass: `${providerPascal}${surfacePascal}Adapter`,
+    adapterModuleClass: `${providerPascal}${surfacePascal}AdapterModule`,
+    providerModuleClass: `${providerPascal}ProviderModule`,
+    aggregatorClass: `${surfacePascal}AdaptersModule`,
+    strategyToken: `${providerConst}_AUTH_STRATEGY`,
+    clientToken: `${providerConst}_CLIENT`,
+    contributionsToken: `${surfaceConst}_ADAPTER_CONTRIBUTIONS`,
+    entitySourcesToken: `${surfaceConst}_ENTITY_SOURCES`
+  };
+}
+function generateAdapterScaffold(def, surface, entities) {
+  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 entitiesLiteral = entities.length ? `[${entities.map((e) => `'${e}'`).join(", ")}]` : "[]";
+  const surfaceTypeImports = [
+    spec.portType,
+    ...spec.l2Ports.map((p) => p.type),
+    spec.capabilitiesType
+  ].map((t) => `  ${t},`).join("\n");
+  const capabilityBody = [
+    `    ...${spec.noCapsConst},`,
+    ...spec.l2Ports.map((p) => `    ${p.capFlag}: true,`),
+    `    entities: ${entitiesLiteral},`
+  ].join("\n");
+  const l2Members = spec.l2Ports.map(
+    (p) => `  /** L2 \u2014 fill in the provider-specific implementation. */
+  readonly ${p.prop}: ${p.type} = {
+    ${p.method}: async ${p.params} => {
+      throw new Error('not implemented: ${n.adapterClass}.${p.prop}.${p.method}');
+    },
+  };`
+  ).join("\n\n");
+  const l2Section = l2Members ? `
+${l2Members}
+` : "";
+  return `${SCAFFOLD_SENTINEL}
+// 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.
+// Source: definitions/providers/${def.slug}.yaml (surface: ${surface}).
+import { Inject, Injectable } from '@nestjs/common';
+import type {
+${surfaceTypeImports}
+} from '${spec.packageName}';
+import { ${spec.noCapsConst} } from '${spec.packageName}';
+import type {
+  IAuthStrategy,
+  IChangeSource,
+  IEntityChangeSourceRegistry,
+} 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';
+import { ${n.entitySourcesToken} } from '../../${surface}-adapters.tokens';
+
+@Injectable()
+export class ${n.adapterClass} implements ${spec.portType} {
+  /** Declared capabilities. \`entities\` derives from \`surface: ${surface}\` entity YAML. */
+  readonly capabilities: ${spec.capabilitiesType} = {
+${capabilityBody}
+  };
+
+  constructor(
+    @Inject(${n.strategyToken}) readonly auth: IAuthStrategy,
+    @Inject(${n.clientToken}) private readonly client: ${client.exportName},
+    @Inject(${n.entitySourcesToken}) readonly sources: IEntityChangeSourceRegistry,
+  ) {}
+${l2Section}
+  /**
+   * Per-entity change sources this adapter contributes to the ${surface}
+   * registry (ADR-033 \`buildChangeSource\`), keyed by entity name. The
+   * surface aggregator folds these into the \`IEntityChangeSourceRegistry\`
+   * bound under \`${n.entitySourcesToken}\`. Author-owned \u2014 populate one entry
+   * per entity in \`capabilities.entities\`.
+   */
+  readonly changeSources: Record<string, IChangeSource<unknown>> = {};
+
+  // surface-only methods (optional on ${spec.portType}): add here
+}
+`;
+}
+function generateAdapterModule(def, surface) {
+  const n = names(def.slug, surface);
+  return `${generatedBanner(`definitions/providers/${def.slug}.yaml (surface: ${surface})`)}
+import { Module } from '@nestjs/common';
+import { ${n.providerModuleClass} } from '../../../providers/${def.slug}/${def.slug}.provider.module';
+import { ${n.adapterClass} } from './${def.slug}-${surface}.adapter';
+
+@Module({
+  imports: [${n.providerModuleClass}],
+  providers: [${n.adapterClass}],
+  exports: [${n.adapterClass}],
+})
+export class ${n.adapterModuleClass} {}
+`;
+}
+function generateAdaptersBarrel(surface, providerSlugs) {
+  const lines = [...providerSlugs].sort().map((slug) => {
+    const n = names(slug, surface);
+    return `export { ${n.adapterModuleClass} } from './${slug}/${slug}-${surface}.adapter.module';`;
+  }).join("\n");
+  return `${generatedBanner(`definitions/providers/*.yaml (surface: ${surface})`)}
+${lines}
+`;
+}
+function generateSurfaceTokens(surface) {
+  const n = names("__placeholder__", surface);
+  return `${generatedBanner(`surface: ${surface}`)}
+import type { IChangeSource } from '@pattern-stack/codegen/subsystems';
+
+/** The assembled list of every ${surface} adapter's contribution. */
+export const ${n.contributionsToken} = Symbol.for('@app/integrations/${surface}.adapter-contributions');
+
+/** Resolved registry token \u2014 resolves to a C7 IEntityChangeSourceRegistry. */
+export const ${n.entitySourcesToken} = Symbol.for('@app/integrations/${surface}.entity-sources');
+
+/** One provider-adapter's contribution to the surface registry. */
+export interface AdapterContribution {
+  /** Provider slug. */
+  provider: string;
+  /** Entities this provider serves on this surface \u2192 their change sources. */
+  sources: Record<string, IChangeSource<unknown>>;
+}
+`;
+}
+function generateSurfaceAggregator(surface, providerSlugs) {
+  const n = names("__placeholder__", surface);
+  const slugs = [...providerSlugs].sort();
+  const per = slugs.map((slug) => names(slug, surface));
+  const moduleClasses = per.map((p) => p.adapterModuleClass);
+  const moduleImport = `import {
+  ${moduleClasses.join(",\n  ")},
+} from './adapters';`;
+  const adapterImports = slugs.map((slug) => {
+    const p = names(slug, surface);
+    return `import { ${p.adapterClass} } from './adapters/${slug}/${slug}-${surface}.adapter';`;
+  }).join("\n");
+  const contributionEntries = slugs.map((slug) => {
+    const p = names(slug, surface);
+    return `        { provider: '${slug}', sources: ${lowerFirst(p.adapterClass)}.changeSources },`;
+  }).join("\n");
+  const injectParams = slugs.map((slug) => {
+    const p = names(slug, surface);
+    return `${lowerFirst(p.adapterClass)}: ${p.adapterClass}`;
+  }).join(", ");
+  const injectTokens = per.map((p) => p.adapterClass).join(", ");
+  return `${generatedBanner(`surface: ${surface}`)}
+import { Module } from '@nestjs/common';
+import {
+  MemoryEntityChangeSourceRegistry,
+  type IChangeSource,
+  type IEntityChangeSourceRegistry,
+} from '@pattern-stack/codegen/subsystems';
+${moduleImport}
+${adapterImports}
+import {
+  ${n.contributionsToken},
+  ${n.entitySourcesToken},
+  type AdapterContribution,
+} from './${surface}-adapters.tokens';
+
+/**
+ * Fold every adapter contribution into one entity-keyed registry. Each entity
+ * resolves to exactly one change source; two providers serving the same entity
+ * is an ambiguous-source boot error.
+ */
+function provide${n.surfacePascal}EntitySources(
+  contribs: AdapterContribution[],
+): IEntityChangeSourceRegistry {
+  const merged = new Map<string, IChangeSource<unknown>>();
+  const owner = new Map<string, string>();
+  for (const contrib of contribs ?? []) {
+    for (const [entity, source] of Object.entries(contrib.sources)) {
+      const prior = owner.get(entity);
+      if (prior !== undefined) {
+        throw new Error(
+          \`entity '\${entity}' is served by both '\${prior}' and '\${contrib.provider}' \u2014 ambiguous change source\`,
+        );
+      }
+      owner.set(entity, contrib.provider);
+      merged.set(entity, source);
+    }
+  }
+  return new MemoryEntityChangeSourceRegistry(merged);
+}
+
+@Module({
+  imports: [${moduleClasses.join(", ")}],
+  providers: [
+    {
+      provide: ${n.contributionsToken},
+      useFactory: (${injectParams}): AdapterContribution[] => [
+${contributionEntries}
+      ],
+      inject: [${injectTokens}],
+    },
+    {
+      provide: ${n.entitySourcesToken},
+      useFactory: (contributions: AdapterContribution[]) =>
+        provide${n.surfacePascal}EntitySources(contributions),
+      inject: [${n.contributionsToken}],
+    },
+  ],
+  exports: [${n.entitySourcesToken}, ${n.contributionsToken}],
+})
+export class ${n.aggregatorClass} {}
+`;
+}
+function lowerFirst(s) {
+  return s.length ? s[0].toLowerCase() + s.slice(1) : s;
+}
+function generateTypedView(surface, providerSlugs, entities) {
+  const surfacePascal = providerPascalCase(surface);
+  const slugs = [...providerSlugs].sort();
+  const ents = [...entities].sort();
+  const providerUnion = slugs.length ? slugs.map((s) => `'${s}'`).join(" | ") : "never";
+  const entityUnion = ents.length ? ents.map((e) => `'${e}'`).join(" | ") : "never";
+  const mapEntries = slugs.map((s) => `  ${jsKey(s)}: ${surfacePascal}Entity;`).join("\n");
+  return `${generatedBanner(`surface: ${surface}`)}
+/**
+ * Per-consumer typed view for the \`${surface}\` surface. Surface-scoped unions
+ * + a (provider, entity) validity map for compile-time-checked consumer
+ * use-cases. Replaces ADR-033.2's per-entity provider tuples (RFC-0001 \xA75/\xA78).
+ */
+
+/** Providers whose \`surfaces[]\` include \`${surface}\`. */
+export type ${surfacePascal}Provider = ${providerUnion};
+
+/** Entities declared with \`surface: ${surface}\`. */
+export type ${surfacePascal}Entity = ${entityUnion};
+
+/** Valid entities per provider on this surface. */
+export interface ${surfacePascal}ProviderEntities {
+${mapEntries || "  // no providers serve this surface yet"}
+}
+`;
+}
+function jsKey(key) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : `'${key}'`;
+}
+function emitAdapters(opts) {
+  const result = {
+    written: [],
+    scaffoldsWritten: [],
+    scaffoldsSkipped: [],
+    skippedSurfaces: []
+  };
+  const entitiesBySurface = collectEntitiesBySurface(opts.entities);
+  const bySurface = /* @__PURE__ */ new Map();
+  for (const { definition } of opts.providers) {
+    for (const surface of definition.surfaces) {
+      if (!SURFACE_REGISTRY[surface]) {
+        result.skippedSurfaces.push({
+          provider: definition.slug,
+          surface,
+          reason: `no surface package for '${surface}' yet \u2014 add codegen-${surface} (Track C) to emit its adapters`
+        });
+        continue;
+      }
+      const list = bySurface.get(surface) ?? [];
+      list.push(definition.slug);
+      bySurface.set(surface, list);
+    }
+  }
+  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");
+    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)) {
+        result.scaffoldsSkipped.push(scaffoldPath);
+      } else {
+        const content = generateAdapterScaffold(
+          def,
+          surface,
+          entitiesBySurface.get(surface) ?? []
+        );
+        if (!opts.dryRun) writeFile(scaffoldPath, content);
+        result.scaffoldsWritten.push(scaffoldPath);
+      }
+      const moduleContent = generateAdapterModule(def, surface);
+      if (!opts.dryRun) writeIfChanged2(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 files = [
+      [barrelPath, generateAdaptersBarrel(surface, slugs)],
+      [tokensPath, generateSurfaceTokens(surface)],
+      [aggregatorPath, generateSurfaceAggregator(surface, slugs)],
+      [typedViewPath, generateTypedView(surface, slugs, entitiesBySurface.get(surface) ?? [])]
+    ];
+    for (const [path34, content] of files) {
+      if (!opts.dryRun) writeIfChanged2(path34, content);
+      result.written.push(path34);
+    }
+  }
+  return result;
+}
+function writeFile(outPath, content) {
+  mkdirSync3(dirname2(outPath), { recursive: true });
+  writeFileSync3(outPath, content);
+}
+function writeIfChanged2(outPath, content) {
+  if (existsSync10(outPath) && statSync6(outPath).isFile() && readFileSync8(outPath, "utf-8") === content) {
+    return;
+  }
+  writeFile(outPath, content);
+}
+
 // src/cli/shared/events-path.ts
 import path12 from "path";
 var FALLBACK = "events";
@@ -8261,6 +9142,92 @@ var EntityNewCommand = class extends Command2 {
         }
       }
     }
+    let providerResult = null;
+    try {
+      const providersDir = ctx.config?.paths?.providers != null ? path13.resolve(
+        ctx.cwd,
+        ctx.config.paths.providers
+      ) : path13.resolve(ctx.cwd, "definitions/providers");
+      const providerOutputRoot = path13.resolve(
+        ctx.cwd,
+        backendSrcForHandlers,
+        "integrations/providers"
+      );
+      const entitySurfaces = fs9.existsSync(entitiesDir) ? collectEntitySurfaces(
+        loadEntitiesFromYaml(findYamlFiles(entitiesDir)).successes.map(
+          (s) => s.definition
+        )
+      ) : /* @__PURE__ */ new Set();
+      const tsAliases = resolveTsconfigAliases(ctx.cwd);
+      providerResult = generateProviderModules({
+        providersDir,
+        outputRoot: providerOutputRoot,
+        entitySurfaces,
+        sourceRoot: tsAliases?.sourceRoot,
+        aliases: tsAliases?.aliases,
+        skipImportCheck: tsAliases === null
+      });
+      if (!providerResult.skipped && !isJsonMode()) {
+        for (const issue of providerResult.issues) {
+          printError(`provider codegen: ${issue.message}`);
+        }
+        if (providerResult.issues.length === 0) {
+          printInfo(
+            `provider modules regenerated (${providerResult.written.length}) \u2192 ${providerOutputRoot}`
+          );
+        }
+      }
+      if (providerResult.issues.some((i) => i.severity === "error") && !this.continueOnError) {
+        return 1;
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (!isJsonMode()) {
+        printWarning(`provider codegen failed \u2014 ${msg}`);
+      }
+    }
+    try {
+      if (providerResult && !providerResult.skipped && providerResult.issues.length === 0) {
+        const providersDir = providerResult.providersDir;
+        const adapterOutputRoot = path13.resolve(
+          ctx.cwd,
+          backendSrcForHandlers,
+          "integrations"
+        );
+        const entityDefs = fs9.existsSync(entitiesDir) ? loadEntitiesFromYaml(findYamlFiles(entitiesDir)).successes.map(
+          (s) => s.definition
+        ) : [];
+        const loadedProviders = loadProvidersFromYaml(
+          findYamlFiles(providersDir)
+        ).successes.map((s) => ({
+          definition: s.definition,
+          filePath: s.filePath
+        }));
+        const adapterResult = emitAdapters({
+          providers: loadedProviders,
+          entities: entityDefs,
+          outputRoot: adapterOutputRoot
+        });
+        if (!isJsonMode()) {
+          if (adapterResult.written.length || adapterResult.scaffoldsWritten.length) {
+            printInfo(
+              `adapter codegen: ${adapterResult.scaffoldsWritten.length} scaffold(s) + ${adapterResult.written.length} @generated \u2192 ${adapterOutputRoot}`
+            );
+          }
+          for (const s of adapterResult.scaffoldsSkipped) {
+            printInfo(`skipped scaffold ${s} (author-owned)`);
+          }
+          for (const s of adapterResult.skippedSurfaces) {
+            printWarning(`adapter codegen: ${s.reason} (provider ${s.provider})`);
+          }
+        }
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (!isJsonMode()) {
+        printWarning(`adapter codegen failed \u2014 ${msg}`);
+      }
+    }
     if (isJsonMode()) {
       printJson({
         command: "entity new",
@@ -10580,7 +11547,7 @@ var REQUIRED_ALIASES = {
   "@modules/*": ["./src/modules/*"],
   "@generated/*": ["./src/generated/*"]
 };
-function stripJsonComments(raw) {
+function stripJsonComments2(raw) {
   let out = "";
   let i = 0;
   let inString = false;
@@ -10628,7 +11595,7 @@ var REQUIRED_COMPILER_OPTIONS = {
 function mergeTsconfig(raw) {
   let parsed;
   try {
-    parsed = JSON.parse(stripJsonComments(raw));
+    parsed = JSON.parse(stripJsonComments2(raw));
   } catch (err) {
     return {
       content: raw,
@@ -11098,8 +12065,8 @@ function ensureMainSwaggerBlock(sourceFile, opts) {
       /^import\s+\{\s*([^}]+)\s*\}\s+from\s+['"]([^'"]+)['"]\s*;?\s*$/
     );
     if (match) {
-      const names = match[1].split(",").map((s) => s.trim()).filter(Boolean);
-      ensureImport(sourceFile, match[2], names);
+      const names2 = match[1].split(",").map((s) => s.trim()).filter(Boolean);
+      ensureImport(sourceFile, match[2], names2);
     } else {
       sourceFile.insertStatements(0, importLine);
     }
@@ -12105,10 +13072,10 @@ var ProjectInitCommand = class extends Command7 {
 };
 function askConfirm(question) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve4) => {
+  return new Promise((resolve6) => {
     rl.question(`${question} [Y/n] `, (answer) => {
       rl.close();
-      resolve4(answer.trim().toLowerCase() !== "n");
+      resolve6(answer.trim().toLowerCase() !== "n");
     });
   });
 }
@@ -13715,7 +14682,7 @@ var junction_default = junctionNoun;
 // src/cli/commands/events.ts
 import fs20 from "fs";
 import path32 from "path";
-import ts2 from "typescript";
+import ts3 from "typescript";
 import { Command as Command11, Option as Option11 } from "clipanion";
 function scanSourceFileForConsumers(sourceFile, filePath, eventType) {
   const tier2 = [];
@@ -13729,13 +14696,13 @@ function scanSourceFileForConsumers(sourceFile, filePath, eventType) {
   }
   function checkImport(node) {
     const moduleSpec = node.moduleSpecifier;
-    if (ts2.isStringLiteral(moduleSpec) && moduleSpec.text.includes("subsystems/bridge")) {
+    if (ts3.isStringLiteral(moduleSpec) && moduleSpec.text.includes("subsystems/bridge")) {
       hasEventFlowImport = true;
     }
     const clause = node.importClause;
     if (!clause) return;
     const named = clause.namedBindings;
-    if (named && ts2.isNamedImports(named)) {
+    if (named && ts3.isNamedImports(named)) {
       for (const el of named.elements) {
         const name = el.name.text;
         if (name === "EventFlowService" || name === "EVENT_FLOW") {
@@ -13745,11 +14712,11 @@ function scanSourceFileForConsumers(sourceFile, filePath, eventType) {
     }
   }
   function checkCall(node) {
-    if (!ts2.isPropertyAccessExpression(node.expression)) return;
+    if (!ts3.isPropertyAccessExpression(node.expression)) return;
     const methodName = node.expression.name.text;
     if (methodName !== "publishAndStart" && methodName !== "subscribe") return;
     const firstArg = node.arguments[0];
-    if (!firstArg || !ts2.isStringLiteralLike(firstArg)) return;
+    if (!firstArg || !ts3.isStringLiteralLike(firstArg)) return;
     if (firstArg.text !== eventType) return;
     const receiverText = node.expression.expression.getText(sourceFile);
     if (methodName === "publishAndStart") {
@@ -13770,24 +14737,24 @@ function scanSourceFileForConsumers(sourceFile, filePath, eventType) {
   function findEnclosingClassName(node) {
     let cur = node.parent;
     while (cur) {
-      if (ts2.isClassDeclaration(cur) && cur.name) return cur.name.text;
-      if (ts2.isClassExpression(cur) && cur.name) return cur.name.text;
+      if (ts3.isClassDeclaration(cur) && cur.name) return cur.name.text;
+      if (ts3.isClassExpression(cur) && cur.name) return cur.name.text;
       cur = cur.parent;
     }
     return null;
   }
   function checkDecoratorOn(member) {
-    const decorators = ts2.canHaveDecorators(member) ? ts2.getDecorators(member) ?? [] : [];
+    const decorators = ts3.canHaveDecorators(member) ? ts3.getDecorators(member) ?? [] : [];
     for (const decorator of decorators) {
       const call = decorator.expression;
-      if (!ts2.isCallExpression(call)) continue;
-      if (!ts2.isIdentifier(call.expression)) continue;
+      if (!ts3.isCallExpression(call)) continue;
+      if (!ts3.isIdentifier(call.expression)) continue;
       if (call.expression.text !== "OnEvent") continue;
       const firstArg = call.arguments[0];
-      if (!firstArg || !ts2.isStringLiteralLike(firstArg)) continue;
+      if (!firstArg || !ts3.isStringLiteralLike(firstArg)) continue;
       if (firstArg.text !== eventType) continue;
       const className = findEnclosingClassName(member) ?? "<anonymous>";
-      const memberName = ts2.isIdentifier(member.name) ? member.name.text : member.name.getText(sourceFile);
+      const memberName = ts3.isIdentifier(member.name) ? member.name.text : member.name.getText(sourceFile);
       tier1.push({
         kind: "on-event",
         siteLabel: `${className}.${memberName} @OnEvent('${eventType}')`,
@@ -13797,12 +14764,12 @@ function scanSourceFileForConsumers(sourceFile, filePath, eventType) {
     }
   }
   function visit(node) {
-    if (ts2.isImportDeclaration(node)) checkImport(node);
-    if (ts2.isCallExpression(node)) checkCall(node);
-    if (ts2.isMethodDeclaration(node) || ts2.isPropertyDeclaration(node)) {
+    if (ts3.isImportDeclaration(node)) checkImport(node);
+    if (ts3.isCallExpression(node)) checkCall(node);
+    if (ts3.isMethodDeclaration(node) || ts3.isPropertyDeclaration(node)) {
       checkDecoratorOn(node);
     }
-    ts2.forEachChild(node, visit);
+    ts3.forEachChild(node, visit);
   }
   visit(sourceFile);
   return { tier2, tier1, hasEventFlowImport };
@@ -13814,12 +14781,12 @@ function scanDirectoryForConsumers(rootDir, eventType) {
   let hasEventFlowImport = false;
   for (const filePath of files) {
     const text2 = fs20.readFileSync(filePath, "utf8");
-    const sourceFile = ts2.createSourceFile(
+    const sourceFile = ts3.createSourceFile(
       filePath,
       text2,
-      ts2.ScriptTarget.Latest,
+      ts3.ScriptTarget.Latest,
       true,
-      ts2.ScriptKind.TS
+      ts3.ScriptKind.TS
     );
     const result = scanSourceFileForConsumers(sourceFile, filePath, eventType);
     tier2.push(...result.tier2);
@@ -14233,12 +15200,12 @@ async function summary9(ctx) {
     await reloadRegistry(ctx);
   } catch {
   }
-  const names = getOrchestrationPatternNames();
+  const names2 = getOrchestrationPatternNames();
   return {
     title: "orchestration",
     body: [
-      `patterns: ${names.length}`,
-      ...names.length > 0 ? [`  ${names.join(", ")}`] : []
+      `patterns: ${names2.length}`,
+      ...names2.length > 0 ? [`  ${names2.join(", ")}`] : []
     ]
   };
 }
@@ -14287,8 +15254,8 @@ var update_default = UpdateShortcut;
 // src/cli/index.ts
 function readVersion() {
   try {
-    const pkgPath = join10(import.meta.dirname, "..", "..", "package.json");
-    const pkg = JSON.parse(readFileSync6(pkgPath, "utf-8"));
+    const pkgPath = join13(import.meta.dirname, "..", "..", "package.json");
+    const pkg = JSON.parse(readFileSync9(pkgPath, "utf-8"));
     return typeof pkg.version === "string" ? pkg.version : "0.0.0";
   } catch {
     return "0.0.0";