@pattern-stack/codegen 0.16.1 → 0.17.1

package/dist/src/index.d.ts

@@ -4135,17 +4135,32 @@ declare function isDomainPattern(def: AnyPatternDefinition): def is PatternDefin
 declare function defineOrchestrationPattern(def: OrchestrationPatternDefinition): OrchestrationPatternDefinition;
 
 /**
- * ActivityPattern — replaces `family: activity`.
+ * ActivityPattern — config-driven subject-scoped interaction base.
  *
- * Activity entities represent time-bounded interactions (calls, meetings,
- * emails). The base repository/service expose date-range + opportunity +
- * user-scoped lookups on top of the standard CRUD methods.
+ * Activity entities represent interactions (calls, meetings, emails, messages,
+ * transcripts) that reference a *subject* — the thing the interaction is about.
+ * Which subject is a per-entity fact, not a library constant: a CRM activity is
+ * scoped to an `opportunity`, a swe-brain interaction to a `person` (later
+ * `repo`/`team`, ADR-0006's Salesforce Activities-vs-Records shape). The base
+ * repository/service therefore expose **generic** subject-scoped finders
+ * (`findBySubjectId` / `findRecentBySubjectId`) that read the subject FK column
+ * from the entity's `config:` block, on top of the standard CRUD methods plus
+ * date-range and actor (`user_id`) scoping.
  *
- * Class names, import paths, and inherited-method strings match the
- * legacy `FAMILY_MAP` entry verbatim so PATTERN-5's template swap produces
- * byte-identical output.
+ * The subject FK column resolves from `config: { Activity: { ... } }`:
+ *   - `subjectColumn` — explicit snake_case column, OR
+ *   - `<subject>_id` — derived from the `subject` entity name.
+ * The recency-ordering column is `occurredAt` (snake_case in config), default
+ * `occurred_at`. The base reads these via `this.patternConfig` — the same
+ * ADR-031 §4 hand-off `IntegratedEntityRepository` uses for `integrationConfig`.
+ *
+ * See `docs/specs/ACTIVITY-SUBJECT-1.md`.
  */
-declare const ActivityPattern: PatternDefinition<unknown>;
+declare const ActivityPattern: PatternDefinition<{
+    subject?: string | undefined;
+    subjectColumn?: string | undefined;
+    occurredAt?: string | undefined;
+}>;
 
 /**
  * BasePattern — identity pattern for the `extends` chain.

package/dist/src/index.js

@@ -44,27 +44,27 @@ import {
   validateOrchestrationProject,
   validatePatternComposition,
   validatePatternProject
-} from "../chunk-2WDX6I7T.js";
+} from "../chunk-IOQMMH6C.js";
 import "../chunk-KVOWSC5S.js";
-import "../chunk-24WXSC3C.js";
-import "../chunk-EO2QPOKH.js";
+import "../chunk-JA7GJDNI.js";
 import "../chunk-PRWIX6UW.js";
-import "../chunk-XWBK3XJK.js";
 import "../chunk-AHV4GDYM.js";
 import "../chunk-YK5JEVLX.js";
+import "../chunk-EO2QPOKH.js";
 import "../chunk-SQDOBLBP.js";
-import "../chunk-5TK7MEN4.js";
 import "../chunk-4KNXX6TI.js";
 import "../chunk-3CJFPU6Q.js";
 import "../chunk-TDEHU73T.js";
+import "../chunk-LG57S2SC.js";
+import "../chunk-XWBK3XJK.js";
 import "../chunk-S7C6TIIF.js";
 import "../chunk-MZ6GV4YF.js";
-import "../chunk-LG57S2SC.js";
 import "../chunk-HNWZFNKP.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-U64T4YZE.js";
 import "../chunk-2E224ZSN.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.16.1",
+  "version": "0.17.1",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",
@@ -138,6 +138,7 @@
     "@pattern-stack/codegen-calendar": "workspace:*",
     "@pattern-stack/codegen-crm": "workspace:*",
     "@pattern-stack/codegen-mail": "workspace:*",
+    "@pattern-stack/codegen-messaging": "workspace:*",
     "@pattern-stack/codegen-transcript": "workspace:*",
     "@cubejs-client/core": "^1.0.0",
     "@nestjs/common": "10",

package/runtime/base-classes/activity-entity-repository.ts

@@ -1,26 +1,84 @@
 /**
  * ActivityEntityRepository<TEntity>
  *
- * Family-specific base for activity entities (emails, calls, meetings, notes).
- * Adds date-range queries, user/opportunity scoping, and recency ordering.
+ * Family-specific base for activity / interaction entities (emails, calls,
+ * meetings, messages, transcripts). Adds date-range queries, actor (`user_id`)
+ * scoping, recency ordering, and **config-driven subject scoping** — the
+ * subject FK column is resolved from the concrete repo's `patternConfig`
+ * (ADR-031 §4) rather than hardcoded, so the same base serves a CRM
+ * `opportunity`-scoped activity and a swe-brain `person`-scoped interaction.
  *
- * Concrete repos extend this and declare their table + behaviors.
+ * Concrete repos extend this and declare their table + behaviors, and (when
+ * they use the subject finders) a `patternConfig` carrying `subject` /
+ * `subjectColumn` / `occurredAt`. The template emits that property from the
+ * entity's `config: { Activity: {...} }` block. See ACTIVITY-SUBJECT-1.
  */
 import { eq, between, desc } from 'drizzle-orm';
 import { BaseRepository } from './base-repository';
 
+/**
+ * Per-entity Activity config (matches `ActivityPatternConfigSchema` in
+ * `src/patterns/library/activity.pattern.ts`). Carried on the concrete repo as
+ * `patternConfig` and read here to resolve column names at runtime.
+ */
+export interface ActivityPatternConfig {
+  /** Subject entity name → derives the FK column `<subject>_id`. */
+  subject?: string;
+  /** Explicit snake_case FK column, when it does not follow `<subject>_id`. */
+  subjectColumn?: string;
+  /** snake_case recency-ordering column; defaults to `occurred_at`. */
+  occurredAt?: string;
+}
+
+const toCamel = (snake: string): string =>
+  snake.replace(/_([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+
 export abstract class ActivityEntityRepository<TEntity> extends BaseRepository<TEntity> {
   /**
-   * Find activities within a date range (inclusive).
+   * Per-entity Activity config. The template emits this from `config:
+   * { Activity: {...} }`; entities that only use date-range / user scoping omit
+   * it (and must not call the subject finders).
+   */
+  protected readonly patternConfig?: ActivityPatternConfig;
+
+  /**
+   * camelCase key for the recency-ordering column. Defaults to `occurredAt`
+   * (column `occurred_at`); override via `patternConfig.occurredAt`.
+   */
+  protected get occurredAtColumn(): string {
+    const snake = this.patternConfig?.occurredAt ?? 'occurred_at';
+    return toCamel(snake);
+  }
+
+  /**
+   * camelCase key for the subject FK column, resolved from `patternConfig`:
+   * `subjectColumn` (explicit) → `<subject>_id` (derived). Throws when neither
+   * is configured — the subject finders are unusable without it, and a clear
+   * error beats a silent `undefined` column index.
+   */
+  protected get subjectColumn(): string {
+    const explicit = this.patternConfig?.subjectColumn;
+    if (explicit) return toCamel(explicit);
+    const subject = this.patternConfig?.subject;
+    if (subject) return toCamel(`${subject}_id`);
+    throw new Error(
+      'ActivityEntityRepository: subject finders require a subject column. ' +
+        "Set `config: { Activity: { subject: '<entity>' } }` (→ <entity>_id) " +
+        "or `config: { Activity: { subjectColumn: '<column>' } }` on the entity YAML.",
+    );
+  }
+
+  /**
+   * Find activities within a date range (inclusive), by the recency column.
    */
   async findByDateRange(start: Date, end: Date): Promise<TEntity[]> {
     const rows = await this.baseQuery()
-      .where(between(this.table['occurredAt'], start, end));
+      .where(between(this.table[this.occurredAtColumn], start, end));
     return rows as TEntity[];
   }
 
   /**
-   * Find all activities for a specific user.
+   * Find all activities for a specific user (actor / owner scoping).
    */
   async findByUserId(userId: string): Promise<TEntity[]> {
     const rows = await this.baseQuery()
@@ -29,21 +87,22 @@ export abstract class ActivityEntityRepository<TEntity> extends BaseRepository<T
   }
 
   /**
-   * Find all activities for a specific opportunity.
+   * Find all activities for a specific subject (config-driven FK column).
    */
-  async findByOpportunityId(opportunityId: string): Promise<TEntity[]> {
+  async findBySubjectId(subjectId: string): Promise<TEntity[]> {
     const rows = await this.baseQuery()
-      .where(eq(this.table['opportunityId'], opportunityId));
+      .where(eq(this.table[this.subjectColumn], subjectId));
     return rows as TEntity[];
   }
 
   /**
-   * Find the most recent activities for an opportunity, ordered by occurredAt desc.
+   * Find the most recent activities for a subject, ordered by the recency
+   * column descending.
    */
-  async findRecentByOpportunityId(opportunityId: string, limit = 10): Promise<TEntity[]> {
+  async findRecentBySubjectId(subjectId: string, limit = 10): Promise<TEntity[]> {
     const rows = await this.baseQuery()
-      .where(eq(this.table['opportunityId'], opportunityId))
-      .orderBy(desc(this.table['occurredAt']))
+      .where(eq(this.table[this.subjectColumn], subjectId))
+      .orderBy(desc(this.table[this.occurredAtColumn]))
       .limit(limit);
     return rows as TEntity[];
   }

package/runtime/base-classes/activity-entity-service.ts

@@ -1,17 +1,19 @@
 /**
  * ActivityEntityService<TRepo, TEntity>
  *
- * Family-specific base service for activity entities.
- * Delegates to an activity repository that provides date-range,
- * user, and opportunity queries.
+ * Family-specific base service for activity / interaction entities. Delegates
+ * to an activity repository that provides date-range, actor (`user_id`), and
+ * config-driven subject queries. The subject FK column is resolved inside the
+ * repository from its `patternConfig` (ADR-031 §4) — the service is
+ * subject-name-agnostic. See ACTIVITY-SUBJECT-1.
  */
 import { BaseService, type IBaseRepository } from './base-service';
 
 export interface IActivityEntityRepository<TEntity> extends IBaseRepository<TEntity> {
   findByDateRange(start: Date, end: Date): Promise<TEntity[]>;
   findByUserId(userId: string): Promise<TEntity[]>;
-  findByOpportunityId(opportunityId: string): Promise<TEntity[]>;
-  findRecentByOpportunityId(opportunityId: string, limit?: number): Promise<TEntity[]>;
+  findBySubjectId(subjectId: string): Promise<TEntity[]>;
+  findRecentBySubjectId(subjectId: string, limit?: number): Promise<TEntity[]>;
 }
 
 export abstract class ActivityEntityService<
@@ -26,23 +28,23 @@ export abstract class ActivityEntityService<
   }
 
   /**
-   * Find all activities for a specific user.
+   * Find all activities for a specific user (actor / owner scoping).
    */
   findByUser(userId: string): Promise<TEntity[]> {
     return this.repository.findByUserId(userId);
   }
 
   /**
-   * Find all activities for a specific opportunity.
+   * Find all activities for a specific subject (config-driven FK column).
    */
-  findByOpportunity(opportunityId: string): Promise<TEntity[]> {
-    return this.repository.findByOpportunityId(opportunityId);
+  findBySubject(subjectId: string): Promise<TEntity[]> {
+    return this.repository.findBySubjectId(subjectId);
   }
 
   /**
-   * Find the most recent activities for an opportunity.
+   * Find the most recent activities for a subject.
    */
-  findRecent(opportunityId: string, limit?: number): Promise<TEntity[]> {
-    return this.repository.findRecentByOpportunityId(opportunityId, limit);
+  findRecent(subjectId: string, limit?: number): Promise<TEntity[]> {
+    return this.repository.findRecentBySubjectId(subjectId, limit);
   }
 }

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';