Reference troubleshooting, refusal codes and safe reconciliation

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.

Reference Testing configuration pending, zero directory rows and disabled actions are expected now. They are not an empty operational service: canonical relationships, mappings, native registry and referral writer are unavailable. No button sent an invitation, stored an approval, transmitted an order or returned a result.

• Non-sender / wrong client / wrong Program: no menu data. Do not retry using another workspace’s credential.
• Blocked authorized sender: safe identifiers and refusal reasons only; code/specimen/price details are redacted.
• Failed status read: keep unavailable, never promote cached source approval into orderability.

401/403 belong to the existing API’s documented authentication/authorization responses, not a newly invented R1 HTTP body. Internal source codes and staged uppercase SQL exceptions are separate diagnostics; do not promise a wire status or response schema for every source refusal.

• bilateral_consent_missing / relationship_not_effective → missing current consent → obtain independent current approvals, not a role-only override.
• program_client_scope_mismatch / program_version_stale → exact Program/client/version failure → re-read authorized grant.
• mapping_draft_or_withdrawn / mapping_version_stale → clinical review missing/stale → hold for licensed reviewer.
• native_registry_absent / reference_core_authority_absent / reference_execution_disabled → installed authority absent → await separately governed release, no direct writes.
• invalid_or_client_authority_input / duplicate_specimen_ref → strict command validation failure → correct scoped input without inventing identity.

• Native ambiguity note: native_result_poll_reconcile_only. It does not establish an installed polling capability today.
• Legacy HTTPS ambiguity note: legacy_https_terminal_reconcile. Keep the same identity: idempotency key and transmission reference.
• webhook_retry uses existing_webhook_worker_retry; never create another queue or repeat the clinical order.

Observed fact                  Classification                  Safe next step
409 / timeout after send       uncertain_sent_reconcile        NO resend
missing application ACK        transport_only_await_application_ack   hold
proven connect refusal         not_sent_retry_same_identity    existing worker only
unsigned / replay callback     callback_refused                reject, preserve audit
unknown result status          pending_clinical_review         retain last release
partial specimen rejection     specimen_recollection           isolate specimen

1. Record environment and safe order/transmission/specimen/result correlation identifiers, not clinical free text.
2. Capture observed stage, source, timestamp, current scope/revision and allow-listed refusal category.
3. Check cancellation, relationship revocation, terms/mapping drift and actual custody evidence before deciding recovery.
4. For delayed TAT, distinguish no receipt from delayed processing; a time estimate is not a carrier or analysis event.
5. Route clinical release questions to the performer’s authorized reviewer; route replay/signature anomalies to security.

Never change an idempotency key after an ambiguous send; never fabricate application ACK or accession; never turn UNKNOWN into FINAL; never include keys, raw callbacks, patient data or private contract prices in support exports. Critical result notification requires a separate human clinical procedure. This guide documents source behavior, not an available support SLA or live reference service.