---
id: STATE-CRM-DQ-005
title: Merge attempt and its job
object: DOM-CRM-DQ-004
product_area: crm
module: data-quality
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69
states:
  - name: queued
    meaning: >-
      The request has committed the attempt and job before a successful worker
      claim.
  - name: running
    meaning: >-
      The executor has claimed the row inside the still-uncommitted merge
      transaction.
  - name: succeeded
    meaning: >-
      Business commit retained the outcome, aliases, audit pointers and any
      contact event.
  - name: failed
    meaning: Failure settlement records an explanation after business rollback.
transitions:
  - from: queued
    to: running
    trigger: The task begins the transaction and claims the queued attempt.
    guard: The conditional claim must still find queued standing.
    side_effects:
      - apply five-second lock and five-minute statement limits
      - acquire advisory and participant row locks in fixed order
    who: merge task under the state machine
    provenance: observed
    source: >-
      services-crm:modules/merges/services/merges/merge-execution.ts:executeMerge
  - from: running
    to: succeeded
    trigger: The complete business transaction succeeds.
    guard: >-
      Replanning matches approval, participants exist, blockers clear,
      applications accept and the survivor validates.
    side_effects:
      - settle the plan as executed
      - report completed job steps after commit
      - nudge committed contact event delivery
    who: merge task
    provenance: test
    source: >-
      services-crm:modules/merges/tests/integration/services/merges/approval-binding.integration.spec.js#fails
      the merge Stale inside its transaction rather than moving a task nobody
      approved
  - from: running
    to: failed
    trigger: Execution catches a refusal or exception.
    guard: Conditional failure settlement still finds queued or running standing.
    side_effects:
      - store failure code and reason
      - reopen an eligible plan
      - report the mapped failed step and leave later steps queued
    who: merge task
    provenance: test
    source: >-
      services-crm:modules/merges/tests/integration/services/merges/merge-settlement.integration.spec.js#returns
      the plan to the status it had before it was executed, rather than leaving
      it executing
  - from: queued
    to: failed
    trigger: Reconciliation closes an attempt whose job never completed.
    guard: Settlement accepts only a still-unfinished attempt.
    side_effects:
      - record internal failure
      - reopen its eligible plan
    who: job reconciler
    provenance: observed
    source: >-
      services-crm:modules/merges/services/jobs/record-merge-job.ts:markMergeFailedForLostJob
  - from: running
    to: failed
    trigger: Workflow failure handling or reconciliation settles unfinished execution.
    guard: The attempt is queued or running when settlement obtains it.
    side_effects:
      - preserve existing executor failure or record internal failure
      - reopen its eligible plan
    who: workflow failure task; the job reconciler
    provenance: observed
    source: >-
      services-crm:modules/merges/services/merges/merge-settlement.ts:settleMergeAsFailed
invalid:
  - from: succeeded
    to: failed
    why: Failure settlement cannot overwrite successful business completion.
  - from: failed
    to: queued
    why: Another user attempt creates a new merge instead of reviving a failed one.
  - from: succeeded
    to: queued
    why: The service provides no undo or resubmission of successful attempts.
concurrency: >-
  A worker claim is conditional and part of the business transaction. Rollback
  restores queued standing, after which a separate settlement records failure.
  Overlapping attempts acquire participant advisory locks in order; conditional
  terminal updates make repeated settlement safe.
invariants:
  - INV-DOM-CRM-DQ-004-01
  - INV-DOM-CRM-DQ-004-03
  - INV-DOM-CRM-DQ-004-04
  - INV-DOM-CRM-DQ-004-05
  - INV-DOM-CRM-DQ-004-14
evidence:
  - >-
    services-crm at a8d1364f: modules/merges/db/record-merges.table.ts,
    record-merge-jobs.table.ts; services/merges/merge-execution.ts,
    merge-settlement.ts; services/jobs/record-merge-job.ts,
    record-merge-job-tasks.ts; aws/crm.record-merges.names.ts.
---

# Merge Attempt And Its Job

## The Lifecycle

```mermaid
stateDiagram-v2
  state "queued" as queued
  state "running" as running
  state "succeeded" as succeeded
  state "failed" as failed
  queued --> running: The task begins the transaction and claims the queued attempt
  running --> succeeded: The complete business transaction succeeds
  running --> failed: Execution catches a refusal or exception
  queued --> failed: Reconciliation closes an attempt whose job never completed
  running --> failed: Workflow failure handling or reconciliation settles unfinished execution
```

## Transitions Explained

Submission commits a queued attempt and its job. The executor’s running claim belongs to the business transaction, so ordinary readers need not see it while locks are held. Success commits the attempt and outcome; rollback restores queued standing until failure settlement commits.

## What Cannot Happen

A successful attempt cannot be failed later or reversed. A new execution after failure creates a separate attempt, and overlapping merges cannot both absorb one participant.

## Concurrency and Timing

Job reporting begins before the business transaction and settles its four steps afterward. Lock waits are capped at five seconds; a caught lock timeout normally becomes a failed attempt and task refusal. Workflow retry applies to transient task errors that escape that settlement, within the fifteen-minute task and twenty-one-minute workflow limits.