---
id: ADR-PFM-DJE-007
title: Durable producer identity mapping
product_area: platform
module: data-job-engine
revision: 1
status: proposed
design_intent: confirmed
source_sha:
  macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03
  services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
decision: >-
  The record transaction writes a durable producer-key mapping with revision and
  version metadata plus first and last job identifiers that have no job foreign
  keys.
constrains:
  - DOM-PFM-DJE-004
  - WF-PFM-DJE-007
  - WF-PFM-DJE-014
  - SVC-PFM-DJE-engine
origin: >-
  services-platform:docs/proposals/rhythm-data-job-engine-plan.md §6.3 matching
  keys and ID mapping (approved 2026-10-12)
alternatives:
  - option: Add producer identifiers directly to every domain record
    why_not: >-
      Multiple producers need separate revision and version metadata as well as
      their keys.
  - option: Match imports by natural keys
    why_not: >-
      Mutable or ambiguous natural keys do not supply a reliable producer
      identity.
consequences:
  - Existing mappings support revision comparison and replay handling.
  - 'Record deletion, merge and workspace reset must reconcile mappings.'
  - An unseen producer key can create another record for an existing person.
  - >-
    Existing rows are locked, but concurrent first deliveries can create
    separate records and replace the winning mapping destination.
supersedes: []
evidence:
  - >-
    macroservice-libraries at 54536a44: README.md#Keyed writes and the ID
    crosswalk; src/data-id-mapping-columns.ts
---

# Durable Producer Identity Mapping

## Context

External producers identify records with their own keys and may replay deliveries.

## Decision and Origin

The record transaction writes a durable producer-key mapping with revision and version metadata plus first and last job identifiers that have no job foreign keys. The origin recorded above supplies the authority for this choice; implementation evidence supplies the limits described here.

## Alternative Comparison

Add producer identifiers directly to every domain record: Multiple producers need separate revision and version metadata as well as their keys.

Match imports by natural keys: Mutable or ambiguous natural keys do not supply a reliable producer identity.

## Consequences

Existing mappings support revision comparison and replay handling.

Record deletion, merge and workspace reset must reconcile mappings.

An unseen producer key can create another record for an existing person.

Existing rows are locked, but concurrent first deliveries can create separate records and replace the winning mapping destination.