@pattern-stack/codegen 0.22.0 → 0.23.0

package/dist/runtime/subsystems/jobs/jobs-domain.module.d.ts

@@ -37,6 +37,25 @@ interface DrizzleBackendExtensions {
     listenNotify?: boolean;
     /** Polling interval (ms). Default 1000. */
     pollIntervalMs?: number;
+    /**
+     * CLAIM-HB-1 — stale-claim sweep interval (ms). How often each worker scans
+     * for `running` rows whose lease has expired. Default 60_000.
+     */
+    staleSweeperIntervalMs?: number;
+    /**
+     * CLAIM-HB-1 — stale-claim threshold (ms). A `running` row whose `claimed_at`
+     * has not been renewed within this window is presumed stranded by a dead
+     * worker and reset to `pending`. A LIVE worker renews the lease every
+     * `claimHeartbeatIntervalMs`, so this only catches genuine crashes. Default
+     * 300_000 (5 min).
+     */
+    staleThresholdMs?: number;
+    /**
+     * CLAIM-HB-1 — claim heartbeat interval (ms). How often a worker bumps
+     * `claimed_at` for its in-flight runs to keep them from being swept. Must be
+     * comfortably below `staleThresholdMs`. Default `staleThresholdMs / 3`.
+     */
+    claimHeartbeatIntervalMs?: number;
 }
 interface JobsDomainModuleOptions {
     backend: 'drizzle' | 'memory' | 'bullmq';

package/dist/runtime/subsystems/jobs/jobs-domain.module.js

@@ -1,6 +1,6 @@
 import {
   JobsDomainModule
-} from "../../../chunk-6DQEIXYU.js";
+} from "../../../chunk-FIUC6QB5.js";
 import "../../../chunk-VQOAATIG.js";
 import "../../../chunk-3VEVGL74.js";
 import "../../../chunk-CDLWYZVQ.js";

package/dist/src/cli/index.js

@@ -44,7 +44,7 @@ import {
   validateOrchestrationProject,
   validateProviders,
   writeManifest
-} from "../../chunk-6ECCJVYW.js";
+} from "../../chunk-4M66MQYA.js";
 import "../../chunk-KVOWSC5S.js";
 import "../../chunk-QFUIE37H.js";
 import "../../chunk-FFUDEIFF.js";
@@ -2737,6 +2737,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) {
@@ -3691,63 +3697,115 @@ import {
 import { dirname, join as join8 } 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`,
+    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,49 +3813,105 @@ 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
@@ -3993,6 +4107,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,7 +4183,7 @@ var SURFACE_REGISTRY = {
 function isClientlessProvider(surfaces) {
   return surfaces.length > 0 && surfaces.every((s) => SURFACE_REGISTRY[s]?.readPrimitive === true);
 }
-var SCAFFOLD_SENTINEL2 = "// <CODEGEN-SCAFFOLD-V1>";
+var SCAFFOLD_SENTINEL = "// <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\`.`;
@@ -4278,7 +4393,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}).
@@ -4574,14 +4689,18 @@ 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);
         }
         for (const slug of slugs) {
           const assemblyPath = join8(
@@ -4630,6 +4749,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 +4765,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 +4801,12 @@ function buildSinkInput(def, surface, provider, repoImportSpecifier) {
     pattern: "Integrated",
     provider,
     copyThroughFields,
+    viewCopyThroughFields,
     fkExternalKeys,
-    repoImportSpecifier
+    localFkColumns,
+    hasTimestamps: hasTimestamps2,
+    repoImportSpecifier,
+    deleteMode
   };
 }
 var TS_TYPE_FOR_SINK = {