Skip to content

Order-Set Registry Snapshot

This workflow imports the active Elation order-set catalog and Dr Tro's approved mapping artifact to create one append-only registry snapshot. It does not treat an Elation vendor/compendium code as LOINC. The parent registry is never deleted or overwritten.

What It Reads

Use the generated lab_order_sets_catalog.latest.json, not the historical raw export. The current snapshot contains 76 active order sets and 255 unique active tests. The compiler preserves:

  • Elation test IDs, vendor test code, lab-vendor ID, and compendium ID
  • test name and source synonyms
  • CPTs as advisory billing metadata
  • procedure class, order-set IDs/names, fax label hints
  • the exact source snapshot SHA-256

Rows are deduplicated by vendor, compendium, vendor code, and test ID. Display name alone is never a key. Deleted rows are ignored.

The source snapshot is supplied by the main project, for example:

C:\Users\Toward Health\Desktop\Workspace\faxautomation\scripts\elation-sandbox\output\lab_order_sets\lab_order_sets_catalog.latest.json

Classification And Scope

Every active test receives exactly one classification:

Classification Runtime meaning
ready_universal One source-neutral scalar result is supported. Creates a non-active universal proposal.
ready_source_evidence One scalar result is supported, but vendor/test/method facts must remain source evidence.
panel_context_only Panel, profile, reflex, differential, or multi-result order. Never emits one result LOINC.
needs_vendor_definition Vendor code exists but official scalar result facts are missing or incomplete.
needs_clinician_choice Multiple clinically distinct active signatures remain.
vendor_specific_no_exact_code Official definition says no exact LOINC exists, or the result is proprietary.
rejected_conflict Explicit specimen, method, time, or other facts conflict with every candidate.

The snapshot compiler promotes only Dr Tro rows marked verified_active and only active LOINC result terms (ORDER_OBS=Observation or Both) in the pinned release. It preserves the 86 panel/reflex/timed exclusions as audit metadata and runtime exclusions; those orders never receive one parent LOINC code. All 255 active order tests are matched to the approved source inventory, even when their parent order remains context-only.

Official Vendor Definitions

The main project owns network access and credentials. If an Elation vendor code needs resolution, retrieve a non-PHI definition from an official vendor source and write a versioned JSON file using the repository template config/vendor_definitions.example.json; the machine-readable contract is config/vendor_definitions.schema.json.

Required evidence includes the vendor code, exact definition, scalar or panel result type, component output(s), specimen, unit, method when relevant, source URL, retrieval timestamp, and content SHA-256. A missing or incomplete vendor definition remains unresolved. Do not fill missing facts from a general web search or an LLM.

The existing main-project DSPy/Vertex judge may receive one vendor definition and a bounded list of official LOINC candidates. It may explain a difference or identify missing facts. It cannot invent a code, publish a mapping, or bypass axis/unit validation. If it is unavailable, classify the row as needs_clinician_choice.

Approved Panel Components

Parent orders such as CMP, CBC, thyroid profiles, and HbA1c-with-eAG are not single result observations. For the common panels already used by the practice, the repository keeps a small, versioned manifest at config/order_set_panel_components.20260827.json. It contains only scalar result rows backed by official vendor result maps or an explicitly documented LOINC/report source. Each row records its source URL, vendor panel code, result-level name, LOINC target, and source unit when available.

The current manifest covers Labcorp CMP 322000, CBC with differential 005009, TSH plus free T4 224576, and HbA1c with eAG 102525, plus the explicit MPV and RDW-SD rows from the supplied CBC report. Labcorp publishes result-level CMP names and LOINC codes on its CMP page (CMP result map) and result-level CBC names and codes on its CBC page (CBC result map). The TSH/free-T4 page identifies the two scalar components (TSH and free T4).

The manifest is not a new terminology database and does not filter the full LOINC catalog. It is a reviewed alias source used during snapshot generation. The compiler validates every target against LOINC 2.82 and skips a conflicting alias instead of overwriting the parent registry. Source specimen text is retained as provenance; it is not silently written as an analytical specimen constraint for a universal mapping. Parent panel names, CPTs, vendor order codes, and order-set names never become result aliases.

Run The Audit

From the module repository:

$env:PYTHONPATH = "$PWD\src"
python -m loinc_mapper audit-order-sets `
  --input "C:\Users\Toward Health\Desktop\Workspace\faxautomation\scripts\elation-sandbox\output\lab_order_sets\lab_order_sets_catalog.latest.json" `
  --catalog assets\loinc\2.82\catalog_v5.sqlite3 `
  --registry config\mapping_registry.json `
  --output evaluation\order_sets\order_set_audit.latest.json

With official definitions:

python -m loinc_mapper audit-order-sets `
  --input "C:\path\lab_order_sets_catalog.latest.json" `
  --vendor-definitions config\vendor_definitions.2026-08-24.json `
  --catalog assets\loinc\2.82\catalog_v5.sqlite3 `
  --registry config\mapping_registry.json `
  --output evaluation\order_sets\order_set_audit.latest.json

The audit JSON is both the classified inventory and the review evidence. It contains each source record, candidates with official display names and axes, explicit facts, reasons, and promotion eligibility.

Build The Append-Only Snapshot

The approved Dr Tro file is a bare JSON array. Build exactly one new snapshot from it, the active catalog, the current registry, and the versioned panel manifest. Supporting audit files are optional diagnostics and are not required for the approved snapshot:

python -m loinc_mapper build-order-set-snapshot `
  --approved-mappings "C:\Users\Toward Health\Downloads\final_lab_order_set_loinc_mapping_v2.json" `
  --order-set-catalog "C:\path\lab_order_sets_catalog.latest.json" `
  --registry config\mapping_registry.json `
  --catalog assets\loinc\2.82\catalog_v5.sqlite3 `
  --panel-components config\order_set_panel_components.20260827.json `
  --output config\mapping_registry.order_sets.<date>.json

The command writes a new registry_status=active artifact only; it does not modify config/mapping_registry.json. The generated snapshot includes the complete parent mappings list plus appended clinician-authorized universal templates and panel exclusions. Runtime should switch to it only by updating the main project's immutable active pointer after validating its checksum.

The current generated artifact is:

config/mapping_registry.order_sets.20260827.json

Its build metadata records the parent version, source JSON/catalog/panel manifest checksums, counts, conflicts, matched tests, promoted panel aliases, skipped collisions, and safety notes.

Unresolved And Vendor Evidence

If a future Elation catalog changes, the audit and unresolved CSV commands can be run as disposable diagnostics. They are not runtime inputs for the approved snapshot. The CSV columns are:

test_name, vendor_name, vendor_test_code, order_set_names, source_synonyms,
classification, reason, candidate_1, candidate_2, candidate_3,
llm_suggestion, clinician_action, selected_loinc, rationale

If a future run has unresolved rows, allowed clinician actions are:

  • approve_candidate: approve a displayed candidate as a scalar result
  • select_alternative: use another displayed candidate
  • keep_context_only: keep a panel/profile out of runtime mapping
  • not_standardized: no exact reusable LOINC result exists

An approval requires a selected active candidate and rationale. The validation command rejects arbitrary codes that were not in the bounded audit candidate set. A code outside that set should become a normal ReviewCase, where the main project can use its authenticated active-LOINC search UI.

python -m loinc_mapper validate-order-set-approvals `
  --audit evaluation\order_sets\order_set_audit.latest.json `
  --input evaluation\order_sets\order_set_unresolved.completed.csv `
  --catalog assets\loinc\2.82\catalog_v5.sqlite3 `
  --output evaluation\order_sets\order_set_approval_validation.json

Those future approvals should use the authenticated ReviewCase workflow. This Dr Tro bootstrap is already approved and therefore does not create another review CSV or require a second approval step.

What Is Safe To Promote

Universal templates are appropriate for an invariant scalar meaning such as a reviewed Hemoglobin A1c result. Source evidence is appropriate when a vendor definition supplies a clinically important assay or method. A source test ID may disambiguate that assay when the fax workflow later passes it; vendor code or laboratory name alone cannot override a universal mapping.

CPTs are many-to-many billing evidence. They never select or filter LOINC. Order-set names are soft panel context. Names such as CBC, CMP, Iron and TIBC, or reflex profiles must not become one test.loinc value.

When the same alias already exists in the parent registry:

  1. Same alias and same target merge provenance.
  2. Same alias and different target retains both records. The exact clinician- approved universal record has precedence over lab-name-only legacy evidence; a future exact source_test_id or explicit method/specimen fact may disambiguate a documented local assay.
  3. An existing active mapping is never overwritten or deleted by the bootstrap.

Known retained conflicts include AM cortisol (9813-7 versus legacy 2143-6), total 25-hydroxy vitamin D (62292-8 versus legacy D3-only 1989-3), and other clinically distinct legacy surfaces. Both remain auditable in the snapshot.

Main-Project Integration

The main project should:

  1. Export the active order-set catalog and retain its snapshot hash.
  2. Use the generated snapshot as an immutable registry object; never edit its JSON from the clinician UI.
  3. Retrieve official vendor definitions only for the 255 active tests when a panel or vendor-coded order needs more result-level evidence.
  4. Submit LabObservation.source_test_id when the pending Elation order can be matched after patient demographic reconciliation.
  5. Persist audit JSON, unresolved CSV decisions, reviewer identity, and the registry version in its durable review ledger.
  6. Use the module's ReviewCase publication contract rather than editing JSON registry files in the UI.
  7. Keep raw PDFs, patient data, Elation credentials, DSPy, and Vertex access outside this package.

The future chart-order integration may add CPT, diagnosis, order-set, and ordering context as advisory evidence. It is not implemented as a hard global LOINC filter in this bootstrap.

Current Baseline

The generated snapshot from 2026-08-27 contains 595 unchanged parent entries, 115 appended Dr Tro entries, 44 same-target merges, 4 retained cross-target conflicts, 81 panel exclusions, 137 safe order synonyms, and 93 promoted or merged scalar panel aliases from 45 manifest components. Two ambiguous panel aliases were retained as non-promoted conflicts. It matched all 255 active tests from the 76-order-set catalog. The final artifact has 884 entries and zero invalid, inactive, or order-only targets. No parent panel was mapped to one LOINC code. Broad differential aliases such as Lymphs and Eos are intentionally excluded because they do not distinguish relative from absolute results.

To rebuild after changing the manifest, rerun the same command with a new versioned output name. Never edit the generated JSON in the clinician UI and never replace the parent config/mapping_registry.json in place.