Reference specimen custody and accession evidence

Everything below describes engineering source contracts and isolated test evidence (disposable PostgreSQL, loopback PostgREST, test-signed tokens). Where a behavior is described as "designed", it exists in source and isolated tests only — not as a joined, persisted canonical R1 workflow. This is not an availability, certification or publication announcement.

applyCustodyEvent is a pure in-memory contract over per-specimen evidence; it is not a canonical specimen writer or courier integration. Current R1 has no persisted custody chain or performing accession. Do not label a displayed designed stage as an operational event.

none → prepared
prepared → dispatched | rejected
dispatched → carrier_in_transit | carrier_delivered | performer_received
carrier_in_transit → carrier_delivered | performer_received
carrier_delivered → performer_received
performer_received → accessioned | rejected
accessioned → processing | rejected
processing → rejected
rejected → recollection_requested
recollection_requested → [no further transition in this contract]

CustodyEvent names specimenId, orderId, to, actor, source, occurredAt and correlationId. accession, handling and reason are conditionally required. actor and correlationId must be nonempty; occurredAt must parse as time and cannot regress behind the specimen’s previous event.

• prepared and dispatched require sender_lab source.
• carrier_in_transit and carrier_delivered require carrier_evidence. No carrier client or integration is provided.
• performer_received, accessioned, processing, rejected and recollection_requested require performer_lab source.
• accessioned requires a distinct accession identifier; receipt does not infer it.
• rejected and recollection_requested require reason; governed prepared/performer_received events require handling evidence.

The contract permits dispatched directly to performer_received, because actual receiving evidence may exist without a carrier feed. It must not create carrier_in_transit or carrier_delivered events in between. Similarly a carrier delivery scan never creates performer receipt or accession.

1. Correlate the real event to the existing order and exact specimen.
2. Verify authoritative actor/source and chronological timestamp; refuse a foreign order or missing correlation.
3. Check allowed transition and governed container/volume/preparation/handling evidence.
4. Append only that specimen event. Preserve other specimens without cancellation.
5. For accession, record actual B accession separately from sender reference and kit barcode.

orderCustodySummary distinguishes none_rejected, partial_rejection and whole_kit_rejected; orderCanceled is always false in this source summary. One rejected specimen affects only its ledger entry. Recollection is a recorded request, not an automatic replacement order, new kit or courier booking.

• custody_evidence_incomplete: repair source evidence, never fabricate actor/time.
• custody_source_not_authoritative: obtain performer/carrier evidence as appropriate.
• specimen_order_mismatch or custody_time_regression: hold and investigate correlation.
• accession_identifier_required or governed_handling_evidence_required: wait for actual governed evidence.

Verify every allowed edge and prohibited jump in a disposable future canonical implementation, including individual rejection with a second specimen unchanged. Current tests prove source transition rules only. Production custody and clinical acceptance remain unavailable.