@pattern-stack/codegen 0.22.0 → 0.24.0

package/dist/src/cli/index.js

@@ -44,13 +44,13 @@ import {
   validateOrchestrationProject,
   validateProviders,
   writeManifest
-} from "../../chunk-6ECCJVYW.js";
+} from "../../chunk-K4BQQ2NN.js";
 import "../../chunk-KVOWSC5S.js";
-import "../../chunk-QFUIE37H.js";
-import "../../chunk-FFUDEIFF.js";
-import "../../chunk-EO2QPOKH.js";
 import "../../chunk-PRWIX6UW.js";
-import "../../chunk-O2A6XHGD.js";
+import "../../chunk-KFXXOFDC.js";
+import "../../chunk-HN5HT5WL.js";
+import "../../chunk-EO2QPOKH.js";
+import "../../chunk-LLDJS7PJ.js";
 import "../../chunk-HNWZFNKP.js";
 import "../../chunk-AHV4GDYM.js";
 import "../../chunk-SQDOBLBP.js";
@@ -63,8 +63,8 @@ import {
 } from "../../chunk-5TK7MEN4.js";
 import "../../chunk-4KNXX6TI.js";
 import "../../chunk-3CJFPU6Q.js";
-import "../../chunk-TDEHU73T.js";
-import "../../chunk-S7C6TIIF.js";
+import "../../chunk-YIVQ7KLS.js";
+import "../../chunk-S5G3HO7N.js";
 import "../../chunk-MZ6GV4YF.js";
 import "../../chunk-LG57S2SC.js";
 import "../../chunk-U64T4YZE.js";
@@ -2151,7 +2151,7 @@ function loadEvents(eventsDir, entityNames) {
 function desugarEntityEvents(entity) {
   const entityName = entity.entity.name;
   const entityEvents = entity.events ?? [];
-  return entityEvents.map((ev) => {
+  const explicit = entityEvents.map((ev) => {
     const payload = {};
     for (const [key, typeString] of Object.entries(ev.body)) {
       if (!isEventFieldType(typeString)) {
@@ -2173,6 +2173,56 @@ function desugarEntityEvents(entity) {
     };
     return def;
   });
+  const changeTriad = desugarEmitChangeEvents(entity);
+  return [...explicit, ...changeTriad];
+}
+var EMIT_CHANGE_SUFFIXES = ["created", "edited", "deleted"];
+function desugarEmitChangeEvents(entity) {
+  if (entity.integration?.sink?.emit_changes !== true) return [];
+  const entityName = entity.entity.name;
+  const basePayload = {
+    entity_id: {
+      type: "uuid",
+      nullable: false,
+      description: "Local aggregate id the sink wrote/soft-deleted."
+    },
+    external_id: {
+      type: "string",
+      nullable: false,
+      description: "Vendor external id the change keyed on."
+    },
+    provider: {
+      type: "string",
+      nullable: false,
+      description: "Provider label (e.g. 'slack', 'google')."
+    },
+    source: {
+      type: "string",
+      nullable: false,
+      description: "Provenance marker \u2014 always 'integration'. A write-back action reads this to avoid echoing the change back to the vendor."
+    }
+  };
+  return EMIT_CHANGE_SUFFIXES.map((suffix) => {
+    const payload = { ...basePayload };
+    if (suffix !== "deleted") {
+      payload.changed_fields = {
+        type: "json",
+        nullable: true,
+        description: "Differ's per-field before/after map (same value as integration_run_items.changed_fields)."
+      };
+    }
+    const def = {
+      type: `${entityName}_${suffix}`,
+      tier: "domain",
+      direction: "change",
+      aggregate: entityName,
+      payload,
+      retry: { attempts: 3, backoff: "exponential" },
+      version: 1,
+      pool: DIRECTION_TO_POOL.change
+    };
+    return def;
+  });
 }
 function isEventFieldType(s) {
   return EVENT_FIELD_TYPES.includes(s);
@@ -2737,6 +2787,12 @@ function drizzleJobsExtensions(backend, cfg) {
   if (typeof drizzle.listen_notify === "boolean") out.listenNotify = drizzle.listen_notify;
   if (typeof drizzle.poll_interval_ms === "number")
     out.pollIntervalMs = drizzle.poll_interval_ms;
+  if (typeof drizzle.stale_sweeper_interval_ms === "number")
+    out.staleSweeperIntervalMs = drizzle.stale_sweeper_interval_ms;
+  if (typeof drizzle.stale_threshold_ms === "number")
+    out.staleThresholdMs = drizzle.stale_threshold_ms;
+  if (typeof drizzle.claim_heartbeat_interval_ms === "number")
+    out.claimHeartbeatIntervalMs = drizzle.claim_heartbeat_interval_ms;
   return Object.keys(out).length > 0 ? out : void 0;
 }
 function drizzleExtensionsClause(ext, key) {
@@ -3690,64 +3746,207 @@ import {
 } from "fs";
 import { dirname, join as join8 } from "path";
 
+// src/cli/shared/change-emitter-emission-generator.ts
+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 changeEmitterClass(entityClass) {
+  return `${entityClass}ChangeEmitter`;
+}
+function generateChangeEmitter(input) {
+  const mode = input.mode ?? "package";
+  const cls = changeEmitterClass(input.entityClass);
+  const eventsImport = subsystemsImport(mode, "events");
+  const integrationImport = subsystemsImport(mode, "integration");
+  const createdType = `${input.entityName}_created`;
+  const editedType = `${input.entityName}_edited`;
+  const deletedType = `${input.entityName}_deleted`;
+  return `${generatedBanner(input.sourceDesc)}
+import { Inject, Injectable } from '@nestjs/common';
+import { TYPED_EVENT_BUS } from '${eventsImport}';
+import type {
+  IIntegrationChangeEmitter,
+  IntegrationChangeNotification,
+} from '${integrationImport}';
+
+/**
+ * Minimal publisher shape the emitter calls \u2014 decoupled from BOTH the package's
+ * \`TypedEventBus\` (whose \`EventTypeName\` union is the package's own events) and
+ * the consumer's generated \`TypedEventBus\` (whose union is the consumer's
+ * events). The \`${createdType}\` / \`${editedType}\` / \`${deletedType}\` events
+ * THIS class publishes live in the CONSUMER's registry; the structural \`publish\`
+ * here accepts the string types without depending on either compile-time union.
+ * The TYPED_EVENT_BUS token resolves to the consumer's generated bus at runtime
+ * (bound by EventsModule.forRoot()), which validates the payload against the
+ * generated event schema.
+ */
+interface ChangeEventPublisher {
+  publish(
+    type: string,
+    aggregateId: string,
+    payload: Record<string, unknown>,
+    opts?: { tx?: unknown; metadata?: Record<string, unknown> },
+  ): Promise<void>;
+}
+
+/**
+ * ${cls} \u2014 publishes the typed ${input.entityName} data-level change events
+ * (\`${createdType}\` / \`${editedType}\` / \`${deletedType}\`) after the
+ * integration orchestrator's sink write/soft-delete (EMIT-CHANGES seam).
+ *
+ * Bound to INTEGRATION_CHANGE_EMITTER in the ${input.entityName} integration
+ * assembly; the orchestrator calls \`emitChange\` once per real change. The
+ * payload carries \`source: 'integration'\` so a write-back action can detect an
+ * integration-originated change and decline to echo it back to the vendor.
+ */
+@Injectable()
+export class ${cls} implements IIntegrationChangeEmitter {
+  constructor(
+    @Inject(TYPED_EVENT_BUS) private readonly bus: ChangeEventPublisher,
+  ) {}
+
+  async emitChange(notification: IntegrationChangeNotification): Promise<void> {
+    const type =
+      notification.action === 'created'
+        ? '${createdType}'
+        : notification.action === 'updated'
+          ? '${editedType}'
+          : '${deletedType}';
+
+    const payload: Record<string, unknown> = {
+      entityId: notification.entityId,
+      externalId: notification.externalId,
+      provider: notification.provider,
+      source: 'integration',
+    };
+    // changedFields is present on created/edited only (deletes are tombstones).
+    if (notification.changedFields !== undefined) {
+      payload['changedFields'] = notification.changedFields;
+    }
+
+    await this.bus.publish(type, notification.entityId, payload, {
+      tx: notification.tx,
+      metadata:
+        notification.tenantId !== undefined && notification.tenantId !== null
+          ? { tenantId: notification.tenantId }
+          : undefined,
+    });
+  }
+}
+`;
+}
+
 // 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`,
+    sinkBaseClass: `${entityClass}SinkBase`,
     repoClass: `${entityClass}Repository`,
     projectionType: `${entityClass}IntegrationProjection`,
-    writeType: `${entityClass}IntegrationWrite`
+    writeType: `${entityClass}IntegrationWrite`,
+    defaultBuildWrite: `default${entityClass}BuildWrite`,
+    defaultToCanonicalView: `default${entityClass}ToCanonicalView`
   };
 }
-function generateDefaultSink(input) {
+function assertIntegrated(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);
+}
+function buildWriteBodyLines(input, n) {
   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 = [
+  const fkLines = input.fkExternalKeys.flatMap((fk) => [
+    `      // SEAM (FK external key \u2014 null until you widen ${n.projectionType} to carry \`${fk.writeKey}\`):`,
+    `      // Replace null with record.${fk.writeKey} after widening. Write-safe: repo skips null FKs.`,
+    `      ${fk.writeKey}: null,`
+  ]);
+  const lines = [
     `      externalId: record.externalId,`
   ];
   if (copyThroughLines.length > 0) {
-    writeBodyLines.push(
+    lines.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 (fkLines.length > 0) {
+    lines.push(
+      `      // FK external join-keys (null until canonical widens to carry them):`,
+      ...fkLines
     );
   }
   if (hasUserIdField) {
-    writeBodyLines.push(`      userId,`);
+    lines.push(`      userId,`);
+  }
+  return lines;
+}
+function buildFindViewLines(input) {
+  const viewFields = input.viewCopyThroughFields ?? input.copyThroughFields;
+  const lines = [
+    `    id: row.id,`,
+    `    externalId: row.externalId,`
+  ];
+  for (const f of viewFields) {
+    const isJson = f.tsType.startsWith("unknown");
+    if (isJson) {
+      lines.push(`    // SEAM (typed json \u2014 unknown; narrow on canonical widen): ${f.camelName}`);
+    }
+    lines.push(`    ${f.camelName}: row.${f.camelName},`);
+  }
+  for (const localFk of input.localFkColumns ?? []) {
+    lines.push(`    ${localFk.camelName}: row.${localFk.camelName},`);
+  }
+  if (input.hasTimestamps) {
+    lines.push(`    createdAt: row.createdAt,`);
+    lines.push(`    updatedAt: row.updatedAt,`);
+  }
+  return lines;
+}
+function buildDeleteBody(input) {
+  if ((input.deleteMode ?? "delegate") === "noop") {
+    return [
+      `// delete:noop (YAML integration.sink.delete: noop) \u2014 tombstone-preserving:`,
+      `// an upstream delete signal is a no-op here; the repo row is left intact.`,
+      `// Returns null \u2192 the orchestrator records an audit noop. Override this`,
+      `// method in the subclass if you need a log line.`,
+      `return null;`
+    ].join("\n    ");
   }
+  return `return this.repo.softDeleteByExternalId(externalId, this.provider);`;
+}
+function generateSinkBase(input) {
+  assertIntegrated(input);
+  const n = sinkNames(input.entityClass);
+  const writeBodyLines = buildWriteBodyLines(input, n);
   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.
+  const findViewLines = buildFindViewLines(input);
+  const findViewBody = findViewLines.map((l) => `  ${l}`).join("\n");
+  const deleteBody = buildDeleteBody(input);
+  const banner = `// @generated by @pattern-stack/codegen from definitions entity '${input.entityName}' (surface: ${input.surface}) \u2014 DO NOT EDIT.
+// Hand edits are overwritten on re-emit. Regenerate with \`bun run codegen\`.
 //
-// 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';
+// Two-file seam (Shape C, #491, RFC-0002 \xA74):
+//   THIS FILE  \u2014 @generated base: two standalone default functions at concrete types
+//                + abstract class ${n.sinkBaseClass}<TCanonical>.
+//                A YAML field change reflows the mapping here on every run.
+//   ${input.entityName}.sink.ts \u2014 emit-once subclass: \`class ${n.sinkClass} extends ${n.sinkBaseClass}\`
+//                with the two one-line seam wirings. Author overrides survive regen.
+//
+// SEAM #1 (canonical widening): change \`extends ${n.sinkBaseClass}\` \u2192
+//   \`extends ${n.sinkBaseClass}<YourCanonical>\` in the subclass.
+// SEAM #2 (FK activation): override \`buildWrite\` in the subclass.
+//   Replace \`${n.defaultBuildWrite}(record)\` with your body that sets
+//   \`<writeKey>: record.<writeKey>\` after widening the canonical to carry it.
+// SEAM #3/#4 (typed-json narrow / null-coerce on widen): override \`toCanonicalView\`.
+//   The bare passthrough preserves null (diff-soundness); coerce only on canonical widen.`;
+  return `${banner}
 import type { IIntegrationSink } from '${subsystemsImport(input.mode ?? "package", "integration")}';
 import {
   ${n.repoClass},
@@ -3755,54 +3954,110 @@ import {
   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};
+// Standalone default functions at CONCRETE projection/write types \u2014 the literal IS the
+// return type, so NO cast is needed (this is what dodges the TS2322 of a generic default
+// body). The regenerated home of the #487 write body and #488 find view.
+// Override these in the emit-once subclass via buildWrite / toCanonicalView.
+export function ${n.defaultBuildWrite}(record: ${n.projectionType}): ${n.writeType} {
+  return {
+${writeBody}
+  };
+}
 
-@Injectable()
-export class ${n.sinkClass} implements IIntegrationSink<${n.canonicalType}> {
+export function ${n.defaultToCanonicalView}(row: ${n.projectionType}): ${n.projectionType} {
+  // BARE passthrough \u2014 preserves null so the orchestrator's DeepEqualDiffer converges
+  // to noop (null \u2260 ''; deep-equal.differ.ts:187-208). The projection-default canonical
+  // is exactly the projection shape, so bare passthrough type-checks without a cast.
+  const view: ${n.projectionType} = {
+${findViewBody}
+  };
+  return view;
+}
+
+// Abstract base \u2014 the three IIntegrationSink methods are CONCRETE (machinery: provider
+// assert, repo delegation, #490 knob-driven delete). The two protected abstract seams are
+// typed at TCanonical with NO body \u2014 a default body returning TCanonical would be TS2322
+// (Shape A failure \u2014 see RFC-0002 \xA74 and the \xA73b gate: sink-widened-canonical.gate.test.ts).
+// The bodies live in the standalone functions above; the emit-once subclass wires them in one
+// line each. No @Injectable() \u2014 the assembly binds via useFactory (OQ2 CLOSED, #491).
+export abstract class ${n.sinkBaseClass}<TCanonical = ${n.projectionType}>
+  implements IIntegrationSink<TCanonical> {
   constructor(
-    private readonly repo: ${n.repoClass},
-    private readonly provider: string,
+    protected readonly repo: ${n.repoClass},
+    protected readonly provider: string,
   ) {}
 
-  async findByExternalId(userId: string, externalId: string): Promise<${n.canonicalType} | null> {
+  async findByExternalId(userId: string, externalId: string): Promise<TCanonical | null> {
     const row = await this.repo.findByExternalIdProjected(externalId, this.provider);
+    if (row === null) return null;
     // 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;
+    return this.toCanonicalView(row);
   }
 
   async upsertByExternalId(
     userId: string,
-    record: ${n.canonicalType},
+    record: TCanonical,
     provider: string,
-  ): Promise<{ id: string; saved: ${n.canonicalType} }> {
+  ): Promise<{ id: string; saved: TCanonical }> {
     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);
+    const proj = await this.repo.integrationUpsertOne(this.buildWrite(record), 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);
+    ${deleteBody}
   }
+
+  // ABSTRACT seams (NO body \u2014 a default body returning TCanonical is TS2322).
+  // The projection-default subclass wires the default functions; a widened
+  // subclass reimplements them (FK activation / typed-json narrow / null-coerce).
+  protected abstract toCanonicalView(row: ${n.projectionType}): TCanonical;
+  protected abstract buildWrite(record: TCanonical): ${n.writeType};
 }
 `;
 }
-function relationLabel(writeKey) {
-  const stripped = writeKey.replace(/ExternalId$/, "");
-  return stripped || "related entity";
+function generateSinkSubclass(input) {
+  assertIntegrated(input);
+  const n = sinkNames(input.entityClass);
+  return `// Emit-once \u2014 author-owned. Regen never overwrites this file.
+// The mechanical mapping lives in ${input.entityName}.sink.generated.ts and reflows on every
+// codegen run (a YAML field change reflows into the @generated base + default functions).
+//
+// To WIDEN (all four seams \u2014 see ${input.entityName}.sink.generated.ts banner for detail):
+//   1. Change \`extends ${n.sinkBaseClass}\` \u2192 \`extends ${n.sinkBaseClass}<YourCanonical>\`.
+//   2. Override \`toCanonicalView\`: reshape projection, narrow typed json, coerce nulls.
+//   3. Override \`buildWrite\`: activate FK write keys (\`<writeKey>: record.<writeKey>\`).
+//   4. Optionally override \`softDeleteByExternalId\` if you want a log line.
+//      (The base handles delegate/noop via the #490 YAML knob \u2014 no override needed otherwise.)
+// Source: definitions entity '${input.entityName}' (surface: ${input.surface}).
+import {
+  ${n.sinkBaseClass},
+  ${n.defaultToCanonicalView},
+  ${n.defaultBuildWrite},
+} from './${input.entityName}.sink.generated';
+import type {
+  ${n.projectionType},
+  ${n.writeType},
+} from '${input.repoImportSpecifier}';
+
+export class ${n.sinkClass} extends ${n.sinkBaseClass} {
+  protected toCanonicalView(row: ${n.projectionType}): ${n.projectionType} {
+    return ${n.defaultToCanonicalView}(row);
+  }
+
+  protected buildWrite(record: ${n.projectionType}): ${n.writeType} {
+    return ${n.defaultBuildWrite}(record);
+  }
+}
+`;
 }
 
 // src/cli/shared/assembly-emission-generator.ts
 import { relative, resolve as resolve2, sep } from "path";
-function generatedBanner(sourceDesc) {
+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\`.`;
 }
@@ -3833,19 +4088,30 @@ function generateAssemblyModule(input) {
   const token = integrationUseCaseToken(input.entityName, input.provider);
   const moduleClass = assemblyModuleClass(input.entityName, input.provider);
   const tokensImport = `../../${input.surface}-integration.tokens`;
-  return `${generatedBanner(input.sourceDesc)}
+  const emitChanges = input.emitChanges === true;
+  const emitterClass = changeEmitterClass(input.entityClass);
+  const emitterImport = `../../sinks/${input.entityName}.change-emitter`;
+  const integrationTokenImports = emitChanges ? `  INTEGRATION_CHANGE_EMITTER,
+  INTEGRATION_CHANGE_SOURCE,
+  INTEGRATION_SINK,` : `  INTEGRATION_CHANGE_SOURCE,
+  INTEGRATION_SINK,`;
+  const emitterImportLine = emitChanges ? `
+import { ${emitterClass} } from '${emitterImport}';` : "";
+  const emitterProviderBlock = emitChanges ? `
+    ${emitterClass},
+    { provide: INTEGRATION_CHANGE_EMITTER, useExisting: ${emitterClass} },` : "";
+  return `${generatedBanner2(input.sourceDesc)}
 import { Module } from '@nestjs/common';
 import {
   ExecuteIntegrationUseCase,
-  INTEGRATION_CHANGE_SOURCE,
-  INTEGRATION_SINK,
+${integrationTokenImports}
 } from '${subsystemsImport(input.mode ?? "package", "integration")}';
 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}';
+import { ${token} } from '${tokensImport}';${emitterImportLine}
 
 /**
  * ${moduleClass} \u2014 the ${input.surface}/${input.entityName} \u2190 ${input.provider}
@@ -3855,7 +4121,12 @@ import { ${token} } from '${tokensImport}';
  * \`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,
+ * assembly provides it).${emitChanges ? `
+ *
+ * EMIT-CHANGES: binds INTEGRATION_CHANGE_EMITTER to ${emitterClass} so the
+ * orchestrator publishes typed ${input.entityName}_created/_edited/_deleted events
+ * after every sink write/soft-delete (integration.sink.emit_changes).
+ *` : ""} The substrate (cursor store, run recorder, differ,
  * multi-tenant flag) comes from the global IntegrationModule.forRoot(...) in
  * AppModule, never re-bound here.
  */
@@ -3871,7 +4142,7 @@ import { ${token} } from '${tokensImport}';
       provide: INTEGRATION_SINK,
       useFactory: (repo: ${input.repoClass}) => new ${sinkClass}(repo, '${input.provider}'),
       inject: [${input.repoClass}],
-    },
+    },${emitterProviderBlock}
     ExecuteIntegrationUseCase,
     { provide: ${token}, useExisting: ExecuteIntegrationUseCase },
   ],
@@ -3891,7 +4162,7 @@ function generateIntegrationTokens(surface, entries) {
  *  (${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}`)}
+  return `${generatedBanner2(`surface: ${surface}`)}
 /**
  * Use-case handles for the \`${surface}\` surface \u2014 one per (entity, provider)
  * assembly. Each is a Symbol \`provide:\` token a per-entity
@@ -3917,7 +4188,7 @@ function generateIntegrationAggregator(surface, entries) {
     return `import { ${cls} } from '${path36}';`;
   }).join("\n");
   const membersInline = moduleClasses.join(", ");
-  return `${generatedBanner(`surface: ${surface}`)}
+  return `${generatedBanner2(`surface: ${surface}`)}
 import { Module } from '@nestjs/common';
 ${importLines || "// no (entity, provider) integration assemblies on this surface yet"}
 
@@ -3993,6 +4264,7 @@ function resolveEntityModuleImports(input) {
 }
 
 // src/cli/shared/adapter-emission-generator.ts
+import pluralize2 from "pluralize";
 var SURFACE_REGISTRY = {
   crm: {
     packageName: "@pattern-stack/codegen-crm",
@@ -4068,8 +4340,8 @@ var SURFACE_REGISTRY = {
 function isClientlessProvider(surfaces) {
   return surfaces.length > 0 && surfaces.every((s) => SURFACE_REGISTRY[s]?.readPrimitive === true);
 }
-var SCAFFOLD_SENTINEL2 = "// <CODEGEN-SCAFFOLD-V1>";
-function generatedBanner2(sourceDesc) {
+var SCAFFOLD_SENTINEL = "// <CODEGEN-SCAFFOLD-V1>";
+function generatedBanner3(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\`.`;
 }
@@ -4278,7 +4550,7 @@ ${l2Members}
   const ctorOpen = rp ? `  constructor(@Inject(${n.strategyToken}) readonly auth: IAuthStrategy) {${changeSourcesAssign}}` : `  constructor(
     @Inject(${n.strategyToken}) readonly auth: IAuthStrategy,${ctorClientParam}
   ) {${changeSourcesAssign}}`;
-  return `${SCAFFOLD_SENTINEL2}
+  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}).
@@ -4309,7 +4581,7 @@ ${changeSourcesDecl}
 }
 function generateAdapterModule(def, surface) {
   const n = names(def.slug, surface);
-  return `${generatedBanner2(`definitions/providers/${def.slug}.yaml (surface: ${surface})`)}
+  return `${generatedBanner3(`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';
@@ -4327,13 +4599,13 @@ function generateAdaptersBarrel(surface, providerSlugs) {
     const n = names(slug, surface);
     return `export { ${n.adapterModuleClass} } from './${slug}/${slug}-${surface}.adapter.module';`;
   }).join("\n");
-  return `${generatedBanner2(`definitions/providers/*.yaml (surface: ${surface})`)}
+  return `${generatedBanner3(`definitions/providers/*.yaml (surface: ${surface})`)}
 ${lines}
 `;
 }
 function generateSurfaceTokens(surface, mode = "package") {
   const n = names("__placeholder__", surface);
-  return `${generatedBanner2(`surface: ${surface}`)}
+  return `${generatedBanner3(`surface: ${surface}`)}
 import type { IChangeSource } from '${subsystemsImport(mode, "integration")}';
 
 /** The assembled list of every ${surface} adapter's contribution. */
@@ -4372,7 +4644,7 @@ function generateSurfaceAggregator(surface, providerSlugs, mode = "package") {
     return `${lowerFirst(p.adapterClass)}: ${p.adapterClass}`;
   }).join(", ");
   const injectTokens = per.map((p) => p.adapterClass).join(", ");
-  return `${generatedBanner2(`surface: ${surface}`)}
+  return `${generatedBanner3(`surface: ${surface}`)}
 import { Module } from '@nestjs/common';
 import {
   MemoryEntityChangeSourceRegistry,
@@ -4444,7 +4716,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 `${generatedBanner2(`surface: ${surface}`)}
+  return `${generatedBanner3(`surface: ${surface}`)}
 /**
  * Per-consumer typed view for the \`${surface}\` surface. Surface-scoped unions
  * + a (provider, entity) validity map for compile-time-checked consumer
@@ -4474,6 +4746,7 @@ function emitAdapters(opts) {
     scaffoldsSkipped: [],
     skippedSurfaces: [],
     assembliesWritten: [],
+    changeEmittersWritten: [],
     tokensWritten: [],
     integrationAggregatorsWritten: [],
     skippedAssemblies: []
@@ -4574,14 +4847,31 @@ function emitAdapters(opts) {
           backendSrcAbs: opts.backendSrcAbs,
           aliases
         });
-        const sinkPath = join8(sinksDir, `${entityName}.sink.ts`);
-        if (existsSync6(sinkPath)) {
-          result.scaffoldsSkipped.push(sinkPath);
+        const sinkInput = buildSinkInput(def, surface, slugs[0], loc.repoImportSpecifier);
+        const basePath = join8(sinksDir, `${entityName}.sink.generated.ts`);
+        const baseContent = generateSinkBase({ ...sinkInput, mode });
+        if (!opts.dryRun) writeIfChanged(basePath, baseContent);
+        result.written.push(basePath);
+        const subclassPath = join8(sinksDir, `${entityName}.sink.ts`);
+        if (existsSync6(subclassPath)) {
+          result.scaffoldsSkipped.push(subclassPath);
         } else {
-          const sinkInput = buildSinkInput(def, surface, slugs[0], loc.repoImportSpecifier);
-          const sinkContent = generateDefaultSink({ ...sinkInput, mode });
-          if (!opts.dryRun) writeFile(sinkPath, sinkContent);
-          result.scaffoldsWritten.push(sinkPath);
+          const subclassContent = generateSinkSubclass({ ...sinkInput, mode });
+          if (!opts.dryRun) writeFile(subclassPath, subclassContent);
+          result.scaffoldsWritten.push(subclassPath);
+        }
+        const emitChanges = def?.integration?.sink?.emit_changes === true;
+        if (emitChanges) {
+          const emitterPath = join8(sinksDir, `${entityName}.change-emitter.ts`);
+          const emitterContent = generateChangeEmitter({
+            entityName,
+            entityClass: loc.entityClass,
+            surface,
+            sourceDesc: `definitions entity '${entityName}' (integration.sink.emit_changes)`,
+            mode
+          });
+          if (!opts.dryRun) writeIfChanged(emitterPath, emitterContent);
+          result.changeEmittersWritten.push(emitterPath);
         }
         for (const slug of slugs) {
           const assemblyPath = join8(
@@ -4599,7 +4889,8 @@ function emitAdapters(opts) {
             repoImportSpecifier: loc.repoImportSpecifier,
             repoClass: loc.repoClass,
             sourceDesc: `definitions/providers/${slug}.yaml`,
-            mode
+            mode,
+            emitChanges
           });
           if (!opts.dryRun) writeIfChanged(assemblyPath, assemblyContent);
           result.assembliesWritten.push(assemblyPath);
@@ -4630,6 +4921,13 @@ function emitAdapters(opts) {
   }
   return result;
 }
+function fkWriteKey(target, foreignKey, isSelfFk) {
+  if (isSelfFk) {
+    const base = foreignKey.endsWith("_id") ? foreignKey.slice(0, -3) : foreignKey;
+    return snakeToCamel(base) + "ExternalId";
+  }
+  return `${target}ExternalId`;
+}
 function buildSinkInput(def, surface, provider, repoImportSpecifier) {
   const fields = def.fields ?? {};
   const relationships = def.relationships ?? {};
@@ -4639,14 +4937,35 @@ function buildSinkInput(def, surface, provider, repoImportSpecifier) {
       fkColumns.add(rel2.foreign_key);
     }
   }
-  const copyThroughFields = Object.entries(fields).filter(([name]) => name !== "id" && !fkColumns.has(name)).map(([name, f]) => ({
+  const excludeSet = new Set(def.integration?.sink?.exclude_fields ?? []);
+  const isCopyThrough = ([name]) => name !== "id" && !fkColumns.has(name);
+  const viewCopyThroughFields = Object.entries(fields).filter(isCopyThrough).map(([name, f]) => ({
+    camelName: snakeToCamel(name),
+    tsType: tsTypeFor(f.type, f.nullable)
+  }));
+  const copyThroughFields = Object.entries(fields).filter((entry) => isCopyThrough(entry) && !excludeSet.has(entry[0])).map(([name, f]) => ({
     camelName: snakeToCamel(name),
     tsType: tsTypeFor(f.type, f.nullable)
   }));
+  const entityNamePlural = def.entity.plural ?? pluralize2.plural(def.entity.name);
   const fkExternalKeys = Object.entries(relationships).filter(([, rel2]) => rel2.type === "belongs_to").map(([relName, rel2]) => {
     const target = rel2.target ?? relName;
-    return { writeKey: `${snakeToCamel(target)}ExternalId` };
+    const foreignKey = rel2.foreign_key ?? `${target}_id`;
+    const isSelfFk = pluralize2.plural(target) === entityNamePlural;
+    return { writeKey: fkWriteKey(target, foreignKey, isSelfFk) };
   });
+  const localFkColumns = Object.entries(relationships).filter(([, rel2]) => rel2.type === "belongs_to").map(([relName, rel2]) => {
+    const foreignKey = rel2.foreign_key ?? `${relName}_id`;
+    return {
+      camelName: snakeToCamel(foreignKey),
+      tsType: rel2.nullable ? "string | null" : "string"
+    };
+  });
+  const hasTimestamps2 = (def.behaviors ?? []).some(
+    (b) => typeof b === "string" ? b === "timestamps" : b.name === "timestamps"
+  );
+  const deleteKnob = def.integration?.sink?.delete;
+  const deleteMode = deleteKnob === "noop" ? "noop" : "delegate";
   return {
     entityName: def.entity.name,
     entityClass: pascalFromSnake(def.entity.name),
@@ -4654,8 +4973,12 @@ function buildSinkInput(def, surface, provider, repoImportSpecifier) {
     pattern: "Integrated",
     provider,
     copyThroughFields,
+    viewCopyThroughFields,
     fkExternalKeys,
-    repoImportSpecifier
+    localFkColumns,
+    hasTimestamps: hasTimestamps2,
+    repoImportSpecifier,
+    deleteMode
   };
 }
 var TS_TYPE_FOR_SINK = {
@@ -4901,12 +5224,12 @@ function resolveSyncMode(entity, config) {
 // src/emitters/frontend/emit-utils.ts
 import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname3 } from "path";
-function generatedBanner3(sourceDesc) {
+function generatedBanner4(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 withBanner(sourceDesc, body) {
-  return `${generatedBanner3(sourceDesc)}
+  return `${generatedBanner4(sourceDesc)}
 
 ${body}`;
 }
@@ -6742,6 +7065,11 @@ var EntityNewCommand = class extends Command2 {
               `integration assembly codegen: ${adapterResult.assembliesWritten.length} module(s) + ${adapterResult.tokensWritten.length} tokens file(s) + ${adapterResult.integrationAggregatorsWritten.length} aggregator(s)`
             );
           }
+          if (adapterResult.changeEmittersWritten.length) {
+            printInfo(
+              `integration change-emitters (emit_changes): ${adapterResult.changeEmittersWritten.length} emitter(s)`
+            );
+          }
           for (const s of adapterResult.scaffoldsSkipped) {
             printInfo(`skipped scaffold ${s} (author-owned)`);
           }