@pattern-stack/codegen 0.17.0 → 0.17.1

package/dist/src/index.js

@@ -46,25 +46,25 @@ import {
   validatePatternProject
 } from "../chunk-IOQMMH6C.js";
 import "../chunk-KVOWSC5S.js";
-import "../chunk-P3AYBRP6.js";
+import "../chunk-JA7GJDNI.js";
 import "../chunk-PRWIX6UW.js";
-import "../chunk-SR7F3TJY.js";
+import "../chunk-AHV4GDYM.js";
+import "../chunk-YK5JEVLX.js";
 import "../chunk-EO2QPOKH.js";
 import "../chunk-SQDOBLBP.js";
-import "../chunk-OGIZXGPY.js";
+import "../chunk-4KNXX6TI.js";
+import "../chunk-3CJFPU6Q.js";
+import "../chunk-TDEHU73T.js";
 import "../chunk-LG57S2SC.js";
-import "../chunk-DCCZB4UC.js";
+import "../chunk-XWBK3XJK.js";
+import "../chunk-S7C6TIIF.js";
 import "../chunk-MZ6GV4YF.js";
 import "../chunk-HNWZFNKP.js";
-import "../chunk-AHV4GDYM.js";
 import "../chunk-43SBT72G.js";
 import "../chunk-4MF3HKJA.js";
 import "../chunk-TIZXQU26.js";
-import "../chunk-36U5UGIO.js";
+import "../chunk-JEINYUJH.js";
 import "../chunk-5TK7MEN4.js";
-import "../chunk-4KNXX6TI.js";
-import "../chunk-3CJFPU6Q.js";
-import "../chunk-S7C6TIIF.js";
 import "../chunk-U64T4YZE.js";
 import "../chunk-2E224ZSN.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",

package/runtime/subsystems/integration/deep-equal.differ.ts

@@ -12,7 +12,11 @@
  *      `id`, `createdAt`, `updatedAt`, `deletedAt`, `type`,
  *      `lastModifiedAt`, `fields`, `providerMetadata`
  *    (`fields` is the EAV bag — it's diffed by the sink's EAV dual-write
- *    path, not at the canonical-record layer.)
+ *    path, not at the canonical-record layer.) Consumers augment the list via
+ *    `options.ignore` and — when a default is domain data for their entity —
+ *    REMOVE a default via `options.unignore` (e.g. an entity whose
+ *    `deletedAt` is a vendor-observed retraction tombstone, not row metadata;
+ *    see `DeepEqualDifferOptions.unignore`).
  *
  * 2. **`providerChangedFields` hint (CDC)** — when present, restricts the
  *    comparison to the hinted field set. The hint is advisory; fields in
@@ -75,6 +79,26 @@ export interface DeepEqualDifferOptions {
    * merged (not replaced) with `DEFAULT_IGNORE_FIELDS`.
    */
   readonly ignore?: readonly string[];
+
+  /**
+   * Field names to REMOVE from the default ignore list — the inverse of
+   * `ignore`. Use this to declare that a normally-metadata column is in fact
+   * DOMAIN DATA for this entity and must register as a field change.
+   *
+   * The canonical case (swe-brain ADR-0008 §1, the gap this knob closes):
+   * `deletedAt` is in `DEFAULT_IGNORE_FIELDS` because most sinks stamp it as
+   * row metadata sinks own unconditionally. But an entity with
+   * `softDelete: false` and a domain-owned `deleted_at` carries the
+   * vendor-observed retraction tombstone ON the canonical record (a Slack
+   * `message_deleted` → `deletedAt`). Without un-ignoring it, the tombstone
+   * overlay diffs to `'noop'`, the upsert is skipped, and `deleted_at` never
+   * lands. `unignore: ['deletedAt']` makes the differ treat it as domain data.
+   *
+   * Applied AFTER `ignore` is merged, so `unignore` wins on a field listed in
+   * both. Subtracting a field not in the (merged) ignore set is a harmless
+   * no-op. Does not touch `DEFAULT_IGNORE_FIELDS` for any other instance.
+   */
+  readonly unignore?: readonly string[];
 }
 
 @Injectable()
@@ -84,11 +108,16 @@ export class DeepEqualDiffer<T extends Record<string, unknown>>
   private readonly ignore: ReadonlySet<string>;
 
   constructor(opts: DeepEqualDifferOptions = {}) {
-    if (opts.ignore && opts.ignore.length > 0) {
-      this.ignore = new Set([...DEFAULT_IGNORE_FIELDS, ...opts.ignore]);
-    } else {
-      this.ignore = DEFAULT_IGNORE_FIELDS;
+    const merged = new Set<string>(DEFAULT_IGNORE_FIELDS);
+    if (opts.ignore) {
+      for (const field of opts.ignore) merged.add(field);
+    }
+    // `unignore` is subtracted last so it wins over a field that also appears
+    // in `ignore` or the defaults — "this column is domain data here."
+    if (opts.unignore) {
+      for (const field of opts.unignore) merged.delete(field);
     }
+    this.ignore = merged;
   }
 
   diff(

package/runtime/subsystems/integration/integration.module.ts

@@ -73,7 +73,7 @@ import { MemoryCursorStore } from './integration-cursor-store.memory-backend';
 import { MemoryRunRecorder } from './integration-run-recorder.memory-backend';
 import { PostgresCursorStore } from './integration-cursor-store.drizzle-backend';
 import { DrizzleIntegrationRunRecorder } from './integration-run-recorder.drizzle-backend';
-import { DeepEqualDiffer } from './deep-equal.differ';
+import { DeepEqualDiffer, type DeepEqualDifferOptions } from './deep-equal.differ';
 
 export interface IntegrationModuleOptions {
   /**
@@ -100,6 +100,24 @@ export interface IntegrationModuleOptions {
    * Defaults to `false`.
    */
   multiTenant?: boolean;
+
+  /**
+   * Default-differ configuration (DIFFER-UNIGNORE, 0.17.1). Threaded into the
+   * `DeepEqualDiffer` bound to `INTEGRATION_FIELD_DIFFER`. Omit for the
+   * historical behaviour (the default ignore list, unchanged).
+   *
+   * Mirrors `DeepEqualDifferOptions`:
+   *   - `ignore`   — extra field names to ignore (merged with the defaults).
+   *   - `unignore` — default-ignored field names to RE-include as domain data
+   *     (e.g. `['deletedAt']` for an entity whose `deletedAt` is a
+   *     vendor-observed retraction tombstone, not row metadata — swe-brain
+   *     ADR-0008 §1). Subtracted after the merge, so it wins.
+   *
+   * A feature module that binds its own `IFieldDiffer<T>` to
+   * `INTEGRATION_FIELD_DIFFER` overrides this entirely (per-entity escape hatch
+   * unchanged).
+   */
+  differ?: DeepEqualDifferOptions;
 }
 
 @Module({})
@@ -112,7 +130,13 @@ export class IntegrationModule {
       { provide: INTEGRATION_MULTI_TENANT, useValue: multiTenant },
       // Default differ — consumers can override by binding a different
       // `IFieldDiffer<T>` to `INTEGRATION_FIELD_DIFFER` in their feature module.
-      { provide: INTEGRATION_FIELD_DIFFER, useValue: new DeepEqualDiffer() },
+      // DIFFER-UNIGNORE: `options.differ` (ignore/unignore) is threaded here so
+      // a consumer can declare a default-ignored column (e.g. `deletedAt`) as
+      // domain data for their entities without binding a bespoke differ.
+      {
+        provide: INTEGRATION_FIELD_DIFFER,
+        useValue: new DeepEqualDiffer(options.differ ?? {}),
+      },
     ];
 
     const backendProviders: Provider[] =

package/runtime/subsystems/jobs/job-handler.base.ts

@@ -42,13 +42,33 @@ export interface RetryPolicy {
   nonRetryableErrors?: string[];
 }
 
+/**
+ * Concurrency lane key (JOB-FN-KEY, 0.16.2).
+ *
+ * Two authoring forms, both honored end-to-end (the typed function form was
+ * previously dropped to `null` at registration — see `upsertJobRows` — so
+ * `collisionMode` silently never engaged):
+ *
+ *   - **`string`** — a `{{field}}` template evaluated against the start
+ *     payload by `evaluateKeyTemplate` (single-key substitution, no dotted
+ *     paths). Persisted verbatim to `job.concurrency_key_template`.
+ *   - **`(input) => string`** — an arbitrary function of the input. Persisted
+ *     as the `FN_KEY_SENTINEL` marker so the definition-hash gate stays stable
+ *     and the collision path engages; `start()` re-resolves the live function
+ *     from `JOB_HANDLER_REGISTRY` and evaluates it against the payload.
+ *
+ * Both forms produce a per-lane key; same key + in-flight incumbent ⇒
+ * `collisionMode` ('queue' | 'reject' | 'replace') decides.
+ */
+export type JobKeySelector<TInput> = string | ((input: TInput) => string);
+
 export interface ConcurrencyPolicy<TInput> {
-  key: (input: TInput) => string;
+  key: JobKeySelector<TInput>;
   collisionMode: 'queue' | 'reject' | 'replace';
 }
 
 export interface DedupePolicy<TInput> {
-  key: (input: TInput) => string;
+  key: JobKeySelector<TInput>;
   windowMs: number;
 }
 
@@ -245,3 +265,96 @@ export namespace HandlerRegistry {
     return JOB_HANDLER_REGISTRY.get(type);
   }
 }
+
+// ─── Key resolution (JOB-FN-KEY, 0.16.2) ────────────────────────────────────
+
+/**
+ * Sentinel persisted to `job.concurrency_key_template` / `dedupe_key_template`
+ * when the authored `key` is a function rather than a `{{field}}` template.
+ *
+ * Why a sentinel (not `null`): the collision/dedupe paths in both backends gate
+ * on `definition.concurrencyKeyTemplate != null`. A function key persisted as
+ * `null` (the pre-0.16.2 bug) left those columns empty, so `collisionMode` /
+ * the dedupe window never engaged — the job ran with NO key. A stable sentinel
+ * keeps the column non-null (path engages) AND keeps the definition-hash gate
+ * (`upsertJobRows`' `IS DISTINCT FROM` clause) stable across boots, since the
+ * function identity itself can't be hashed. `start()` detects the sentinel and
+ * re-resolves the live function from `JOB_HANDLER_REGISTRY`.
+ *
+ * Chosen as an angle-bracketed token so it can never collide with a real
+ * `{{field}}` template (which never contains a literal `<`).
+ */
+export const FN_KEY_SENTINEL = '<fn>';
+
+/**
+ * Registration-time projection: collapse an authored `JobKeySelector` to the
+ * string stored in the `job` definition row. A string template is stored
+ * verbatim; a function is stored as `FN_KEY_SENTINEL`; absence stays `null`.
+ */
+export function keySelectorToTemplate(
+  key: JobKeySelector<unknown> | undefined,
+): string | null {
+  if (typeof key === 'string') return key;
+  if (typeof key === 'function') return FN_KEY_SENTINEL;
+  return null;
+}
+
+/** Which meta policy a key belongs to — selects the live fn at `start()`. */
+export type KeyKind = 'concurrency' | 'dedupe';
+
+/**
+ * `start()`-time resolution shared by every backend. Turns the persisted
+ * template column into the concrete per-run key for the given payload.
+ *
+ *   - `template == null` → `null` (no key; caller skips the collision/dedupe path).
+ *   - `template === FN_KEY_SENTINEL` → look the live `@JobHandler` meta up in
+ *     `JOB_HANDLER_REGISTRY`, pull `meta[kind].key`, and invoke it against the
+ *     payload. The registry is the runtime source of truth (the worker already
+ *     resolves handler classes the same way), so the function survives the DB
+ *     round-trip even though it can't be persisted.
+ *   - otherwise → a `{{field}}` template, evaluated via the injected
+ *     `evaluateTemplate` (each backend passes its own copy to avoid a runtime
+ *     import cycle).
+ *
+ * Throws `JobKeyFunctionUnavailableError` if the sentinel is present but no
+ * live function can be found (e.g. the registry was reset, or a function key
+ * was persisted by a newer build and read by an older one). Failing loud beats
+ * silently degrading to no-key — the exact regression this fix exists to kill.
+ */
+export function resolveJobKey(
+  kind: KeyKind,
+  type: string,
+  template: string | null,
+  payload: Record<string, unknown>,
+  evaluateTemplate: (template: string, payload: Record<string, unknown>) => string,
+): string | null {
+  if (template == null) return null;
+  if (template !== FN_KEY_SENTINEL) return evaluateTemplate(template, payload);
+
+  const meta = JOB_HANDLER_REGISTRY.get(type)?.meta;
+  const key = (meta?.[kind] as { key?: unknown } | undefined)?.key;
+  if (typeof key !== 'function') {
+    throw new JobKeyFunctionUnavailableError(type, kind);
+  }
+  return (key as (input: unknown) => string)(payload);
+}
+
+/**
+ * Raised when a `${FN_KEY_SENTINEL}` template is read but the live function
+ * key is missing from `JOB_HANDLER_REGISTRY`. Kept here (not in `jobs-errors`)
+ * so `job-handler.base` stays import-cycle-free.
+ */
+export class JobKeyFunctionUnavailableError extends Error {
+  constructor(
+    readonly jobType: string,
+    readonly kind: KeyKind,
+  ) {
+    super(
+      `[jobs] ${kind} key for job '${jobType}' was persisted as a function ` +
+        `sentinel ('${FN_KEY_SENTINEL}') but no live function is registered ` +
+        `for it. The @JobHandler must be imported before start() so its meta ` +
+        `is in JOB_HANDLER_REGISTRY.`,
+    );
+    this.name = 'JobKeyFunctionUnavailableError';
+  }
+}

package/runtime/subsystems/jobs/job-orchestrator.drizzle-backend.ts

@@ -36,6 +36,11 @@ import {
 import { jobSteps } from './job-orchestration.schema';
 import { JOBS_MULTI_TENANT, JOBS_LISTEN_NOTIFY } from './jobs-domain.tokens';
 import { JOBS_WAKE_CHANNEL, pgNotify } from './pg-notify';
+import {
+  keySelectorToTemplate,
+  resolveJobKey,
+  type JobKeySelector,
+} from './job-handler.base';
 
 /**
  * Terminal statuses — transitions into these are final. Used by `cancel`
@@ -140,9 +145,17 @@ export class DrizzleJobOrchestrator implements IJobOrchestrator {
     if (!def) throw new JobTypeNotFoundError(type);
     const definition = def as JobDefinitionRow;
 
-    // 1b. Dedupe check.
+    // 1b. Dedupe check. JOB-FN-KEY: `resolveJobKey` honors both the `{{field}}`
+    // template AND a function key persisted as `FN_KEY_SENTINEL` (re-resolved
+    // live from JOB_HANDLER_REGISTRY).
     if (definition.dedupeKeyTemplate && definition.dedupeWindowMs) {
-      const dedupeKey = evaluateKeyTemplate(definition.dedupeKeyTemplate, payload);
+      const dedupeKey = resolveJobKey(
+        'dedupe',
+        type,
+        definition.dedupeKeyTemplate,
+        payload,
+        evaluateKeyTemplate,
+      ) as string;
       const windowStart = new Date(Date.now() - definition.dedupeWindowMs);
       const existing = await client
         .select()
@@ -166,10 +179,15 @@ export class DrizzleJobOrchestrator implements IJobOrchestrator {
     // 1c. Concurrency collision check.
     let concurrencyKey: string | null = null;
     if (definition.concurrencyKeyTemplate) {
-      concurrencyKey = evaluateKeyTemplate(
+      // Non-null cast: the branch guard proves the template is present, so the
+      // resolver never returns null here (it only nulls on a null template).
+      concurrencyKey = resolveJobKey(
+        'concurrency',
+        type,
         definition.concurrencyKeyTemplate,
         payload,
-      );
+        evaluateKeyTemplate,
+      ) as string;
       const inFlight = await client
         .select()
         .from(jobRuns)
@@ -223,10 +241,13 @@ export class DrizzleJobOrchestrator implements IJobOrchestrator {
       rootRunId = parent.rootRunId;
     }
 
-    const dedupeKey =
-      definition.dedupeKeyTemplate
-        ? evaluateKeyTemplate(definition.dedupeKeyTemplate, payload)
-        : null;
+    const dedupeKey = resolveJobKey(
+      'dedupe',
+      type,
+      definition.dedupeKeyTemplate,
+      payload,
+      evaluateKeyTemplate,
+    );
 
     const [inserted] = await client
       .insert(jobRuns)
@@ -460,17 +481,23 @@ export class DrizzleJobOrchestrator implements IJobOrchestrator {
         backoff: 'fixed' as const,
         baseMs: 0,
       };
-      const concurrencyKeyTemplate =
-        (meta.concurrency as { key?: unknown } | undefined)?.key;
-      const concurrencyKeyTemplateStr =
-        typeof concurrencyKeyTemplate === 'string' ? concurrencyKeyTemplate : null;
+      // JOB-FN-KEY (0.16.2): both authored key forms are honored. A `{{field}}`
+      // string is persisted verbatim; a function is persisted as
+      // `FN_KEY_SENTINEL` (non-null so the collision/dedupe path engages, and
+      // hash-stable so the definition-hash gate doesn't churn on every boot —
+      // the function identity can't be hashed). `start()` re-resolves the live
+      // function from `JOB_HANDLER_REGISTRY`. The pre-0.16.2 `typeof === string
+      // ? … : null` dropped function keys to null, so `collisionMode` silently
+      // never engaged.
+      const concurrencyKeyTemplateStr = keySelectorToTemplate(
+        meta.concurrency?.key as JobKeySelector<unknown> | undefined,
+      );
       const collisionMode =
         (meta.concurrency?.collisionMode as JobDefinitionRow['collisionMode']) ??
         'queue';
-      const dedupeKeyTemplate =
-        (meta.dedupe as { key?: unknown } | undefined)?.key;
-      const dedupeKeyTemplateStr =
-        typeof dedupeKeyTemplate === 'string' ? dedupeKeyTemplate : null;
+      const dedupeKeyTemplateStr = keySelectorToTemplate(
+        meta.dedupe?.key as JobKeySelector<unknown> | undefined,
+      );
       const dedupeWindowMs = meta.dedupe?.windowMs ?? null;
       const timeoutMs = meta.timeoutMs ?? null;
       const replayFrom = meta.replayFrom ?? 'last_checkpoint';

package/runtime/subsystems/jobs/job-orchestrator.memory-backend.ts

@@ -32,11 +32,17 @@ import type {
   JobContext,
   JobHandlerBase,
   JobHandlerMeta,
+  JobKeySelector,
   RetryPolicy,
   SpawnChildOptions,
   StepOptions,
 } from './job-handler.base';
-import { ParentClosePolicy } from './job-handler.base';
+import {
+  ParentClosePolicy,
+  keySelectorToTemplate,
+  FN_KEY_SENTINEL,
+  JobKeyFunctionUnavailableError,
+} from './job-handler.base';
 import {
   JobCollisionError,
   JobNotReplayableError,
@@ -176,10 +182,9 @@ export class MemoryJobOrchestrator implements IJobOrchestrator {
     meta: JobHandlerMeta<TInput>,
     handlerClass: new (...args: unknown[]) => JobHandlerBase<TInput>,
   ): void {
-    const concurrencyKeyTemplate =
-      (meta.concurrency as { key?: string } | undefined)?.key ?? null;
-    const dedupeKeyTemplate =
-      (meta.dedupe as { key?: string } | undefined)?.key ?? null;
+    // JOB-FN-KEY (0.16.2): mirror the Drizzle backend — collapse a function
+    // key to `FN_KEY_SENTINEL` so the def row stays non-null (collision/dedupe
+    // path engages); `start()` re-resolves the live fn from `handlerRegistry`.
     const dedupeWindowMs = meta.dedupe?.windowMs ?? null;
     const now = new Date();
 
@@ -194,13 +199,15 @@ export class MemoryJobOrchestrator implements IJobOrchestrator {
         baseMs: 0,
       },
       timeoutMs: meta.timeoutMs ?? null,
-      concurrencyKeyTemplate:
-        typeof concurrencyKeyTemplate === 'string' ? concurrencyKeyTemplate : null,
+      concurrencyKeyTemplate: keySelectorToTemplate(
+        meta.concurrency?.key as JobKeySelector<unknown> | undefined,
+      ),
       collisionMode:
         (meta.concurrency?.collisionMode as JobDefinitionRow['collisionMode']) ??
         'queue',
-      dedupeKeyTemplate:
-        typeof dedupeKeyTemplate === 'string' ? dedupeKeyTemplate : null,
+      dedupeKeyTemplate: keySelectorToTemplate(
+        meta.dedupe?.key as JobKeySelector<unknown> | undefined,
+      ),
       dedupeWindowMs,
       priorityDefault: 0,
       replayFrom: meta.replayFrom ?? 'last_checkpoint',
@@ -223,6 +230,34 @@ export class MemoryJobOrchestrator implements IJobOrchestrator {
     return this.handlerRegistry.get(type);
   }
 
+  /**
+   * JOB-FN-KEY (0.16.2): resolve a persisted key template against the payload.
+   * Delegates to the shared `resolveJobKey`, but binds the FUNCTION-sentinel
+   * lookup to THIS backend's local `handlerRegistry` (the memory backend keeps
+   * its own meta map seeded by `registerHandler`, distinct from the global
+   * `JOB_HANDLER_REGISTRY` that the Drizzle/worker path uses — memory tests
+   * register handlers directly, never via the `@JobHandler` decorator). The
+   * `evaluateTemplate` callback handles the ordinary `{{field}}` path.
+   */
+  private resolveKey(
+    kind: 'concurrency' | 'dedupe',
+    type: string,
+    template: string | null,
+    payload: Record<string, unknown>,
+  ): string | null {
+    if (template == null) return null;
+    if (template !== FN_KEY_SENTINEL) {
+      return evaluateKeyTemplate(template, payload);
+    }
+    const key = (this.handlerRegistry.get(type)?.meta?.[kind] as
+      | { key?: unknown }
+      | undefined)?.key;
+    if (typeof key !== 'function') {
+      throw new JobKeyFunctionUnavailableError(type, kind);
+    }
+    return (key as (input: unknown) => string)(payload);
+  }
+
   /**
    * Boot-time upsert per `IJobOrchestrator.upsertJobRows`. Memory backend
    * just funnels each entry through `registerHandler`. The validator is
@@ -270,11 +305,10 @@ export class MemoryJobOrchestrator implements IJobOrchestrator {
       if (!definition) throw new JobTypeNotFoundError(type);
 
       // 1. Dedupe — return existing non-excluded run within the window.
+      // JOB-FN-KEY: `resolveKey` honors the `{{field}}` template AND a function
+      // key persisted as `FN_KEY_SENTINEL` (re-resolved from `handlerRegistry`).
       if (definition.dedupeKeyTemplate && definition.dedupeWindowMs) {
-        const dedupeKey = evaluateKeyTemplate(
-          definition.dedupeKeyTemplate,
-          payload,
-        );
+        const dedupeKey = this.resolveKey('dedupe', type, definition.dedupeKeyTemplate, payload) as string;
         const windowStart = Date.now() - definition.dedupeWindowMs;
         const existing = this.findDedupeCandidate(type, dedupeKey, windowStart);
         if (existing) return existing;
@@ -284,10 +318,13 @@ export class MemoryJobOrchestrator implements IJobOrchestrator {
       let concurrencyKey: string | null = null;
       let queueBlockedBy: string | null = null;
       if (definition.concurrencyKeyTemplate) {
-        concurrencyKey = evaluateKeyTemplate(
+        // Non-null cast: the branch guard proves the template is present.
+        concurrencyKey = this.resolveKey(
+          'concurrency',
+          type,
           definition.concurrencyKeyTemplate,
           payload,
-        );
+        ) as string;
         const incumbent = this.findInFlightByConcurrencyKey(concurrencyKey);
         if (incumbent) {
           switch (definition.collisionMode) {
@@ -331,9 +368,12 @@ export class MemoryJobOrchestrator implements IJobOrchestrator {
       // 4. Compute dedupe key for the persisted row (separate from dedupe
       //    short-circuit above — we store it even when no prior run matched
       //    so future dedupe checks see it).
-      const dedupeKey = definition.dedupeKeyTemplate
-        ? evaluateKeyTemplate(definition.dedupeKeyTemplate, payload)
-        : null;
+      const dedupeKey = this.resolveKey(
+        'dedupe',
+        type,
+        definition.dedupeKeyTemplate,
+        payload,
+      );
 
       const now = new Date();
       const runAt = queueBlockedBy

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

@@ -27,3 +27,20 @@ integration:
   # Enabling post-install requires a reinstall (`subsystem install integration
   # --force --force-config`) plus an Atlas migration.
   multi_tenant: false
+
+  # ── Default-differ tuning (DIFFER-UNIGNORE) ──
+  # Threaded into the `DeepEqualDiffer` bound to INTEGRATION_FIELD_DIFFER.
+  # Off-by-default — omit the whole `differ:` block for the historical
+  # behaviour (the built-in ignore list, unchanged). A feature module that
+  # binds its own `IFieldDiffer<T>` overrides this entirely.
+  #
+  # differ:
+  #   # Extra field names to ALSO ignore (merged with the defaults).
+  #   ignore: [internalSeq]
+  #   # Default-ignored field names to RE-INCLUDE as domain data. The canonical
+  #   # case: an entity with `softDelete: false` whose `deletedAt` carries a
+  #   # vendor-observed retraction tombstone ON the canonical record. Without
+  #   # this the tombstone overlay diffs to 'noop', the upsert is skipped, and
+  #   # `deleted_at` never lands. `unignore` is subtracted after `ignore`, so it
+  #   # wins on a field listed in both.
+  #   unignore: [deletedAt]

package/dist/chunk-36U5UGIO.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../runtime/subsystems/integration/deep-equal.differ.ts"],"sourcesContent":["/**\n * DeepEqualDiffer — default `IFieldDiffer<T>` for the integration subsystem (SYNC-5).\n *\n * Walks every field of `incoming` against `existing`, emitting a structured\n * per-field diff (`{ from, to }`) for every field whose value changed.\n * Returns `'noop'` when the record is unchanged.\n *\n * Design decisions (extracted from the upstream consumer + HS-9 findings):\n *\n * 1. **Ignore list** — row metadata that sinks/services stamp unconditionally\n *    so upstream cannot reasonably disagree:\n *      `id`, `createdAt`, `updatedAt`, `deletedAt`, `type`,\n *      `lastModifiedAt`, `fields`, `providerMetadata`\n *    (`fields` is the EAV bag — it's diffed by the sink's EAV dual-write\n *    path, not at the canonical-record layer.)\n *\n * 2. **`providerChangedFields` hint (CDC)** — when present, restricts the\n *    comparison to the hinted field set. The hint is advisory; fields in\n *    the ignore list are still filtered out even when hinted. Provider\n *    hints are field-NAME-level; they don't override the ignore rules.\n *\n * 3. **Date → ISO string** — `Date` instances are normalized to\n *    `toISOString()` before comparison. Sinks return `Date` from the DB\n *    driver; adapters typically deliver strings. Direct `===` would\n *    always say \"changed.\"\n *\n * 4. **Decimal-string vs number** — Postgres `numeric` columns return as\n *    strings through Drizzle; adapters deliver numbers. When one side is a\n *    number and the other is a numeric string that parses to the same\n *    number, they're equal. The normalizer does NOT coerce non-numeric\n *    strings, and it preserves zero-vs-null distinction.\n *\n * 5. **null-existing path** — `diff(null, incoming)` produces a full\n *    created-shape diff (`{from: null, to: <value>}` for every non-ignored\n *    field). Orchestrator sees this and records `operation: 'created'`.\n */\nimport { Injectable } from '@nestjs/common';\nimport type {\n  DiffResult,\n  FieldDiff,\n  IFieldDiffer,\n} from './integration-field-diff.protocol';\n\n/**\n * Default ignore list. Keep in integration with consumer canonical-record shapes —\n * adding a row-metadata field here means no integration will ever mark it changed.\n *\n * Includes the columns contributed by the `external_id_tracking` behavior\n * (`external_id`/`externalId`, `provider`, `provider_metadata`/`providerMetadata`).\n * These are integration-tracking metadata, not domain attributes: they ride on the\n * canonical record but must never register as a field change (the external id\n * is the record's identity, not a mutable value). Listed in both snake_case\n * and camelCase so the differ ignores them regardless of the consumer's\n * canonical projection casing.\n */\nconst DEFAULT_IGNORE_FIELDS: ReadonlySet<string> = new Set([\n  'id',\n  'createdAt',\n  'updatedAt',\n  'deletedAt',\n  'type',\n  'lastModifiedAt',\n  'fields',\n  'external_id',\n  'externalId',\n  'provider',\n  'provider_metadata',\n  'providerMetadata',\n]);\n\nexport interface DeepEqualDifferOptions {\n  /**\n   * Extra field names to ignore in addition to the defaults. Consumers can\n   * pass `['integration_version']` etc. to augment the base list; values here are\n   * merged (not replaced) with `DEFAULT_IGNORE_FIELDS`.\n   */\n  readonly ignore?: readonly string[];\n}\n\n@Injectable()\nexport class DeepEqualDiffer<T extends Record<string, unknown>>\n  implements IFieldDiffer<T>\n{\n  private readonly ignore: ReadonlySet<string>;\n\n  constructor(opts: DeepEqualDifferOptions = {}) {\n    if (opts.ignore && opts.ignore.length > 0) {\n      this.ignore = new Set([...DEFAULT_IGNORE_FIELDS, ...opts.ignore]);\n    } else {\n      this.ignore = DEFAULT_IGNORE_FIELDS;\n    }\n  }\n\n  diff(\n    existing: T | null,\n    incoming: T,\n    providerChangedFields?: string[],\n  ): DiffResult {\n    // Created-shape: every non-ignored field becomes `{from: null, to}`.\n    if (existing === null) {\n      const out: FieldDiff = {};\n      for (const key of Object.keys(incoming)) {\n        if (this.ignore.has(key)) continue;\n        const value = (incoming as Record<string, unknown>)[key];\n        // Skip fields that are themselves null/undefined — a created record\n        // doesn't need to declare \"this field is null now\" for every\n        // untouched column.\n        if (value === null || value === undefined) continue;\n        out[key] = { from: null, to: value };\n      }\n      return Object.keys(out).length === 0 ? 'noop' : out;\n    }\n\n    // Field set to compare. `providerChangedFields` narrows to a hint set;\n    // ignored fields are filtered out regardless of hint.\n    const candidates = new Set<string>();\n    if (providerChangedFields && providerChangedFields.length > 0) {\n      for (const key of providerChangedFields) {\n        if (!this.ignore.has(key)) candidates.add(key);\n      }\n    } else {\n      for (const key of Object.keys(incoming)) {\n        if (!this.ignore.has(key)) candidates.add(key);\n      }\n      // Also include keys that exist on existing but not on incoming —\n      // e.g. a field that was cleared. This would otherwise be missed when\n      // incoming carries an undefined column we drop from the iteration.\n      for (const key of Object.keys(existing)) {\n        if (this.ignore.has(key)) continue;\n        if (!(key in (incoming as Record<string, unknown>))) continue;\n        candidates.add(key);\n      }\n    }\n\n    const out: FieldDiff = {};\n    for (const key of candidates) {\n      const before = (existing as Record<string, unknown>)[key];\n      const after = (incoming as Record<string, unknown>)[key];\n      if (!isEqual(before, after)) {\n        out[key] = { from: before ?? null, to: after ?? null };\n      }\n    }\n\n    return Object.keys(out).length === 0 ? 'noop' : out;\n  }\n}\n\n// ─── equality helpers ───────────────────────────────────────────────────────\n\n/**\n * Field-level equality with the canonical-integration normalizations:\n *   - Date → toISOString (adapters deliver strings)\n *   - numeric-string vs number → numeric equality when both parse\n *   - deep equality for plain objects/arrays (single-level is enough for\n *     canonical records; nested records travel as jsonb columns where the\n *     sink already owns the comparison)\n */\nfunction isEqual(a: unknown, b: unknown): boolean {\n  if (a === b) return true;\n\n  const na = normalize(a);\n  const nb = normalize(b);\n  if (na === nb) return true;\n\n  // After normalization: both may still be non-primitive objects.\n  if (\n    typeof na === 'object' &&\n    typeof nb === 'object' &&\n    na !== null &&\n    nb !== null\n  ) {\n    return deepEqualObject(na as Record<string, unknown>, nb as Record<string, unknown>);\n  }\n\n  // Numeric string ↔ number: when one side is a number and the other is a\n  // string that parses to the same finite number.\n  const numericEqual = maybeNumericEqual(na, nb) || maybeNumericEqual(nb, na);\n  return numericEqual;\n}\n\nfunction normalize(value: unknown): unknown {\n  if (value instanceof Date) return value.toISOString();\n  return value;\n}\n\nfunction maybeNumericEqual(a: unknown, b: unknown): boolean {\n  // a is string-shape, b is number — parse a and compare. Only when the\n  // string looks numeric AND the parse round-trips (no silent NaN pass-\n  // through on non-numeric strings).\n  if (typeof a !== 'string' || typeof b !== 'number') return false;\n  if (a.trim() === '') return false;\n  const parsed = Number(a);\n  if (!Number.isFinite(parsed)) return false;\n  return parsed === b;\n}\n\nfunction deepEqualObject(\n  a: Record<string, unknown>,\n  b: Record<string, unknown>,\n): boolean {\n  if (Array.isArray(a) !== Array.isArray(b)) return false;\n  const aKeys = Object.keys(a);\n  const bKeys = Object.keys(b);\n  if (aKeys.length !== bKeys.length) return false;\n  for (const key of aKeys) {\n    if (!(key in b)) return false;\n    if (!isEqual(a[key], b[key])) return false;\n  }\n  return true;\n}\n"],"mappings":"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","names":["out"]}