Diligence status

From you

nothing

Details

What fires each event

arrow word, code event, one caller at HEAD

queue kyc = enqueue_kyc: trigger.ts:167 transitionCaseToKycQueuedWithRetry, 3 attempts with jitter, after the provider POST queues Trulioo sessions
submitted = kyc_submitted: no transitionCase caller. trulioo/queue.ts:654-665 promoteCdCasesToKycProcessing writes kyc_processing inline (EXISTS on submitted sessions), run by the KYC cron route.ts:284; it also moves received straight to kyc_processing, an edge the table does not have
succeeded = kyc_succeeded: notify.ts:506 promoteCaseStatus on the Trulioo FLOW_END webhook, from received, kyc_queued, kyc_processing or kyc_failed
kyc failed = kyc_failed: no transitionCase caller. trigger.ts:211-220 markCaseKycFailedIfNoSessions writes it inline from received or kyc_queued only, and only when no Trulioo session row exists; the kyc_processing row in the table has no writer at HEAD
pdf lands = pdf_received: case-diligence-pdf.ts:337 on the screening PDF webhook, patches final_pdf_r2_key and final_pdf_received_at in the same UPDATE; allowed from every pre-dispatch state because the PDF can land before KYC finishes
claim = dispatch_claim: pdf-batch-dispatch.ts:390 processDispatchBatch step 1, one case at a time
email sent = dispatch_sent: pdf-batch-dispatch.ts:113 markCasesDispatchedWithRetry, bulk, patches dispatched_at and dispatch_batch_id
release = dispatch_release: pdf-batch-dispatch.ts:213, 518 and 575, bulk, when the batch fails or a case was left out of the ZIP; plus the inline 10 minute stuck-dispatching sweep at 270-275
oversized pdf = dispatch_failed: pdf-batch-dispatch.ts:69 quarantines a case whose PDF alone exceeds MAX_ZIP_BUFFER_BYTES, so the rest of the campaign batch can drain

The CAS guard

transitionCase, cases-state.ts:272-363

SELECT the row's status, resolve (status, event) in ALLOWED_TRANSITIONS; no row in the map means RepositoryError conflict invalid_state_transition and nothing is written
atomicTransition (repositories/concurrency.ts:144-164) runs UPDATE ... WHERE id = $id AND status = $read; zero rows means a concurrent writer moved it, RepositoryError conflict concurrent_write
Callers treat both conflicts as benign no-ops (trigger, notify, PDF webhook, dispatch claim) and re-read instead of forcing the write
transitionCasesBulk (cases-state.ts:440-503) needs expectedFromState, issues one UPDATE WHERE id = ANY($ids) AND status = $from, and silently skips rows that moved; count versus ids.length tells the caller
Every call takes a MutationContext, so it runs inside withTransaction; patch columns are identifier-allowlisted and parameter-bound

Audit trail

ADR-019

Each winning transition emits one audit.events row: aggregate_type case_diligence.case, event_type case_diligence.case.transitioned, before and after status, metadata.event (cases-state.ts:353-360)
The bulk variant emits one row per transitioned id (cases-state.ts:491-500)
emitEvent (observability/events.ts) writes on the same transaction under a SAVEPOINT; a failed audit INSERT logs WARN and never rolls back the status flip
Inline carve-out writers (dashed edges) bypass this emit, so their flips are not in audit.events

Dashed arrows: written outside the machine

cases-state.ts:15-21 lists the carve-outs: trigger.ts markCaseKycFailedIfNoSessions (NOT EXISTS guard), pdf-batch-dispatch.ts stuck-dispatching sweep (time predicate), trulioo/queue.ts promoteCdCasesToKycProcessing (cross-table EXISTS), queue/claim.ts (that one is the GHL queue table, not this column)
Each stays inline because the state machine's patch map carries column values only, not SQL predicates
The enum has nine values; 'dispatched' and the spec's 'initial' were left out of mig 362 on purpose (lines 141-147). The const key DISPATCHED maps to the value 'sent'

Not in this diagram

Layout note: the happy path ends at sent (success, double border); it sits below dispatching only because seven phases do not fit one readable row
The GHL push retry queue machine: case_diligence.ghl_queue.status, five statuses (pending, processing, succeeded, abandoned, failed) and five events, in ghl-queue-state.ts
The ops.cases status machine (status, qc_status): a separate diagram
The Trulioo session machine on kyc.trulioo_sessions.status (pending, submitted, completed, failed) in kyc/session-state.ts, which feeds kyc_submitted and kyc_succeeded here
case_diligence.dispatch_batches.status (pending, failed, sent) written by the dispatch cron beside the case flips
Cron schedules come from app/vercel.json: case-diligence-kyc */5, case-diligence-dispatch 0 */12

Diligence status

The short version

From you