@pattern-stack/codegen 0.22.0 → 0.24.0

package/templates/entity/new/clean-lite-ps/prompt-extension.js

@@ -852,6 +852,29 @@ function processSearchQueries(queriesBlock, processedFields, belongsTo, entityNa
 // Integration write-surface derivation (#374)
 // ============================================================================
 
+/**
+ * Shared delete-knob → softDelete boolean mapping rule (#490).
+ *
+ * Applied at BOTH derivations (repo config + sink body) so the two always agree:
+ *   soft      → true  (set deletedAt)
+ *   tombstone → false (null externalId/provider)
+ *   absent    → !!hasSoftDelete  (preserve today's default)
+ *   noop      → !!hasSoftDelete  (repo config irrelevant for noop — sink short-circuits)
+ *
+ * The sink only needs 'delegate' | 'noop' for its body decision; this helper
+ * is for the REPO config boolean. Mirrored verbatim in buildSinkInput caller
+ * (adapter-emission-generator.ts) for the contract test (spec Tests §3d).
+ *
+ * @param {'soft'|'tombstone'|'noop'|undefined} deleteKnob
+ * @param {boolean} hasSoftDelete
+ * @returns {boolean}
+ */
+export function resolveSoftDeleteBoolean(deleteKnob, hasSoftDelete) {
+  if (deleteKnob === 'soft') return true;
+  if (deleteKnob === 'tombstone') return false;
+  return !!hasSoftDelete; // absent OR noop → preserve current default
+}
+
 /**
  * Pre-compute the inbound-integration write surface for a `pattern: Integrated` entity.
  * Keeps the EJS thin + unit-testable: the template hand-emits the integrationConfig
@@ -866,14 +889,27 @@ function processSearchQueries(queriesBlock, processedFields, belongsTo, entityNa
  * @param {boolean} hasTimestamps
  * @param {boolean} eavEnabled
  * @param {boolean} hasSoftDelete
+ * @param {object} [fields]           raw entity fields (for FK strict detection)
+ * @param {object} [sinkPolicy]       integration.sink knobs {delete?, exclude_fields?}
  */
-export function buildIntegrationSurface(patternName, processedFields, belongsTo, hasTimestamps, eavEnabled, hasSoftDelete, fields) {
+export function buildIntegrationSurface(patternName, processedFields, belongsTo, hasTimestamps, eavEnabled, hasSoftDelete, fields, sinkPolicy) {
   if (patternName !== 'Integrated') return null;
 
+  // Per-field exclusion (#490): drop declared-excluded fields from copy-through.
+  // Exclusion targets copy-through scalars only (FK columns and user_id are
+  // rejected at schema validation — the schema superRefine guards both).
+  // Match on snake_case `name` (how processedFields.name is keyed) so a
+  // multi-word field like `conversation_external_id` matches correctly.
+  const excludeSet = new Set(sinkPolicy?.exclude_fields ?? []);
+
   // Copy-through columns: every non-FK declared field. external_id_tracking
   // columns (external_id/provider/provider_metadata) are injected by the
   // behavior, NOT present in processedFields, so they're already excluded.
-  const writeColumns = processedFields.map((f) => f.camelName);
+  // Excluded fields (#490) are also dropped here — they are removed from the
+  // copy-through write surface so integrationUpsertOne never clobbers them.
+  const writeColumns = processedFields
+    .filter((f) => !excludeSet.has(f.name))
+    .map((f) => f.camelName);
 
   // FK resolvers — one per belongs_to. writeKey = `${relationKey}ExternalId`
   // (Decision 4). refTable is the string 'self' for self-FKs, else the parent
@@ -896,12 +932,15 @@ export function buildIntegrationSurface(patternName, processedFields, belongsTo,
     importPath: rel.importPath,
   }));
 
-  // Projection columns: id + externalId + copy-through + local FK columns +
-  // timestamps. Omits provider/provider_metadata.
+  // Projection columns: id + externalId + ALL copy-through columns + local FK
+  // columns + timestamps. Omits provider/provider_metadata.
+  // Projection keeps excluded fields (#490) — exclusion is write-surface only.
+  // The find VIEW also keeps them (bare passthroughs); diff-soundness holds via
+  // the differ's `key in incoming` guard, not by omitting them from the view.
   const projectionColumns = [
     'id',
     'externalId',
-    ...writeColumns,
+    ...processedFields.map((f) => f.camelName),
     ...belongsTo.map((rel) => rel.camelField),
     ...(hasTimestamps ? ['createdAt', 'updatedAt'] : []),
   ];
@@ -909,20 +948,26 @@ export function buildIntegrationSurface(patternName, processedFields, belongsTo,
   // The integrationConfig object literal the template hand-emits. fkResolvers carry a
   // sentinel so the template can swap `refTable` to either 'self' or the live
   // table identifier.
+  // softDelete: use resolveSoftDeleteBoolean (delete knob takes precedence over
+  // !!hasSoftDelete default; noop/absent both preserve !!hasSoftDelete, spec §Delete).
   const integrationConfig = {
     conflictTarget: ['provider', 'externalId'],
     writeColumns,
     projectionColumns,
     eav: !!eavEnabled,
-    softDelete: !!hasSoftDelete,
+    softDelete: resolveSoftDeleteBoolean(sinkPolicy?.delete, hasSoftDelete),
   };
 
   // TIntegrationWrite fields: externalId:string, copy-through (typed, nullable-aware),
   // one `<writeKey>?: string | null` per FK, fields?: Record<string, unknown>.
-  const writeFields = processedFields.map((f) => ({
-    camelName: f.camelName,
-    tsType: f.nullable ? `${f.tsType} | null` : f.tsType,
-  }));
+  // Excluded fields (#490) are dropped from writeFields too — same exclusion set
+  // as writeColumns. The projection keeps them (projectionFields below).
+  const writeFields = processedFields
+    .filter((f) => !excludeSet.has(f.name))
+    .map((f) => ({
+      camelName: f.camelName,
+      tsType: f.nullable ? `${f.tsType} | null` : f.tsType,
+    }));
   const writeFkFields = fkResolvers.map((fk) => ({
     name: fk.writeKey,
     tsType: 'string | null',
@@ -1336,6 +1381,9 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
   }));
 
   // Integration write-surface derivation (#374) — null unless pattern: Integrated.
+  // Pass sinkPolicy (#490) so the delete knob and exclude_fields knob are applied
+  // at this derivation (repo config) as well as buildSinkInput (sink derivation).
+  const sinkPolicy = definition.integration?.sink ?? null;
   const integrationSurface = buildIntegrationSurface(
     patternName,
     nonFkFields,
@@ -1344,6 +1392,7 @@ export function buildCleanLitePsLocals(definition, baseLocals) {
     eavEnabled,
     hasSoftDelete,
     fields,
+    sinkPolicy,
   );
 
   // EVT-7: emits locals flow through from baseLocals (prompt.js computed them

package/templates/subsystem/jobs-config/codegen-config-jobs-block.ejs.t

@@ -30,6 +30,17 @@ jobs:
       #                            # are simply never received and the worker
       #                            # degrades to polling.
       poll_interval_ms: 1000       # interval-poll heartbeat (the wake fallback)
+      # ── Claim lease / heartbeat (CLAIM-HB-1) ──
+      # A live worker renews `claimed_at` for its in-flight runs every
+      # `claim_heartbeat_interval_ms`, so a legitimately long-running handler is
+      # NEVER swept; only a row whose worker died ages past
+      # `stale_threshold_ms` and is reset to `pending` by the sweeper. Raise the
+      # threshold only if you expect worker-crash recovery to wait longer; the
+      # heartbeat (not the threshold) is what protects long handlers.
+      # stale_threshold_ms: 300000          # dead-worker recovery window (5 min)
+      # stale_sweeper_interval_ms: 60000    # how often the sweeper scans
+      # claim_heartbeat_interval_ms: 100000 # lease renewal cadence
+      #                                     # (default = stale_threshold_ms / 3)
     # bullmq:                      # Example shape for Phase 6+ BullMQ backend.
     #   bull_board:                # Mount Bull Board admin UI.
     #     enabled: true

package/dist/chunk-6DQEIXYU.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../runtime/subsystems/jobs/jobs-domain.module.ts"],"sourcesContent":["/**\n * JobsDomainModule — `DynamicModule.forRoot({ backend })` factory wiring\n * the three jobs-domain protocol tokens to a backend implementation\n * (ADR-022, JOB-5).\n *\n * Mirrors `EventsModule.forRoot()` exactly:\n *   - `global: true` so consumer entity modules don't have to import this\n *     individually — `JOB_ORCHESTRATOR` / `JOB_RUN_SERVICE` /\n *     `JOB_STEP_SERVICE` are available project-wide.\n *   - One backend at a time (Drizzle for production, Memory for tests).\n *\n * Backend swappability follows the core/extension protocol from CLAUDE.md:\n * the three tokens are the **core contract**; backend-specific tunables\n * live under `extensions.<backend>` so opting into a feature is explicit\n * and the type system reserves the slot.\n */\nimport { Module, type DynamicModule, type Provider } from '@nestjs/common';\nimport { DRIZZLE } from '../../constants/tokens';\nimport {\n  JOB_ORCHESTRATOR,\n  JOB_RUN_SERVICE,\n  JOB_STEP_SERVICE,\n  JOBS_MULTI_TENANT,\n  JOBS_LISTEN_NOTIFY,\n} from './jobs-domain.tokens';\nimport { DrizzleJobOrchestrator } from './job-orchestrator.drizzle-backend';\nimport { DrizzleJobRunService } from './job-run-service.drizzle-backend';\nimport { DrizzleJobStepService } from './job-step-service.drizzle-backend';\n// #6 — `BullMQJobOrchestrator` is lazy-loaded only when `backend: 'bullmq'`\n// is selected. The backend file is filtered out of drizzle/memory installs\n// (see `backendFileFilter`); a non-literal dynamic import below sidesteps\n// consumer-side tsc resolution of an absent file.\nimport { MemoryJobOrchestrator } from './job-orchestrator.memory-backend';\nimport { MemoryJobRunService } from './job-run-service.memory-backend';\nimport { MemoryJobStepService } from './job-step-service.memory-backend';\nimport { MemoryJobStore } from './memory-job-store';\nimport {\n  BULLMQ_CONNECTION,\n  BULLMQ_RESOLVED_CONFIG,\n  resolveBullMqConfig,\n  type BullMqExtensionsConfig,\n} from './bullmq.config';\n\n/**\n * Drizzle backend extensions surface (LISTEN-NOTIFY-1 wires both fields).\n *\n * - `listenNotify` → provided as `JOBS_LISTEN_NOTIFY` so the orchestrator emits\n *   in-tx `pg_notify` on enqueue, and threaded into each spawned `JobWorker`\n *   (which holds the listener connection). Off by default.\n * - `pollIntervalMs` → threaded into the spawned `JobWorker`'s\n *   `JobWorkerOptions.pollIntervalMs` (the worker already honored this; it just\n *   never received a config value). Default 1000.\n *\n * Both run ALONGSIDE interval polling — `listenNotify` only adds an early wake;\n * polling remains the durability heartbeat.\n */\nexport interface DrizzleBackendExtensions {\n  /** Use Postgres LISTEN/NOTIFY to wake the polling loop. Default false. */\n  listenNotify?: boolean;\n  /** Polling interval (ms). Default 1000. */\n  pollIntervalMs?: number;\n}\n\nexport interface JobsDomainModuleOptions {\n  backend: 'drizzle' | 'memory' | 'bullmq';\n  /**\n   * Backend-specific extensions. Only the matching backend's extensions\n   * are read at boot; non-matching keys are ignored. This is the\n   * core/extension protocol surface — see CLAUDE.md.\n   */\n  extensions?: {\n    drizzle?: DrizzleBackendExtensions;\n    /**\n     * BullMQ backend extensions (BULLMQ-1). Snake_case mirrors the YAML\n     * under `jobs.extensions.bullmq`. `redis_url` falls back to\n     * `process.env.REDIS_URL` then `redis://localhost:6379`.\n     */\n    bullmq?: BullMqExtensionsConfig;\n  };\n  /** Multi-tenancy opt-in. Wired by JOB-8; module signature stays stable. */\n  multiTenant?: boolean;\n}\n\n@Module({})\nexport class JobsDomainModule {\n  static forRoot(opts: JobsDomainModuleOptions): DynamicModule {\n    const multiTenant = opts.multiTenant ?? false;\n    // LISTEN-NOTIFY-1 — drizzle-only extension. `listen_notify` is meaningless\n    // for memory (no DB) and redundant for bullmq (native wakeups); only the\n    // drizzle backend's orchestrator reads it.\n    const listenNotify =\n      opts.backend === 'drizzle' && Boolean(opts.extensions?.drizzle?.listenNotify);\n\n    const providers: Provider[] = [\n      // JOB-8 — boolean provider consumed by the four service-layer backends.\n      // Always provided (even when `multiTenant === false`) so `@Inject`\n      // always resolves; backends short-circuit the enforcement path when\n      // the value is `false`. See `jobs-domain.tokens.ts` for the claim-loop\n      // cross-tenant-by-design decision.\n      { provide: JOBS_MULTI_TENANT, useValue: multiTenant },\n      // LISTEN-NOTIFY-1 — always provided so the orchestrator's `@Inject`\n      // resolves; the orchestrator skips the `pg_notify` emit when `false`.\n      { provide: JOBS_LISTEN_NOTIFY, useValue: listenNotify },\n    ];\n\n    if (opts.backend === 'memory') {\n      // The store is a plain class — wired as a singleton `useValue` so\n      // unit tests can pull it out via `.get(MemoryJobStore)` for direct\n      // assertions (matches the access pattern in JOB-4 specs).\n      const store = new MemoryJobStore();\n      providers.push({ provide: MemoryJobStore, useValue: store });\n      providers.push(MemoryJobStepService);\n      providers.push({ provide: JOB_STEP_SERVICE, useExisting: MemoryJobStepService });\n      providers.push(MemoryJobOrchestrator);\n      providers.push({ provide: JOB_ORCHESTRATOR, useExisting: MemoryJobOrchestrator });\n      providers.push(MemoryJobRunService);\n      providers.push({ provide: JOB_RUN_SERVICE, useExisting: MemoryJobRunService });\n    } else if (opts.backend === 'bullmq') {\n      // BULLMQ-1 — BullMQ orchestrator over a Postgres source of truth. The\n      // run/step services stay Drizzle (domain reads + `listForScope` are\n      // Postgres queries, unchanged per spec). Only the orchestrator's\n      // claim/dispatch half swaps to BullMQ.\n      //\n      // #6 — the bullmq backend module is filtered out of drizzle/memory\n      // installs (no `bullmq` peer dep, no consumer-side tsc compile of an\n      // unused file). The factory below dynamic-imports it via a non-literal\n      // specifier so TS treats the module type as `any` and never tries to\n      // resolve the absent file on a drizzle/memory consumer.\n      const resolved = resolveBullMqConfig(opts.extensions?.bullmq);\n      providers.push({ provide: BULLMQ_CONNECTION, useValue: resolved.connection });\n      providers.push({ provide: BULLMQ_RESOLVED_CONFIG, useValue: resolved });\n      providers.push({\n        provide: JOB_ORCHESTRATOR,\n        useFactory: async (...args: unknown[]): Promise<object> => {\n          const specifier = './job-orchestrator.bullmq-backend';\n          const mod = (await import(specifier)) as {\n            BullMQJobOrchestrator: new (...args: unknown[]) => object;\n          };\n          return new mod.BullMQJobOrchestrator(...args);\n        },\n        // The bullmq orchestrator constructor mirrors DrizzleJobOrchestrator's\n        // injection list: DRIZZLE + JOBS_MULTI_TENANT + the resolved BullMQ\n        // tokens. Importing token references would force a static dep on the\n        // tokens file in this module's import graph; using the existing\n        // symbols already in scope is sufficient.\n        inject: [DRIZZLE, JOBS_MULTI_TENANT, BULLMQ_CONNECTION, BULLMQ_RESOLVED_CONFIG],\n      });\n      providers.push({ provide: JOB_RUN_SERVICE, useClass: DrizzleJobRunService });\n      providers.push({ provide: JOB_STEP_SERVICE, useClass: DrizzleJobStepService });\n    } else {\n      providers.push({ provide: JOB_ORCHESTRATOR, useClass: DrizzleJobOrchestrator });\n      providers.push({ provide: JOB_RUN_SERVICE, useClass: DrizzleJobRunService });\n      providers.push({ provide: JOB_STEP_SERVICE, useClass: DrizzleJobStepService });\n    }\n\n    const exports = [\n      JOB_ORCHESTRATOR,\n      JOB_RUN_SERVICE,\n      JOB_STEP_SERVICE,\n      JOBS_MULTI_TENANT,\n      JOBS_LISTEN_NOTIFY,\n    ];\n    // BULLMQ-1 — only export the BullMQ tokens when they were actually\n    // provided. Nest throws \"exported but not provided\" otherwise. Exported so\n    // JobWorkerModule (which imports this module) can read the resolved\n    // connection/config to spawn BullMQ workers.\n    if (opts.backend === 'bullmq') {\n      exports.push(BULLMQ_CONNECTION, BULLMQ_RESOLVED_CONFIG);\n    }\n\n    return {\n      module: JobsDomainModule,\n      global: true,\n      providers,\n      exports,\n    };\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgBA,SAAS,cAAiD;AAoEnD,IAAM,mBAAN,MAAuB;AAAA,EAC5B,OAAO,QAAQ,MAA8C;AAC3D,UAAM,cAAc,KAAK,eAAe;AAIxC,UAAM,eACJ,KAAK,YAAY,aAAa,QAAQ,KAAK,YAAY,SAAS,YAAY;AAE9E,UAAM,YAAwB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAM5B,EAAE,SAAS,mBAAmB,UAAU,YAAY;AAAA;AAAA;AAAA,MAGpD,EAAE,SAAS,oBAAoB,UAAU,aAAa;AAAA,IACxD;AAEA,QAAI,KAAK,YAAY,UAAU;AAI7B,YAAM,QAAQ,IAAI,eAAe;AACjC,gBAAU,KAAK,EAAE,SAAS,gBAAgB,UAAU,MAAM,CAAC;AAC3D,gBAAU,KAAK,oBAAoB;AACnC,gBAAU,KAAK,EAAE,SAAS,kBAAkB,aAAa,qBAAqB,CAAC;AAC/E,gBAAU,KAAK,qBAAqB;AACpC,gBAAU,KAAK,EAAE,SAAS,kBAAkB,aAAa,sBAAsB,CAAC;AAChF,gBAAU,KAAK,mBAAmB;AAClC,gBAAU,KAAK,EAAE,SAAS,iBAAiB,aAAa,oBAAoB,CAAC;AAAA,IAC/E,WAAW,KAAK,YAAY,UAAU;AAWpC,YAAM,WAAW,oBAAoB,KAAK,YAAY,MAAM;AAC5D,gBAAU,KAAK,EAAE,SAAS,mBAAmB,UAAU,SAAS,WAAW,CAAC;AAC5E,gBAAU,KAAK,EAAE,SAAS,wBAAwB,UAAU,SAAS,CAAC;AACtE,gBAAU,KAAK;AAAA,QACb,SAAS;AAAA,QACT,YAAY,UAAU,SAAqC;AACzD,gBAAM,YAAY;AAClB,gBAAM,MAAO,MAAM,OAAO;AAG1B,iBAAO,IAAI,IAAI,sBAAsB,GAAG,IAAI;AAAA,QAC9C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAMA,QAAQ,CAAC,SAAS,mBAAmB,mBAAmB,sBAAsB;AAAA,MAChF,CAAC;AACD,gBAAU,KAAK,EAAE,SAAS,iBAAiB,UAAU,qBAAqB,CAAC;AAC3E,gBAAU,KAAK,EAAE,SAAS,kBAAkB,UAAU,sBAAsB,CAAC;AAAA,IAC/E,OAAO;AACL,gBAAU,KAAK,EAAE,SAAS,kBAAkB,UAAU,uBAAuB,CAAC;AAC9E,gBAAU,KAAK,EAAE,SAAS,iBAAiB,UAAU,qBAAqB,CAAC;AAC3E,gBAAU,KAAK,EAAE,SAAS,kBAAkB,UAAU,sBAAsB,CAAC;AAAA,IAC/E;AAEA,UAAM,UAAU;AAAA,MACd;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAKA,QAAI,KAAK,YAAY,UAAU;AAC7B,cAAQ,KAAK,mBAAmB,sBAAsB;AAAA,IACxD;AAEA,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;AA7Fa,mBAAN;AAAA,EADN,OAAO,CAAC,CAAC;AAAA,GACG;","names":[]}