@pattern-stack/codegen 0.12.2 → 0.13.0

package/dist/src/cli/index.js

@@ -1120,12 +1120,33 @@ var EventIdCursorSchema = z2.object({
   kind: z2.literal("eventId"),
   field: z2.string().min(1)
 });
+var HistoryIdCursorSchema = z2.object({
+  kind: z2.literal("historyId"),
+  field: z2.string().min(1)
+});
+var SyncTokenCursorSchema = z2.object({
+  kind: z2.literal("syncToken"),
+  field: z2.string().min(1)
+});
 var CursorStrategySchema = z2.discriminatedUnion("kind", [
   SystemModstampCursorSchema,
   ReplayIdCursorSchema,
   TimestampCursorSchema,
-  EventIdCursorSchema
+  EventIdCursorSchema,
+  HistoryIdCursorSchema,
+  SyncTokenCursorSchema
 ]);
+var CURSOR_DIVISIBILITY = {
+  systemModstamp: true,
+  timestamp: true,
+  replayId: true,
+  eventId: false,
+  historyId: false,
+  syncToken: false
+};
+function isDivisibleCursor(kind) {
+  return CURSOR_DIVISIBILITY[kind];
+}
 var PollDetectionSchema = z2.object({
   cursor: CursorStrategySchema,
   provenance: z2.enum(["poll", "cdc"]).optional()
@@ -8241,6 +8262,310 @@ import {
   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";
+function sinkNames(entityClass) {
+  return {
+    sinkClass: `${entityClass}Sink`,
+    canonicalType: `${entityClass}Canonical`,
+    repoClass: `${entityClass}Repository`,
+    projectionType: `${entityClass}IntegrationProjection`,
+    writeType: `${entityClass}IntegrationWrite`
+  };
+}
+function generateDefaultSink(input) {
+  if (input.pattern !== "Integrated") {
+    throw new Error(
+      `cannot emit default integration sink for entity '${input.entityName}': it is 'pattern: ${input.pattern}', but the default sink is emittable only for 'pattern: Integrated' entities (the only family with the integrationUpsertOne / findByExternalIdProjected projection path). Add 'pattern: Integrated' to the entity or provide a hand-authored sink.`
+    );
+  }
+  const n = sinkNames(input.entityClass);
+  const hasUserIdField = input.copyThroughFields.some(
+    (f) => f.camelName === USER_ID_FIELD
+  );
+  const copyThroughLines = input.copyThroughFields.filter((f) => f.camelName !== USER_ID_FIELD).map((f) => `      ${f.camelName}: record.${f.camelName},`);
+  const fkTodoLines = input.fkExternalKeys.map(
+    (fk) => `      // ${fk.writeKey}: /* TODO(author): external id of the related ${relationLabel(fk.writeKey)} */ null,`
+  );
+  const writeBodyLines = [
+    `      externalId: record.externalId,`
+  ];
+  if (copyThroughLines.length > 0) {
+    writeBodyLines.push(
+      `      // copy-through fields (one line per \`fields:\` entry):`,
+      ...copyThroughLines
+    );
+  }
+  if (fkTodoLines.length > 0) {
+    writeBodyLines.push(
+      `      // FK external join-keys \u2014 projection has no external key; supply from your canonical record:`,
+      ...fkTodoLines
+    );
+  }
+  if (hasUserIdField) {
+    writeBodyLines.push(`      userId,`);
+  }
+  const writeBody = writeBodyLines.join("\n");
+  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.
+//
+// Default IIntegrationSink over the generated ${n.repoClass}. The PLUMBING
+// (constructor, provider-match assert, repo delegation, userId scoping, return
+// shapes) is generated. The canonical<->local FIELD MAPPING is the author seam:
+// the canonical type is whatever your adapter's changeSource yields \u2014 the same
+// seam as the IChangeSource.listChanges fetch body. For FK-free entities the
+// generated ${n.projectionType} IS the canonical shape (passthrough);
+// 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 {
+  ${n.repoClass},
+  type ${n.projectionType},
+  type ${n.writeType},
+} from '${input.repoImportSpecifier}';
+
+/** Canonical type the orchestrator diffs. Defaults to the generated projection;
+ *  widen to your adapter's canonical shape if it carries fields the projection
+ *  does not (e.g. external FK join-keys). */
+export type ${n.canonicalType} = ${n.projectionType};
+
+@Injectable()
+export class ${n.sinkClass} implements IIntegrationSink<${n.canonicalType}> {
+  constructor(
+    private readonly repo: ${n.repoClass},
+    private readonly provider: string,
+  ) {}
+
+  async findByExternalId(userId: string, externalId: string): Promise<${n.canonicalType} | null> {
+    const row = await this.repo.findByExternalIdProjected(externalId, this.provider);
+    // The repo lookup is (provider, externalId)-scoped. If your external_id is not
+    // globally unique, enforce ownership here (e.g. row.userId === userId).
+    return row;
+  }
+
+  async upsertByExternalId(
+    userId: string,
+    record: ${n.canonicalType},
+    provider: string,
+  ): Promise<{ id: string; saved: ${n.canonicalType} }> {
+    if (provider !== this.provider) {
+      throw new Error(\`${n.sinkClass}: bound provider '\${this.provider}' != run provider '\${provider}'\`);
+    }
+    const write: ${n.writeType} = {
+${writeBody}
+    };
+    const proj = await this.repo.integrationUpsertOne(write, this.provider);
+    return { id: proj.id, saved: record };
+  }
+
+  async softDeleteByExternalId(_userId: string, externalId: string): Promise<{ id: string } | null> {
+    return this.repo.softDeleteByExternalId(externalId, this.provider);
+  }
+}
+`;
+}
+function relationLabel(writeKey) {
+  const stripped = writeKey.replace(/ExternalId$/, "");
+  return stripped || "related entity";
+}
+
+// src/cli/shared/assembly-emission-generator.ts
+import { relative, resolve as resolve6, 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\`.`;
+}
+function entityPascalCase(name) {
+  return name.split("_").filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function entityConstantCase(name) {
+  return name.replace(/-/g, "_").toUpperCase();
+}
+function integrationUseCaseToken(entityName, providerSlug) {
+  return `${entityConstantCase(entityName)}_INTEGRATION_USE_CASE__${providerConstantCase(providerSlug)}`;
+}
+function assemblyModuleClass(entityName, providerSlug) {
+  return `${entityPascalCase(entityName)}IntegrationModule__${providerPascalCase(providerSlug)}`;
+}
+function tokenSymbolKey(surface, entityName, providerSlug) {
+  return `@app/integrations/${surface}.${entityName}-integration-use-case.${providerSlug}`;
+}
+function generateAssemblyModule(input) {
+  const providerPascal = providerPascalCase(input.provider);
+  const surfacePascal = providerPascalCase(input.surface);
+  const adapterClass = `${providerPascal}${surfacePascal}Adapter`;
+  const adapterModuleClass = `${adapterClass}Module`;
+  const adapterImport = `../../adapters/${input.provider}/${input.provider}-${input.surface}.adapter`;
+  const adapterModuleImport = `${adapterImport}.module`;
+  const sinkClass = `${input.entityClass}Sink`;
+  const sinkImport = `../../sinks/${input.entityName}.sink`;
+  const token = integrationUseCaseToken(input.entityName, input.provider);
+  const moduleClass = assemblyModuleClass(input.entityName, input.provider);
+  const tokensImport = `../../${input.surface}-integration.tokens`;
+  return `${generatedBanner(input.sourceDesc)}
+import { Module } from '@nestjs/common';
+import {
+  ExecuteIntegrationUseCase,
+  INTEGRATION_CHANGE_SOURCE,
+  INTEGRATION_SINK,
+} from '@pattern-stack/codegen/subsystems';
+import { ${adapterClass} } from '${adapterImport}';
+import { ${adapterModuleClass} } from '${adapterModuleImport}';
+import { ${sinkClass} } from '${sinkImport}';
+import { ${input.repoClass} } from '${input.repoImportSpecifier}';
+import { ${input.moduleClass} } from '${input.moduleImportSpecifier}';
+import { ${token} } from '${tokensImport}';
+
+/**
+ * ${moduleClass} \u2014 the ${input.surface}/${input.entityName} \u2190 ${input.provider}
+ * 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
+ * ${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,
+ * multi-tenant flag) comes from the global IntegrationModule.forRoot(...) in
+ * AppModule, never re-bound here.
+ */
+@Module({
+  imports: [${input.moduleClass}, ${adapterModuleClass}],
+  providers: [
+    {
+      provide: INTEGRATION_CHANGE_SOURCE,
+      useFactory: (adapter: ${adapterClass}) => adapter.changeSources['${input.entityName}'],
+      inject: [${adapterClass}],
+    },
+    {
+      provide: INTEGRATION_SINK,
+      useFactory: (repo: ${input.repoClass}) => new ${sinkClass}(repo, '${input.provider}'),
+      inject: [${input.repoClass}],
+    },
+    ExecuteIntegrationUseCase,
+    { provide: ${token}, useExisting: ExecuteIntegrationUseCase },
+  ],
+  exports: [${token}],
+})
+export class ${moduleClass} {}
+`;
+}
+function generateIntegrationTokens(surface, entries) {
+  const sorted = [...entries].sort(
+    (a, b) => a.entityName === b.entityName ? a.provider < b.provider ? -1 : 1 : a.entityName < b.entityName ? -1 : 1
+  );
+  const tokenLines = sorted.map((e) => {
+    const token = integrationUseCaseToken(e.entityName, e.provider);
+    const key = tokenSymbolKey(surface, e.entityName, e.provider);
+    return `/** Unique handle for the ${e.entityName} \u2190 ${e.provider} integration use-case
+ *  (${assemblyModuleClass(e.entityName, e.provider)}). A trigger grabs this to run it. */
+export const ${token} = Symbol.for('${key}');`;
+  }).join("\n\n");
+  return `${generatedBanner(`surface: ${surface}`)}
+/**
+ * Use-case handles for the \`${surface}\` surface \u2014 one per (entity, provider)
+ * assembly. Each is a Symbol \`provide:\` token a per-entity
+ * \`ExecuteIntegrationUseCase\` is aliased under (the bare class token is
+ * ambiguous at app root) and exported for the consuming trigger to grab.
+ */
+
+${tokenLines || "// no (entity, provider) integration assemblies on this surface yet"}
+`;
+}
+function generateIntegrationAggregator(surface, entries) {
+  const surfacePascal = providerPascalCase(surface);
+  const aggregatorClass = `${surfacePascal}IntegrationModule`;
+  const sorted = [...entries].sort(
+    (a, b) => a.provider === b.provider ? a.entityName < b.entityName ? -1 : 1 : a.provider < b.provider ? -1 : 1
+  );
+  const moduleClasses = sorted.map(
+    (e) => assemblyModuleClass(e.entityName, e.provider)
+  );
+  const importLines = sorted.map((e) => {
+    const cls = assemblyModuleClass(e.entityName, e.provider);
+    const path34 = `./modules/${e.provider}/${e.entityName}-integration.module`;
+    return `import { ${cls} } from '${path34}';`;
+  }).join("\n");
+  const membersInline = moduleClasses.join(", ");
+  return `${generatedBanner(`surface: ${surface}`)}
+import { Module } from '@nestjs/common';
+${importLines || "// no (entity, provider) integration assemblies on this surface yet"}
+
+/**
+ * ${aggregatorClass} \u2014 the \`${surface}\` integration aggregator. AppModule
+ * imports THIS (not ${surfacePascal}AdaptersModule) to wire every per-entity
+ * integration on the surface. Re-exports each assembly module so their
+ * <ENTITY>_INTEGRATION_USE_CASE__<PROVIDER> tokens are available to the app (the
+ * trigger/consumer grabs them). Per RFC-0002 \xA77 q3, the run path goes through
+ * these assembly modules, keeping the collision-prone ${surfacePascal}AdaptersModule
+ * fold off the graph.
+ */
+@Module({
+  imports: [${membersInline}],
+  exports: [${membersInline}],
+})
+export class ${aggregatorClass} {}
+`;
+}
+function pluralPascalCase(plural) {
+  return plural.split("_").filter(Boolean).map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+}
+function toImportSpecifier(targetFileAbs, fromDirAbs, aliases) {
+  const noExt = targetFileAbs.replace(/\.ts$/, "");
+  let best = null;
+  for (const [key, dirRaw] of Object.entries(aliases)) {
+    const dir = dirRaw.endsWith(sep) ? dirRaw.slice(0, -1) : dirRaw;
+    const prefix = dir + sep;
+    if (noExt === dir || noExt.startsWith(prefix)) {
+      const rest = noExt === dir ? "" : noExt.slice(prefix.length);
+      if (!best || dir.length > aliases[best.key].length) {
+        best = { key, rest };
+      }
+    }
+  }
+  if (best) {
+    const restPosix = best.rest.split(sep).join("/");
+    return restPosix ? `${best.key}/${restPosix}` : best.key;
+  }
+  let rel2 = relative(fromDirAbs, noExt).split(sep).join("/");
+  if (!rel2.startsWith(".")) rel2 = `./${rel2}`;
+  return rel2;
+}
+function resolveEntityModuleImports(input) {
+  const entityClass = entityPascalCase(input.entityName);
+  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(
+    input.backendSrcAbs,
+    ...moduleGroupSegs,
+    `${input.entityName}.repository.ts`
+  );
+  const moduleFileAbs = resolve6(
+    input.backendSrcAbs,
+    ...moduleGroupSegs,
+    `${input.entityPlural}.module.ts`
+  );
+  const assemblyDirAbs = resolve6(
+    input.backendSrcAbs,
+    "integrations",
+    input.surface,
+    "modules",
+    input.provider
+  );
+  return {
+    entityClass,
+    repoClass,
+    moduleClass,
+    repoImportSpecifier: toImportSpecifier(repoFileAbs, assemblyDirAbs, input.aliases),
+    moduleImportSpecifier: toImportSpecifier(moduleFileAbs, assemblyDirAbs, input.aliases)
+  };
+}
+
+// src/cli/shared/adapter-emission-generator.ts
 var SURFACE_REGISTRY = {
   crm: {
     packageName: "@pattern-stack/codegen-crm",
@@ -8280,25 +8605,28 @@ var SURFACE_REGISTRY = {
     portType: "CalendarPort",
     capabilitiesType: "CalendarCapabilities",
     noCapsConst: "NO_CALENDAR_CAPABILITIES",
-    l2Ports: []
+    l2Ports: [],
+    readPrimitive: true
   },
   mail: {
     packageName: "@pattern-stack/codegen-mail",
     portType: "MailPort",
     capabilitiesType: "MailCapabilities",
     noCapsConst: "NO_MAIL_CAPABILITIES",
-    l2Ports: []
+    l2Ports: [],
+    readPrimitive: true
   },
   transcript: {
     packageName: "@pattern-stack/codegen-transcript",
     portType: "TranscriptPort",
     capabilitiesType: "TranscriptCapabilities",
     noCapsConst: "NO_TRANSCRIPT_CAPABILITIES",
-    l2Ports: []
+    l2Ports: [],
+    readPrimitive: true
   }
 };
-var SCAFFOLD_SENTINEL = "// <CODEGEN-SCAFFOLD-V1>";
-function generatedBanner(sourceDesc) {
+var SCAFFOLD_SENTINEL2 = "// <CODEGEN-SCAFFOLD-V1>";
+function generatedBanner2(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\`.`;
 }
@@ -8336,17 +8664,139 @@ function names(providerSlug, surface) {
     entitySourcesToken: `${surfaceConst}_ENTITY_SOURCES`
   };
 }
-function generateAdapterScaffold(def, surface, entities) {
+function entityPascalCase2(name) {
+  return name.split(/[-_]/).filter(Boolean).map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+}
+function entityConstCase(name) {
+  return name.replace(/-/g, "_").toUpperCase();
+}
+function serializeFilterArray(filters) {
+  if (filters.length === 0) return "[]";
+  const items = filters.map(
+    (f) => `  { field: ${JSON.stringify(f.field)}, op: ${JSON.stringify(f.op)}, value: ${JSON.stringify(f.value)} },`
+  );
+  return `[
+${items.join("\n")}
+]`;
+}
+function buildReadPrimitiveEmission(providerSlug, providerPascal, surface, entities, entityDetection, clientExportName) {
+  const canonicalTypes = [];
+  const blocks = [];
+  const entries = [];
+  for (const entity of entities) {
+    const pascal = entityPascalCase2(entity);
+    const canonical = `Canonical${pascal}`;
+    const className = `${providerPascal}${pascal}IncrementalRead`;
+    const constName = `${entityConstCase(entity)}_DETECTION_FILTERS`;
+    canonicalTypes.push(canonical);
+    const det = entityDetection?.get(entity);
+    const filters = det?.filters ?? [];
+    const cursorKind = det && det.mode === "poll" ? det.poll.cursor.kind : void 0;
+    const atomic = cursorKind !== void 0 && !isDivisibleCursor(cursorKind);
+    const cursorOverride = atomic ? `
+  // \`${cursorKind}\` is an ATOMIC cursor (RFC-0003 \xA73): its next value only exists
+  // at end-of-walk, so per-ref cursors are withheld and only the final record
+  // carries the token \u2014 a mid-walk crash never persists an unresumable value.
+  protected override readonly cursorDivisible = false;` : "";
+    blocks.push(`/**
+ * \`detection.filters\` for \`${entity}\`, emitted from YAML as a static
+ * \`ResolvedFilter[]\` (RFC-0003 \xA74 fork #2); \`filterFor()\` returns it.
+ */
+const ${constName}: ResolvedFilter[] = ${serializeFilterArray(filters)};
+
+// Emit-once read primitive (author-owned). Fill the three vendor methods below.
+export class ${className} extends IncrementalReadBase<${canonical}, ResolvedFilter[]> {
+  readonly label = '${providerSlug}-${surface}-${entity}';
+  // Flip to \`true\` if your \`enumerate\` pushes the request filter to the vendor
+  // (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},
+  ) {
+    super();
+  }
+
+  /** TODO: walk the vendor list endpoint \u2192 pages of \`Ref\` (id + cursor + meta). */
+  protected async *enumerate(
+    _mode: ReadMode,
+    _filter?: ResolvedFilter[],
+    _pageSize?: number,
+  ): 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>> {
+    throw new Error('not implemented: ${className}.hydrate');
+  }
+
+  /** TODO: vendor payload \u2192 \`${canonical}\` (return \`null\` to drop). */
+  protected toCanonical(_raw: unknown): ${canonical} | null {
+    throw new Error('not implemented: ${className}.toCanonical');
+  }
+
+  protected override filterFor(
+    _subscription: IntegrationSubscriptionView,
+  ): ResolvedFilter[] {
+    return ${constName};
+  }
+}`);
+    entries.push(`      ${entity}: new ${className}(this.auth, this.client),`);
+  }
+  return { canonicalTypes, preamble: blocks.join("\n\n"), changeSourceEntries: entries };
+}
+function generateAdapterScaffold(def, surface, entities, entityDetection) {
   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 readPrimitive = !!spec.readPrimitive && entities.length > 0;
+  const rp = readPrimitive ? buildReadPrimitiveEmission(
+    def.slug,
+    n.providerPascal,
+    surface,
+    entities,
+    entityDetection,
+    client.exportName
+  ) : null;
   const surfaceTypeImports = [
     spec.portType,
     ...spec.l2Ports.map((p) => p.type),
-    spec.capabilitiesType
+    spec.capabilitiesType,
+    ...rp ? rp.canonicalTypes : []
+  ].map((t) => `  ${t},`).join("\n");
+  const subsystemValueImport = rp ? `import { IncrementalReadBase } from '@pattern-stack/codegen/subsystems';
+` : "";
+  const subsystemTypeImports = [
+    "IAuthStrategy",
+    "IChangeSource",
+    ...rp ? ["IntegrationSubscriptionView", "ReadMode", "Ref", "ResolvedFilter"] : []
   ].map((t) => `  ${t},`).join("\n");
+  const changeSourcesAssign = rp ? `
+    this.changeSources = {
+${rp.changeSourceEntries.join("\n")}
+    };
+  ` : "";
+  const changeSourcesDecl = rp ? `  /**
+   * Per-entity change sources contributed to the ${surface} registry, keyed by
+   * entity name. The surface aggregator folds these into the
+   * \`IEntityChangeSourceRegistry\` bound under \`${n.entitySourcesToken}\`.
+   * Emit-once: edit the \`IncrementalReadBase\` subclasses above, not this map.
+   */
+  readonly changeSources: Record<string, IChangeSource<unknown>>;` : `  /**
+   * 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>> = {};`;
+  const preambleSection = rp ? `
+${rp.preamble}
+` : "";
   const capabilityBody = [
     `    ...${spec.noCapsConst},`,
     ...spec.l2Ports.map((p) => `    ${p.capFlag}: true,`),
@@ -8363,7 +8813,7 @@ function generateAdapterScaffold(def, surface, entities) {
   const l2Section = l2Members ? `
 ${l2Members}
 ` : "";
-  return `${SCAFFOLD_SENTINEL}
+  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.
 // Source: definitions/providers/${def.slug}.yaml (surface: ${surface}).
@@ -8372,15 +8822,12 @@ import type {
 ${surfaceTypeImports}
 } from '${spec.packageName}';
 import { ${spec.noCapsConst} } from '${spec.packageName}';
-import type {
-  IAuthStrategy,
-  IChangeSource,
-  IEntityChangeSourceRegistry,
+${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';
-import { ${n.entitySourcesToken} } from '../../${surface}-adapters.tokens';
-
+${preambleSection}
 @Injectable()
 export class ${n.adapterClass} implements ${spec.portType} {
   /** Declared capabilities. \`entities\` derives from \`surface: ${surface}\` entity YAML. */
@@ -8391,17 +8838,9 @@ ${capabilityBody}
   constructor(
     @Inject(${n.strategyToken}) readonly auth: IAuthStrategy,
     @Inject(${n.clientToken}) private readonly client: ${client.exportName},
-    @Inject(${n.entitySourcesToken}) readonly sources: IEntityChangeSourceRegistry,
-  ) {}
+  ) {${changeSourcesAssign}}
 ${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>> = {};
+${changeSourcesDecl}
 
   // surface-only methods (optional on ${spec.portType}): add here
 }
@@ -8409,7 +8848,7 @@ ${l2Section}
 }
 function generateAdapterModule(def, surface) {
   const n = names(def.slug, surface);
-  return `${generatedBanner(`definitions/providers/${def.slug}.yaml (surface: ${surface})`)}
+  return `${generatedBanner2(`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';
@@ -8427,13 +8866,13 @@ function generateAdaptersBarrel(surface, providerSlugs) {
     const n = names(slug, surface);
     return `export { ${n.adapterModuleClass} } from './${slug}/${slug}-${surface}.adapter.module';`;
   }).join("\n");
-  return `${generatedBanner(`definitions/providers/*.yaml (surface: ${surface})`)}
+  return `${generatedBanner2(`definitions/providers/*.yaml (surface: ${surface})`)}
 ${lines}
 `;
 }
 function generateSurfaceTokens(surface) {
   const n = names("__placeholder__", surface);
-  return `${generatedBanner(`surface: ${surface}`)}
+  return `${generatedBanner2(`surface: ${surface}`)}
 import type { IChangeSource } from '@pattern-stack/codegen/subsystems';
 
 /** The assembled list of every ${surface} adapter's contribution. */
@@ -8472,7 +8911,7 @@ function generateSurfaceAggregator(surface, providerSlugs) {
     return `${lowerFirst(p.adapterClass)}: ${p.adapterClass}`;
   }).join(", ");
   const injectTokens = per.map((p) => p.adapterClass).join(", ");
-  return `${generatedBanner(`surface: ${surface}`)}
+  return `${generatedBanner2(`surface: ${surface}`)}
 import { Module } from '@nestjs/common';
 import {
   MemoryEntityChangeSourceRegistry,
@@ -8544,7 +8983,7 @@ function generateTypedView(surface, providerSlugs, entities) {
   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}`)}
+  return `${generatedBanner2(`surface: ${surface}`)}
 /**
  * Per-consumer typed view for the \`${surface}\` surface. Surface-scoped unions
  * + a (provider, entity) validity map for compile-time-checked consumer
@@ -8571,9 +9010,14 @@ function emitAdapters(opts) {
     written: [],
     scaffoldsWritten: [],
     scaffoldsSkipped: [],
-    skippedSurfaces: []
+    skippedSurfaces: [],
+    assembliesWritten: [],
+    tokensWritten: [],
+    integrationAggregatorsWritten: [],
+    skippedAssemblies: []
   };
   const entitiesBySurface = collectEntitiesBySurface(opts.entities);
+  const entityByName = new Map(opts.entities.map((e) => [e.entity.name, e]));
   const bySurface = /* @__PURE__ */ new Map();
   for (const { definition } of opts.providers) {
     for (const surface of definition.surfaces) {
@@ -8602,10 +9046,17 @@ function emitAdapters(opts) {
       if (existsSync10(scaffoldPath)) {
         result.scaffoldsSkipped.push(scaffoldPath);
       } else {
+        const surfaceEntityNames = entitiesBySurface.get(surface) ?? [];
+        const entityDetection = /* @__PURE__ */ new Map();
+        for (const name of surfaceEntityNames) {
+          const det = entityByName.get(name)?.entity.detection?.[slug];
+          if (det) entityDetection.set(name, det);
+        }
         const content = generateAdapterScaffold(
           def,
           surface,
-          entitiesBySurface.get(surface) ?? []
+          surfaceEntityNames,
+          entityDetection
         );
         if (!opts.dryRun) writeFile(scaffoldPath, content);
         result.scaffoldsWritten.push(scaffoldPath);
@@ -8628,9 +9079,141 @@ function emitAdapters(opts) {
       if (!opts.dryRun) writeIfChanged2(path34, content);
       result.written.push(path34);
     }
+    if (opts.backendSrcAbs) {
+      const aliases = opts.aliases ?? {};
+      const surfaceEntities = entitiesBySurface.get(surface) ?? [];
+      const tokenEntries = [];
+      const assemblyEntries = [];
+      const sinksDir = join12(surfaceDir, "sinks");
+      const modulesDir = join12(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);
+        if (pattern !== "Integrated") {
+          result.skippedAssemblies.push({
+            surface,
+            entity: entityName,
+            reason: `entity '${entityName}' declares surface '${surface}' but is not 'pattern: Integrated'${pattern ? ` (got 'pattern: ${pattern}')` : " (no pattern declared)"} \u2014 the integration assembly + default sink need the Integrated projection/upsert path. Add 'pattern: Integrated' (or provide a hand-authored sink + assembly).`
+          });
+          continue;
+        }
+        const plural = def?.entity.plural ?? `${entityName}s`;
+        const context = def?.entity.context ?? null;
+        const loc = resolveEntityModuleImports({
+          entityName,
+          entityPlural: plural,
+          context,
+          surface,
+          // The sink+repo import is provider-agnostic; pick any provider's
+          // module dir for the relative-path base (all share the same parent).
+          provider: slugs[0],
+          backendSrcAbs: opts.backendSrcAbs,
+          aliases
+        });
+        const sinkPath = join12(sinksDir, `${entityName}.sink.ts`);
+        if (existsSync10(sinkPath)) {
+          result.scaffoldsSkipped.push(sinkPath);
+        } else {
+          const sinkInput = buildSinkInput(def, surface, slugs[0], loc.repoImportSpecifier);
+          const sinkContent = generateDefaultSink(sinkInput);
+          if (!opts.dryRun) writeFile(sinkPath, sinkContent);
+          result.scaffoldsWritten.push(sinkPath);
+        }
+        for (const slug of slugs) {
+          const assemblyPath = join12(
+            modulesDir,
+            slug,
+            `${entityName}-integration.module.ts`
+          );
+          const assemblyContent = generateAssemblyModule({
+            surface,
+            provider: slug,
+            entityName,
+            entityClass: loc.entityClass,
+            moduleImportSpecifier: loc.moduleImportSpecifier,
+            moduleClass: loc.moduleClass,
+            repoImportSpecifier: loc.repoImportSpecifier,
+            repoClass: loc.repoClass,
+            sourceDesc: `definitions/providers/${slug}.yaml`
+          });
+          if (!opts.dryRun) writeIfChanged2(assemblyPath, assemblyContent);
+          result.assembliesWritten.push(assemblyPath);
+          tokenEntries.push({ entityName, entityClass: loc.entityClass, provider: slug });
+          assemblyEntries.push({ entityName, provider: slug });
+        }
+      }
+      const integrationTokensPath = join12(
+        surfaceDir,
+        `${surface}-integration.tokens.ts`
+      );
+      const tokensContent = generateIntegrationTokens(surface, tokenEntries);
+      if (!opts.dryRun) writeIfChanged2(integrationTokensPath, tokensContent);
+      result.tokensWritten.push(integrationTokensPath);
+      if (assemblyEntries.length > 0) {
+        const integrationAggregatorPath = join12(
+          surfaceDir,
+          `${surface}-integration.module.ts`
+        );
+        const aggregatorContent = generateIntegrationAggregator(
+          surface,
+          assemblyEntries
+        );
+        if (!opts.dryRun) writeIfChanged2(integrationAggregatorPath, aggregatorContent);
+        result.integrationAggregatorsWritten.push(integrationAggregatorPath);
+      }
+    }
   }
   return result;
 }
+function buildSinkInput(def, surface, provider, repoImportSpecifier) {
+  const fields = def.fields ?? {};
+  const relationships = def.relationships ?? {};
+  const fkColumns = /* @__PURE__ */ new Set();
+  for (const rel2 of Object.values(relationships)) {
+    if (rel2.type === "belongs_to" && typeof rel2.foreign_key === "string") {
+      fkColumns.add(rel2.foreign_key);
+    }
+  }
+  const copyThroughFields = Object.entries(fields).filter(([name]) => name !== "id" && !fkColumns.has(name)).map(([name, f]) => ({
+    camelName: snakeToCamel(name),
+    tsType: tsTypeFor(f.type, f.nullable)
+  }));
+  const fkExternalKeys = Object.entries(relationships).filter(([, rel2]) => rel2.type === "belongs_to").map(([relName, rel2]) => {
+    const target = rel2.target ?? relName;
+    return { writeKey: `${snakeToCamel(target)}ExternalId` };
+  });
+  return {
+    entityName: def.entity.name,
+    entityClass: pascalFromSnake(def.entity.name),
+    surface,
+    pattern: "Integrated",
+    provider,
+    copyThroughFields,
+    fkExternalKeys,
+    repoImportSpecifier
+  };
+}
+var TS_TYPE_FOR_SINK = {
+  string: "string",
+  integer: "number",
+  decimal: "string",
+  boolean: "boolean",
+  uuid: "string",
+  date: "Date",
+  datetime: "Date",
+  json: "unknown"
+};
+function tsTypeFor(type, nullable) {
+  const base = TS_TYPE_FOR_SINK[type ?? "string"] ?? "unknown";
+  return nullable ? `${base} | null` : base;
+}
+function snakeToCamel(s) {
+  return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+function pascalFromSnake(s) {
+  const camel = snakeToCamel(s);
+  return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
 function writeFile(outPath, content) {
   mkdirSync3(dirname2(outPath), { recursive: true });
   writeFileSync3(outPath, content);
@@ -9245,10 +9828,13 @@ var EntityNewCommand = class extends Command2 {
           definition: s.definition,
           filePath: s.filePath
         }));
+        const assemblyTsAliases = resolveTsconfigAliases(ctx.cwd);
         const adapterResult = emitAdapters({
           providers: loadedProviders,
           entities: entityDefs,
-          outputRoot: adapterOutputRoot
+          outputRoot: adapterOutputRoot,
+          backendSrcAbs: path13.resolve(ctx.cwd, backendSrcForHandlers),
+          aliases: assemblyTsAliases?.aliases ?? {}
         });
         if (!isJsonMode()) {
           if (adapterResult.written.length || adapterResult.scaffoldsWritten.length) {
@@ -9256,12 +9842,20 @@ var EntityNewCommand = class extends Command2 {
               `adapter codegen: ${adapterResult.scaffoldsWritten.length} scaffold(s) + ${adapterResult.written.length} @generated \u2192 ${adapterOutputRoot}`
             );
           }
+          if (adapterResult.assembliesWritten.length || adapterResult.tokensWritten.length) {
+            printInfo(
+              `integration assembly codegen: ${adapterResult.assembliesWritten.length} module(s) + ${adapterResult.tokensWritten.length} tokens file(s) + ${adapterResult.integrationAggregatorsWritten.length} aggregator(s)`
+            );
+          }
           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})`);
           }
+          for (const s of adapterResult.skippedAssemblies) {
+            printWarning(`integration assembly: ${s.reason}`);
+          }
         }
       }
     } catch (err) {
@@ -13114,10 +13708,10 @@ var ProjectInitCommand = class extends Command7 {
 };
 function askConfirm(question) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     rl.question(`${question} [Y/n] `, (answer) => {
       rl.close();
-      resolve6(answer.trim().toLowerCase() !== "n");
+      resolve7(answer.trim().toLowerCase() !== "n");
     });
   });
 }