⌘K

Reference TestingGuide

Reference results, correction lineage and scoped webhooks

Performer release gates, pending unknowns, historical versions and the unchanged nine-event canonical catalog.

On this page

Current availability — October 25, 2026

Limitation

Reference Testing is NOT available in Production and is NOT operational in Sandbox. The relationship, Program-binding and order-link database packages are staged and unapplied, both reference gates are off, no native installation registry exists and no clinical mapping authority has been established. The Control Plane shows "Reference Testing configuration pending" and every action is disabled with its reason.

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.

Three acknowledgements, three different facts

Transport receipt means a message reached a peer; application ACK means the laboratory application accepted the order; clinical release means a performer-authorized official result exists. None implies the next. R1 result handling is a pure contract, not an installed release service.

  1. Correlate orderId and performerTenantId to the existing result history.
  2. Require verified signature and a nonce not already recorded. The source receives signedVerified evidence; it does not implement or certify a vendor signing protocol.
  3. Deduplicate sourceResultId independently from nonce replay.
  4. Require verified_generic status contract, known FINAL/CORRECTED, performer authorization, releasedBy/releasedAt and officialReportRef.
  5. Keep UNKNOWN, unverified_candidate or incomplete release evidence PENDING_CLINICAL_REVIEW.
  6. Append a new released version only after a prior FINAL for CORRECTED; never overwrite the earlier official version.

Exact source lineage and refusal behavior

ResultHistory keeps orderId, performerTenantId, versions, nonces and pending. ReleasedVersion retains version, type, officialReportRef, releasedBy, releasedAt and sourceResultId. FINAL after an earlier release refuses final_already_released_use_corrected; CORRECTED before FINAL refuses corrected_without_final.

  • performer_or_order_mismatch: no reassociation to another order.
  • unsigned_callback or replayed_callback: refuse, never release.
  • A new nonce with an existing sourceResultId yields duplicate; it does not append another clinical version.
  • A pending correction leaves the last released version current. Prior released versions remain in history.
  • The source flags are evidence inputs, not real reviewer or signer authority.

Sender reads and revocation boundary

readReferenceResults requires the exact linked order, senderTenantId, programId and authorizedAtOrder; unrelated tenant or Program gets no result. This designed history rule can preserve previously authorized releases after relationship revocation. Existing canonical Partner API independently revalidates current client/catalog/Program policy; an old link is not a live access bypass.

  • Nexus-shaped candidate FINAL/CORRECTED remains unapproved and PENDING_CLINICAL_REVIEW. Approved generic synthetic fixtures are distinct, not vendor conformance.
  • humanNotified is false even when critical is true. Clinical escalation and acknowledgement by a human remain the performer’s governed procedure.
  • No joined R1 canonical result release or sender GET has been established. Separate canonical Partner API persisted tests do not close R1-13.

Existing canonical event catalog — unchanged

The following nine names come from the existing Partner event catalog; no reference-specific event or endpoint is added. Event delivery is an identifier/coarse-state/retrieval-pointer notification, not a report or patient payload.

  • order.created
  • order.updated
  • order.cancelled
  • specimen.updated
  • result.partial
  • result.final
  • result.corrected
  • result.critical
  • integration.action_required

Webhook integration verification

Use the existing generated webhook and event reference for exact signature headers, envelope, retry schedule and scopes. Do not invent R1 callback headers. Revalidate the current client/Program scope at delivery, deduplicate events and retrieve authorized current result state through the existing API. A webhook retry cannot cause clinical resend or auto-release.

Continue the integration review

Related resources