Reference order lifecycle, correlation and idempotency

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.

solia.reference.orders.v1 and referralOrderCommand are source contracts. There is no new public R1 route or OpenAPI operation. Existing Partner API order schemas remain authoritative for the separate canonical API; do not POST this illustrative shape to those endpoints.

NON_EXECUTABLE field outline (exact source names)
tenantId, environment, relationshipId, relationshipVersion
bindingId, programId, clientId, senderExternalRef
kitBarcode? , destinationNativeCode
specimens[1..20]: senderSpecimenRef, type, container,
                 volume: { amount: positive finite number, unit }
region, collection, method, idempotencyKey
UUID fields require UUID values; reference fields are bounded
No actor, role, organization or approval fields are accepted

tenantId/environment are requested scope, not proof of acting identity. The authenticated boundary must verify the caller; strict parsing rejects extra authority fields. Recheck consent/version, exact binding/client/Program, destination code, every specimen and installation scope before a canonical write.

1. Resolve trusted current sender/performer and Program facts, not client assertions or a prior menu snapshot.
2. Validate every specimen’s type/container/volume and unique senderSpecimenRef. The first specimen used to build context never exempts later specimens.
3. Validate registry installation tenant/laboratory/environment, reviewed mapping persistence and current execution gates.
4. Compute the deterministic SHA-256 fingerprint; check an existing attempt under the same idempotency identity.
5. Only a future installed canonical writer may create an order/transmission and immutable reference attribution link. Current runtime refuses before writes.

• The designed snapshot preserves relationship, Program, mapping, terms, native codes, reviewer/fingerprints and specimen requirements at order time.
• P3 staged attribution references canonical orders/transmissions only. It does not persist custody or result release.
• The insert path refuses while clinical mapping authority is absent; no operational snapshot or joined referral transaction exists.

senderExternalRef (A requisition)
 → canonicalOrderId (Core order, currently no R1 creation)
 → transmissionId (same correlated order, not another queue)
 → specimenId / senderSpecimenRef (individual specimen)
 → performerAccession (B accession evidence)
 → sourceResultId + result version + officialReportRef
kitBarcode is separate; never substitute it for order/accession

referralFingerprint sorts object keys recursively and hashes the command except idempotencyKey; array order remains significant. Same key/same fingerprint replays existing identifiers. Different fingerprint returns idempotency_payload_conflict. A sent_uncertain prior attempt returns transmission_uncertain_no_resend, never a fresh send.

• HTTP 201 in a candidate native response is transport SENT only, not application ACK, accession or clinical release.
• 409 or timeout after send: preserve identity and reconcile; do not change key or duplicate the order.
• Proven connection refusal before any send differs from uncertain delivery; only the existing worker may retry under the same identity.
• No replacement queue, direct retry button or source-level approval bypass is introduced.

P3 has ten disposable PostgreSQL/PostgREST cases for staged links, RLS, rollback and referral refusal. They prove refusal without canonical writes, not a positive A→B order. R1-13 remains PARTIAL; separate canonical Partner API transactional evidence must not be relabeled an R1 journey.