fhir-data-utils-ts 0.4.0 → 0.6.1

package/dist/converters/index.js

@@ -2,6 +2,7 @@ export * from './convert-shared.js';
 export * from './convert-allergy-intolerance.js';
 export * from './convert-appointment-response.js';
 export * from './convert-appointment.js';
+export * from './convert-appointment-communication.js';
 export * from './convert-care-plan.js';
 export * from './convert-clinical-impression.js';
 export * from './convert-communication-request.js';
@@ -11,17 +12,23 @@ export * from './convert-condition.js';
 export * from './convert-coverage.js';
 export * from './convert-device-use-statement.js';
 export * from './convert-device.js';
+export * from './convert-device-metric.js';
 export * from './convert-diagnostic-report.js';
 export * from './convert-document-reference.js';
 export * from './convert-encounter.js';
+export * from './convert-encounter-history.js';
 export * from './convert-flag.js';
 export * from './convert-immunization.js';
 export * from './convert-imaging-study.js';
 export * from './convert-location.js';
+export * from './convert-healthcare-service.js';
 export * from './convert-medication-statement.js';
 export * from './convert-observation.js';
 export * from './convert-organization.js';
 export * from './convert-practitioner-role.js';
 export * from './convert-procedure.js';
+export * from './convert-regulated-authorization.js';
 export * from './convert-related-person.js';
 export * from './convert-service-request.js';
+export * from './convert-schedule-slot.js';
+export * from './materialize-claims-first-resource.js';

package/dist/converters/materialize-claims-first-resource.d.ts

@@ -0,0 +1,16 @@
+import type { FhirResource } from '../fhir-types.js';
+export type ClaimsFirstFhirResource = Readonly<{
+    resourceType: 'Organization' | 'HealthcareService' | 'Location' | 'Schedule' | 'Slot' | 'DeviceMetric' | 'Procedure' | 'RegulatedAuthorization' | 'DocumentReference' | 'Encounter' | 'EncounterHistory';
+    id: string;
+    meta: Readonly<{
+        claims: Readonly<Record<string, unknown>>;
+    }>;
+}>;
+/**
+ * Materializes native FHIR R5 only at an explicit adapter boundary.
+ *
+ * Canonical persistence remains `{ resourceType, id, meta: { claims } }`.
+ * Nested native fields are rejected so a materialized representation can never
+ * silently become a second business source of truth.
+ */
+export declare function materializeClaimsFirstResourceToFhirR5(input: unknown): FhirResource;

package/dist/converters/materialize-claims-first-resource.js

@@ -0,0 +1,65 @@
+import { healthcareServiceFlatToFhirR5 } from './convert-healthcare-service.js';
+import { locationFlatToFhirR5 } from './convert-location.js';
+import { organizationFlatToFhirR5 } from './convert-organization.js';
+import { scheduleFlatToFhirR5, slotFlatToFhirR5 } from './convert-schedule-slot.js';
+import { deviceMetricFlatToFhirR5 } from './convert-device-metric.js';
+import { procedureFlatToFhirR5 } from './convert-procedure.js';
+import { regulatedAuthorizationFlatToFhirR5 } from './convert-regulated-authorization.js';
+import { documentReferenceFlatToFhirR4 } from './convert-document-reference.js';
+import { encounterFlatToFhirR5 } from './convert-encounter.js';
+import { encounterHistoryFlatToFhirR5 } from './convert-encounter-history.js';
+const materializers = Object.freeze({
+    Organization: organizationFlatToFhirR5,
+    HealthcareService: healthcareServiceFlatToFhirR5,
+    Location: locationFlatToFhirR5,
+    Schedule: scheduleFlatToFhirR5,
+    Slot: slotFlatToFhirR5,
+    DeviceMetric: deviceMetricFlatToFhirR5,
+    Procedure: procedureFlatToFhirR5,
+    RegulatedAuthorization: regulatedAuthorizationFlatToFhirR5,
+    DocumentReference: documentReferenceFlatToFhirR4,
+    Encounter: encounterFlatToFhirR5,
+    EncounterHistory: encounterHistoryFlatToFhirR5,
+});
+/**
+ * Materializes native FHIR R5 only at an explicit adapter boundary.
+ *
+ * Canonical persistence remains `{ resourceType, id, meta: { claims } }`.
+ * Nested native fields are rejected so a materialized representation can never
+ * silently become a second business source of truth.
+ */
+export function materializeClaimsFirstResourceToFhirR5(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError('claims_first_resource_invalid');
+    }
+    const resource = input;
+    if (Object.keys(resource).some(key => !['resourceType', 'id', 'meta'].includes(key))) {
+        throw new TypeError('claims_first_resource_nested_fhir_forbidden');
+    }
+    const resourceType = String(resource.resourceType || '');
+    const materializer = materializers[resourceType];
+    if (!materializer)
+        throw new TypeError('claims_first_resource_type_unsupported');
+    const id = String(resource.id || '').trim();
+    if (!id)
+        throw new TypeError('claims_first_resource_id_required');
+    const meta = resource.meta;
+    if (!meta || typeof meta !== 'object' || Array.isArray(meta))
+        throw new TypeError('claims_first_resource_claims_required');
+    if (Object.keys(meta).some(key => key !== 'claims'))
+        throw new TypeError('claims_first_resource_nested_fhir_forbidden');
+    const rawClaims = meta.claims;
+    if (!rawClaims || typeof rawClaims !== 'object' || Array.isArray(rawClaims)) {
+        throw new TypeError('claims_first_resource_claims_required');
+    }
+    const claims = {};
+    for (const [claim, rawValue] of Object.entries(rawClaims)) {
+        const values = (Array.isArray(rawValue) ? rawValue : [rawValue])
+            .map(value => String(value).trim())
+            .filter(Boolean);
+        if (!values.length)
+            throw new TypeError('claims_first_resource_claim_value_invalid');
+        claims[claim] = values.join(',');
+    }
+    return Object.freeze({ ...materializer(claims), id });
+}

package/dist/encounter-transfer-test-data.d.ts

@@ -0,0 +1,40 @@
+import { EncounterStatusR5 } from './claims/encounter-claims.js';
+/** Product-neutral identifiers and references for cross-package Encounter transfer contract tests. */
+export declare const FHIR_ENCOUNTER_TRANSFER_TEST_DATA: Readonly<{
+    communicationIdentifier: "urn:uuid:00000000-0000-4000-8000-000000000401";
+    subjectReference: "Patient/00000000-0000-4000-8000-000000000402";
+    senderReference: "Organization/00000000-0000-4000-8000-000000000403";
+    indexRecipientReference: "Organization/00000000-0000-4000-8000-000000000404";
+    occurredAt: "2026-09-30T10:10:00Z";
+    class: Readonly<{
+        system: "http://terminology.hl7.org/CodeSystem/v3-ActCode";
+        code: "EMER";
+    }>;
+    source: Readonly<{
+        id: "00000000-0000-4000-8000-000000000405";
+        reference: "Encounter/00000000-0000-4000-8000-000000000405";
+        identifier: "urn:uuid:00000000-0000-4000-8000-000000000405";
+        serviceReference: "HealthcareService/00000000-0000-4000-8000-000000000406";
+        locationReference: "Location/00000000-0000-4000-8000-000000000407";
+        statusWhenReturning: EncounterStatusR5.OnHold;
+        statusWhenNotReturning: EncounterStatusR5.Completed;
+    }>;
+    destination: Readonly<{
+        id: "00000000-0000-4000-8000-000000000408";
+        reference: "Encounter/00000000-0000-4000-8000-000000000408";
+        identifier: "urn:uuid:00000000-0000-4000-8000-000000000408";
+        serviceReference: "HealthcareService/00000000-0000-4000-8000-000000000409";
+        locationReference: "Location/00000000-0000-4000-8000-000000000410";
+        statusOnArrival: EncounterStatusR5.InProgress;
+    }>;
+    sourceHistory: Readonly<{
+        id: "00000000-0000-4000-8000-000000000411";
+        identifier: "urn:uuid:00000000-0000-4000-8000-000000000411";
+        encounterReference: "Encounter/00000000-0000-4000-8000-000000000405";
+    }>;
+    destinationHistory: Readonly<{
+        id: "00000000-0000-4000-8000-000000000412";
+        identifier: "urn:uuid:00000000-0000-4000-8000-000000000412";
+        encounterReference: "Encounter/00000000-0000-4000-8000-000000000408";
+    }>;
+}>;

package/dist/encounter-transfer-test-data.js

@@ -0,0 +1,37 @@
+import { EncounterStatusR5 } from './claims/encounter-claims.js';
+/** Product-neutral identifiers and references for cross-package Encounter transfer contract tests. */
+export const FHIR_ENCOUNTER_TRANSFER_TEST_DATA = Object.freeze({
+    communicationIdentifier: 'urn:uuid:00000000-0000-4000-8000-000000000401',
+    subjectReference: 'Patient/00000000-0000-4000-8000-000000000402',
+    senderReference: 'Organization/00000000-0000-4000-8000-000000000403',
+    indexRecipientReference: 'Organization/00000000-0000-4000-8000-000000000404',
+    occurredAt: '2026-09-30T10:10:00Z',
+    class: Object.freeze({ system: 'http://terminology.hl7.org/CodeSystem/v3-ActCode', code: 'EMER' }),
+    source: Object.freeze({
+        id: '00000000-0000-4000-8000-000000000405',
+        reference: 'Encounter/00000000-0000-4000-8000-000000000405',
+        identifier: 'urn:uuid:00000000-0000-4000-8000-000000000405',
+        serviceReference: 'HealthcareService/00000000-0000-4000-8000-000000000406',
+        locationReference: 'Location/00000000-0000-4000-8000-000000000407',
+        statusWhenReturning: EncounterStatusR5.OnHold,
+        statusWhenNotReturning: EncounterStatusR5.Completed,
+    }),
+    destination: Object.freeze({
+        id: '00000000-0000-4000-8000-000000000408',
+        reference: 'Encounter/00000000-0000-4000-8000-000000000408',
+        identifier: 'urn:uuid:00000000-0000-4000-8000-000000000408',
+        serviceReference: 'HealthcareService/00000000-0000-4000-8000-000000000409',
+        locationReference: 'Location/00000000-0000-4000-8000-000000000410',
+        statusOnArrival: EncounterStatusR5.InProgress,
+    }),
+    sourceHistory: Object.freeze({
+        id: '00000000-0000-4000-8000-000000000411',
+        identifier: 'urn:uuid:00000000-0000-4000-8000-000000000411',
+        encounterReference: 'Encounter/00000000-0000-4000-8000-000000000405',
+    }),
+    destinationHistory: Object.freeze({
+        id: '00000000-0000-4000-8000-000000000412',
+        identifier: 'urn:uuid:00000000-0000-4000-8000-000000000412',
+        encounterReference: 'Encounter/00000000-0000-4000-8000-000000000408',
+    }),
+});

package/dist/fhir-bundle.d.ts

@@ -7,3 +7,24 @@ export declare function walkBundleResources(bundle: FhirBundle): readonly FhirRe
 export declare function classifyBundleResources(bundle: FhirBundle): ReadonlyMap<string, readonly FhirResource[]>;
 /** Resolves `ResourceType/id`, `urn:uuid:*`, an entry fullUrl, or a bare resource id. */
 export declare function findBundleResourceByReference(bundle: FhirBundle, reference: string): FhirResource | undefined;
+export type CommunicationInnerBundleType = 'document' | 'batch' | 'collection';
+export type CommunicationBundlePayload = Readonly<{
+    communication: FhirResource;
+    attachment: Readonly<{
+        contentType: 'application/fhir+json';
+        data: string;
+        title?: string;
+    }>;
+    bundle: FhirBundle;
+}>;
+/**
+ * Bundle Reader boundary used by every secure Communication flow.
+ *
+ * The outer operational payload is always a batch Bundle containing
+ * Communication entries. Each Communication carries exactly one FHIR JSON
+ * attachment whose decoded resource is an inner document, batch or collection
+ * Bundle. Individual clinical resources and arbitrary file MIME types are not
+ * accepted directly at this boundary; files belong to DocumentReference
+ * entries inside the inner Bundle and must be edited through Bundle Editor.
+ */
+export declare function readCommunicationBundlePayloads(input: unknown): readonly CommunicationBundlePayload[];

package/dist/fhir-bundle.js

@@ -41,3 +41,77 @@ export function findBundleResourceByReference(bundle, reference) {
         : [undefined, target.startsWith('urn:uuid:') ? target.slice('urn:uuid:'.length) : target];
     return readBundleResources(bundle).find(resource => resource.id === id && (!resourceType || resource.resourceType === resourceType));
 }
+/**
+ * Bundle Reader boundary used by every secure Communication flow.
+ *
+ * The outer operational payload is always a batch Bundle containing
+ * Communication entries. Each Communication carries exactly one FHIR JSON
+ * attachment whose decoded resource is an inner document, batch or collection
+ * Bundle. Individual clinical resources and arbitrary file MIME types are not
+ * accepted directly at this boundary; files belong to DocumentReference
+ * entries inside the inner Bundle and must be edited through Bundle Editor.
+ */
+export function readCommunicationBundlePayloads(input) {
+    const outerBatch = requireBundle(input);
+    if (outerBatch.type !== 'batch')
+        throw new TypeError('fhir_batch_bundle_required');
+    validateBatchRequests(outerBatch);
+    const payloads = readBundleResources(outerBatch)
+        .filter(resource => resource.resourceType === 'Communication')
+        .map(communication => {
+        const attachment = firstFhirBundleAttachment(communication);
+        let decoded;
+        try {
+            decoded = JSON.parse(decodeBase64Utf8(attachment.data));
+        }
+        catch {
+            throw new TypeError('fhir_bundle_attachment_invalid');
+        }
+        const bundle = requireBundle(decoded);
+        if (!['document', 'batch', 'collection'].includes(String(bundle.type)))
+            throw new TypeError('fhir_inner_bundle_type_invalid');
+        validateInnerBundle(bundle);
+        return Object.freeze({ communication, attachment, bundle });
+    });
+    if (!payloads.length)
+        throw new TypeError('fhir_communication_required');
+    return Object.freeze(payloads);
+}
+function requireBundle(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || value.resourceType !== 'Bundle')
+        throw new TypeError('fhir_bundle_required');
+    return value;
+}
+function firstFhirBundleAttachment(resource) {
+    const payload = Array.isArray(resource.payload) ? resource.payload : [];
+    if (payload.length !== 1)
+        throw new TypeError('fhir_single_bundle_attachment_required');
+    const item = payload[0];
+    if (!item || typeof item !== 'object' || Array.isArray(item))
+        throw new TypeError('fhir_bundle_attachment_required');
+    const attachment = item.contentAttachment;
+    if (!attachment || typeof attachment !== 'object' || Array.isArray(attachment))
+        throw new TypeError('fhir_bundle_attachment_required');
+    const candidate = attachment;
+    if (candidate.contentType !== 'application/fhir+json' || typeof candidate.data !== 'string' || !candidate.data) {
+        throw new TypeError('fhir_bundle_attachment_required');
+    }
+    return Object.freeze({ contentType: candidate.contentType, data: candidate.data, ...(typeof candidate.title === 'string' ? { title: candidate.title } : {}) });
+}
+function decodeBase64Utf8(value) {
+    const binary = globalThis.atob(value);
+    return new TextDecoder().decode(Uint8Array.from(binary, character => character.charCodeAt(0)));
+}
+function validateInnerBundle(bundle) {
+    if (bundle.type === 'document' && readBundleResources(bundle)[0]?.resourceType !== 'Composition') {
+        throw new TypeError('fhir_document_composition_first_required');
+    }
+    if (bundle.type === 'batch')
+        validateBatchRequests(bundle);
+}
+function validateBatchRequests(bundle) {
+    for (const entry of bundle.entry ?? []) {
+        if (!entry.request?.method || !entry.request.url)
+            throw new TypeError('fhir_batch_request_required');
+    }
+}

package/dist/group-r5.d.ts

@@ -89,6 +89,12 @@ export type GroupR5ResearchTeam = Readonly<Record<string, unknown> & {
     membership: 'enumerated';
     member: readonly GroupPractitionerRoleMember[];
 }>;
+export type GroupR5ProfessionalServiceTeam = GroupR5ResearchTeam & Readonly<{
+    managingEntity: Readonly<{
+        reference: `Organization/${string}`;
+        type: 'Organization';
+    }>;
+}>;
 /**
  * Normalizes the members used by an enumerated professional research team.
  * Every entity is a native PractitionerRole reference; a Practitioner or an
@@ -101,6 +107,12 @@ export declare function normalizeGroupPractitionerRoleMembers(input: unknown): r
  * properties are rejected at every depth.
  */
 export declare function normalizeGroupR5ResearchTeam(input: unknown): GroupR5ResearchTeam;
+/**
+ * Normalizes a professional team assigned to one Organization department.
+ * `managingEntity` is singular in FHIR R5, so one Group cannot span several
+ * departments. Membership remains descriptive and grants no permission.
+ */
+export declare function normalizeGroupR5ProfessionalServiceTeam(input: unknown): GroupR5ProfessionalServiceTeam;
 /**
  * Projects all populated official resource-specific R5 Group SearchParameters
  * into flat `resource.meta.claims`. A referenced characteristic is indexed by

package/dist/group-r5.js

@@ -131,6 +131,26 @@ export function normalizeGroupR5ResearchTeam(input) {
     const member = normalizeGroupPractitionerRoleMembers(input.member);
     return Object.freeze({ ...input, type: 'practitioner', membership: 'enumerated', member });
 }
+/**
+ * Normalizes a professional team assigned to one Organization department.
+ * `managingEntity` is singular in FHIR R5, so one Group cannot span several
+ * departments. Membership remains descriptive and grants no permission.
+ */
+export function normalizeGroupR5ProfessionalServiceTeam(input) {
+    const team = normalizeGroupR5ResearchTeam(input);
+    const managingEntity = team.managingEntity;
+    if (!isRecord(managingEntity))
+        throw new TypeError('group_professional_service_managing_organization_invalid');
+    const reference = optionalString(managingEntity.reference);
+    const declaredType = optionalString(managingEntity.type);
+    if (!reference || !/^Organization\/[A-Za-z0-9.-]{1,64}$/.test(reference) || (declaredType && declaredType !== 'Organization')) {
+        throw new TypeError('group_professional_service_managing_organization_invalid');
+    }
+    return Object.freeze({
+        ...team,
+        managingEntity: Object.freeze({ reference: reference, type: 'Organization' }),
+    });
+}
 /**
  * Projects all populated official resource-specific R5 Group SearchParameters
  * into flat `resource.meta.claims`. A referenced characteristic is indexed by

package/dist/healthcare-service-specialty-map.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Candidate SNOMED CT C80 to LOINC specialty map supplied for review.
+ *
+ * This is not an official SNOMED or LOINC map. The declared relationship is
+ * preserved so consumers can automate only strict equivalence and present
+ * wider, related, inexact or unmatched rows for professional governance.
+ */
+export declare const ClinicalSpecialtyMappingEquivalence: Readonly<{
+    readonly Equivalent: "equivalent";
+    readonly Wider: "wider";
+    readonly RelatedTo: "relatedto";
+    readonly Inexact: "inexact";
+    readonly Unmatched: "unmatched";
+}>;
+export type ClinicalSpecialtyMappingEquivalenceCode = typeof ClinicalSpecialtyMappingEquivalence[keyof typeof ClinicalSpecialtyMappingEquivalence];
+export type ClinicalSpecialtyMapping = Readonly<{
+    snomedSystem: 'http://snomed.info/sct';
+    snomedCode: string;
+    snomedDisplay: string;
+    loincSystem?: 'http://loinc.org';
+    loincCode?: string;
+    loincDisplay?: string;
+    equivalence: ClinicalSpecialtyMappingEquivalenceCode;
+    automatic: boolean;
+}>;
+export declare const SnomedC80ToLoincSpecialtyConceptMap: readonly ClinicalSpecialtyMapping[];
+/** Returns a portable LOINC specialty only for a strict reviewed equivalence. */
+export declare function findAutomaticLoincSpecialty(snomedCode: string): Readonly<{
+    system: 'http://loinc.org';
+    code: string;
+    display: string;
+}> | undefined;

package/dist/healthcare-service-specialty-map.js

@@ -0,0 +1,151 @@
+/**
+ * Candidate SNOMED CT C80 to LOINC specialty map supplied for review.
+ *
+ * This is not an official SNOMED or LOINC map. The declared relationship is
+ * preserved so consumers can automate only strict equivalence and present
+ * wider, related, inexact or unmatched rows for professional governance.
+ */
+export const ClinicalSpecialtyMappingEquivalence = Object.freeze({
+    Equivalent: 'equivalent',
+    Wider: 'wider',
+    RelatedTo: 'relatedto',
+    Inexact: 'inexact',
+    Unmatched: 'unmatched',
+});
+const E = ClinicalSpecialtyMappingEquivalence.Equivalent;
+const W = ClinicalSpecialtyMappingEquivalence.Wider;
+const R = ClinicalSpecialtyMappingEquivalence.RelatedTo;
+const I = ClinicalSpecialtyMappingEquivalence.Inexact;
+const U = ClinicalSpecialtyMappingEquivalence.Unmatched;
+const suppliedRows = Object.freeze([
+    ['408467006', 'Adult mental illness', 'LP172958-3', 'Mental health', W],
+    ['394577000', 'Anesthetics', 'LP172918-7', 'Anesthesiology', E],
+    ['394578005', 'Audiological medicine', 'LP172919-5', 'Audiology', I],
+    ['421661004', 'Blood banking and transfusion medicine', 'LP172920-3', 'Blood banking and transfusion medicine', E],
+    ['408462000', 'Burns care', 'LP268363-1', 'Burn management', I],
+    ['394579002', 'Cardiology', 'LA7179-0', 'Medicine.cardiology', E],
+    ['394804000', 'Clinical cytogenetics and molecular genetics', 'LP172929-4', 'Clinical genetics', W],
+    ['394580004', 'Clinical genetics', 'LP172929-4', 'Clinical genetics', E],
+    ['394803006', 'Clinical hematology', 'LP175685-9', 'Hematology', I],
+    ['408480009', 'Clinical immunology', 'LP345043-6', 'Immunology', W],
+    ['408454008', 'Clinical microbiology', 'LP208903-7', 'Pathology - Medical microbiology', I],
+    ['394809005', 'Clinical neuro-physiology', 'LP172931-0', 'Clinical neurophysiology', E],
+    ['394592004', 'Clinical oncology', 'LP172901-3', 'Oncology', I],
+    ['394600006', 'Clinical pharmacology', 'LP220238-2', 'Clinical pharmacology', E],
+    ['394601005', 'Clinical physiology', undefined, undefined, U],
+    ['394581000', 'Community medicine', 'LP204156-6', 'Community health care', I],
+    ['408478003', 'Critical care medicine', 'LP172933-6', 'Critical care medicine', E],
+    ['394812008', 'Dental medicine specialties', 'LP172934-4', 'Dentistry', W],
+    ['408444009', 'Dental-General dental practice', 'LP172934-4', 'Dentistry', W],
+    ['394582007', 'Dermatology', 'LP172935-1', 'Dermatology', E],
+    ['408475000', 'Diabetic medicine', 'LP172938-5', 'Diabetology', E],
+    ['410005002', 'Dive medicine', 'LP173035-9', 'Undersea and hyperbaric medicine', I],
+    ['394583002', 'Endocrinology', 'LP172941-9', 'Endocrinology', E],
+    ['419772000', 'Family practice', 'LP172943-5', 'Family medicine', E],
+    ['394584008', 'Gastroenterology', 'LP172945-0', 'Gastroenterology', E],
+    ['408443003', 'General medical practice', 'LP173010-2', 'Primary care', I],
+    ['394802001', 'General medicine', 'LP172946-8', 'General medicine', E],
+    ['394915009', 'General pathology', 'LP172984-9', 'Pathology', I],
+    ['394814009', 'General practice', 'LP173010-2', 'Primary care', I],
+    ['394808002', 'Genito-urinary medicine', 'LP173036-7', 'Urology', W],
+    ['394811001', 'Geriatric medicine', 'LP172947-6', 'Geriatric medicine', E],
+    ['408446006', 'Gynecological oncology', 'LP202989-2', 'Gynecologic oncology', E],
+    ['394586005', 'Gynecology', 'LP221284-5', 'Gynecology', E],
+    ['394916005', 'Hematopathology', 'LP172984-9', 'Pathology', W],
+    ['408472002', 'Hepatology', 'LP172950-0', 'Hepatology', E],
+    ['394597005', 'Histopathology', 'LP208907-8', 'Anatomic pathology', W],
+    ['394598000', 'Immunopathology', 'LP345043-6', 'Immunology', W],
+    ['394807007', 'Infectious diseases', 'LP172951-8', 'Infectious disease', E],
+    ['419192003', 'Internal medicine', 'LP172952-6', 'Internal medicine', E],
+    ['408468001', 'Learning disability', undefined, undefined, U],
+    ['394593009', 'Medical oncology', 'LP175686-7', 'Medical Oncology', E],
+    ['394813003', 'Medical ophthalmology', 'LP172974-0', 'Ophthalmology', W],
+    ['410001006', 'Military medicine', undefined, undefined, U],
+    ['394589003', 'Nephrology', 'LP172962-5', 'Nephrology', E],
+    ['394591006', 'Neurology', 'LP172964-1', 'Neurology', E],
+    ['394599008', 'Neuropathology', 'LP208907-8', 'Anatomic pathology', W],
+    ['394649004', 'Nuclear medicine', 'LP172968-2', 'Nuclear medicine', E],
+    ['408470005', 'Obstetrics', 'LP221283-7', 'Obstetrics', E],
+    ['394585009', 'Obstetrics and gynecology', 'LP172971-6', 'Obstetrics and gynecology', E],
+    ['394821009', 'Occupational medicine', 'LP172972-4', 'Occupational medicine', E],
+    ['422191005', 'Ophthalmic surgery', 'LP172974-0', 'Ophthalmology', W],
+    ['394594003', 'Ophthalmology', 'LP172974-0', 'Ophthalmology', E],
+    ['416304004', 'Osteopathic manipulative medicine', 'LP434767-2', 'Osteopathic medicine', I],
+    ['418960008', 'Otolaryngology', 'LP172980-7', 'Otolaryngology', E],
+    ['394882004', 'Pain management', 'LP172981-5', 'Pain medicine', I],
+    ['394806003', 'Palliative medicine', 'LP172982-3', 'Palliative care', I],
+    ['394588006', 'Pediatric (Child and adolescent) psychiatry', 'LP172922-9', 'Child and adolescent psychiatry', E],
+    ['408459003', 'Pediatric cardiology', 'LP172985-6', 'Pediatric cardiology', E],
+    ['394607009', 'Pediatric dentistry', 'LP172934-4', 'Dentistry', W],
+    ['419610006', 'Pediatric endocrinology', 'LP172989-8', 'Pediatric endocrinology', E],
+    ['418058008', 'Pediatric gastroenterology', 'LP172990-6', 'Pediatric gastroenterology', E],
+    ['420208008', 'Pediatric genetics', 'LP172956-7', 'Medical genetics', W],
+    ['418652005', 'Pediatric hematology', 'LP172991-4', 'Pediatric hematology-oncology', W],
+    ['418535003', 'Pediatric immunology', 'LP345043-6', 'Immunology', W],
+    ['418862001', 'Pediatric infectious diseases', 'LP172992-2', 'Pediatric infectious diseases', E],
+    ['419365004', 'Pediatric nephrology', 'LP172993-0', 'Pediatric nephrology', E],
+    ['418002000', 'Pediatric oncology', 'LP172991-4', 'Pediatric hematology-oncology', I],
+    ['419983000', 'Pediatric ophthalmology', 'LP172974-0', 'Ophthalmology', W],
+    ['419170002', 'Pediatric pulmonology', 'LP172995-5', 'Pediatric pulmonology', E],
+    ['419472004', 'Pediatric rheumatology', 'LP172998-9', 'Pediatric rheumatology', E],
+    ['394539006', 'Pediatric surgery', 'LP172999-7', 'Pediatric surgery', E],
+    ['420112009', 'Pediatric surgery-bone marrow transplantation', 'LP417851-5', 'Bone Marrow Transplant', I],
+    ['409968004', 'Preventive medicine', 'LP173009-4', 'Preventive medicine', E],
+    ['394587001', 'Psychiatry', 'LP173011-0', 'Psychiatry', E],
+    ['394913002', 'Psychotherapy', 'LP173012-8', 'Psychology', R],
+    ['408440000', 'Public health medicine', 'LP173014-4', 'Public health', I],
+    ['418112009', 'Pulmonary medicine', 'LP173015-1', 'Pulmonary disease', I],
+    ['419815003', 'Radiation oncology', 'LP173016-9', 'Radiation oncology', E],
+    ['394914008', 'Radiology', 'LP173018-5', 'Radiology', E],
+    ['408455009', 'Radiology-Interventional radiology', 'LP172896-5', 'Interventional radiology', E],
+    ['394602003', 'Rehabilitation', 'LP173004-5', 'Physical medicine and rehabilitation', I],
+    ['408447002', 'Respite care', 'LP173240-5', 'Respite', R],
+    ['394810000', 'Rheumatology', 'LP173023-5', 'Rheumatology', E],
+    ['408450004', 'Sleep studies', 'LP248728-0', 'Sleep medicine', I],
+    ['408476004', 'Surgery-Bone and marrow transplantation', 'LP417851-5', 'Bone Marrow Transplant', I],
+    ['408469009', 'Surgery-Breast surgery', 'LA7201-2', 'Surgery.breast', E],
+    ['408466002', 'Surgery-Cardiac surgery', 'LP207300-7', 'Cardiac surgery', E],
+    ['408471009', 'Surgery-Cardiothoracic transplantation', 'LP173033-4', 'Transplant surgery', W],
+    ['408464004', 'Surgery-Colorectal surgery', 'LP172932-8', 'Colon and rectal surgery', E],
+    ['408441001', 'Surgery-Dental-Endodontics', 'LP172934-4', 'Dentistry', W],
+    ['408465003', 'Surgery-Dental-Oral and maxillofacial surgery', 'LP172902-1', 'Oral and maxillofacial surgery', E],
+    ['394605001', 'Surgery-Dental-Oral surgery', 'LP172902-1', 'Oral and maxillofacial surgery', I],
+    ['394608004', 'Surgery-Dental-Orthodontics / Dentistry-surgical-Orthodontics', 'LP172934-4', 'Dentistry', W],
+    ['408461007', 'Surgery-Dental-Periodontal surgery', 'LP172934-4', 'Dentistry', W],
+    ['408460008', 'Prosthodontics / surgical-Prosthodontics', 'LP172934-4', 'Dentistry', W],
+    ['394606000', 'Surgery-Dentistry-Restorative dentistry', 'LP172934-4', 'Dentistry', W],
+    ['408449004', 'Surgery-Dentistry--surgical', 'LP172934-4', 'Dentistry', W],
+    ['418018006', 'Surgery-Dermatologic surgery', 'LP172935-1', 'Dermatology', W],
+    ['394604002', 'Surgery-Ear, nose and throat surgery', 'LP172980-7', 'Otolaryngology', I],
+    ['394609007', 'Surgery-general', 'LA7205-3', 'Surgery.general', E],
+    ['408474001', 'Surgery-Hepatobiliary and pancreatic surgery', 'LP172950-0', 'Hepatology', W],
+    ['394610002', 'Surgery-Neurosurgery', 'LP172963-3', 'Neurological surgery', E],
+    ['394611003', 'Surgery-Plastic surgery', 'LP173006-0', 'Plastic surgery', E],
+    ['408477008', 'Surgery-Transplantation surgery', 'LP173033-4', 'Transplant surgery', E],
+    ['394801008', 'Surgery-Trauma and orthopedics', 'LP434806-8', 'Orthopaedic surgery', I],
+    ['408463005', 'Surgery-Vascular', 'LP173039-1', 'Vascular surgery', E],
+    ['419321007', 'Surgical oncology', 'LP207940-0', 'Surgical oncology', E],
+    ['394576009', 'Surgical-Accident & emergency', 'LP172940-1', 'Emergency medicine', I],
+    ['394590007', 'Thoracic medicine', 'LP173031-8', 'Thoracic and cardiac surgery', R],
+    ['409967009', 'Toxicology', 'LP172957-5', 'Medical toxicology', I],
+    ['408448007', 'Tropical medicine', undefined, undefined, U],
+    ['419043006', 'Urological oncology', 'LP173036-7', 'Urology', W],
+    ['394612005', 'Urology', 'LP173036-7', 'Urology', E],
+    ['394733009', 'Medical specialty--OTHER--NOT LISTED', 'LA46-8', 'Other', I],
+    ['394732004', 'Surgical specialty--OTHER-NOT LISTED', 'LA46-8', 'Other', I],
+]);
+export const SnomedC80ToLoincSpecialtyConceptMap = Object.freeze(suppliedRows.map(([snomedCode, snomedDisplay, loincCode, loincDisplay, equivalence = U]) => Object.freeze({
+    snomedSystem: 'http://snomed.info/sct',
+    snomedCode,
+    snomedDisplay,
+    ...(loincCode ? { loincSystem: 'http://loinc.org', loincCode, loincDisplay } : {}),
+    equivalence,
+    automatic: equivalence === E,
+})));
+/** Returns a portable LOINC specialty only for a strict reviewed equivalence. */
+export function findAutomaticLoincSpecialty(snomedCode) {
+    const mapping = SnomedC80ToLoincSpecialtyConceptMap.find(item => item.snomedCode === snomedCode);
+    if (!mapping?.automatic || !mapping.loincCode || !mapping.loincDisplay)
+        return undefined;
+    return Object.freeze({ system: 'http://loinc.org', code: mapping.loincCode, display: mapping.loincDisplay });
+}

package/dist/index.d.ts

@@ -24,3 +24,6 @@ export * from './fhir-tokens.js';
 export * from './related-person.js';
 export * from './imaging-types.js';
 export * from './subscription-r5.js';
+export * from './healthcare-service-specialty-map.js';
+export * from './appointment-communication-test-data.js';
+export * from './encounter-transfer-test-data.js';

package/dist/index.js

@@ -24,3 +24,6 @@ export * from './fhir-tokens.js';
 export * from './related-person.js';
 export * from './imaging-types.js';
 export * from './subscription-r5.js';
+export * from './healthcare-service-specialty-map.js';
+export * from './appointment-communication-test-data.js';
+export * from './encounter-transfer-test-data.js';

package/docs/CLINICAL_TYPED_ACCESSOR_BOUNDARY.md

@@ -0,0 +1,44 @@
+# Clinical Typed Accessor Boundary
+
+This package owns the FHIR-neutral claim and projection layer. It does not own
+the mutable SDK `BundleReader` / `BundleEditor` session API.
+
+The clinical fields required by the current GDC typed editors are already
+canonical here and survive the native FHIR R4 boundary:
+
+| Clinical field | Canonical flat claim | Native FHIR R4 projection |
+|---|---|---|
+| Observed allergy reaction severity | `AllergyIntolerance.severity` | `AllergyIntolerance.reaction[].severity` |
+| Medication treatment end | `MedicationStatement.effective-period-end` | `MedicationStatement.effectivePeriod.end` |
+| Immunization administration route | `Immunization.route` | `Immunization.route` |
+| Immunization administration site | `Immunization.site` | `Immunization.site` |
+| Observation reference-range text | `Observation.reference-range-text` | `Observation.referenceRange[].text` |
+
+`fhir-data-utils-ts` therefore must preserve these fields in claim catalogs,
+FHIR converters and resource graphs. It must not copy the GDC SDK's mutable
+editor classes or transport-aware Bundle session behavior.
+
+The layer split is:
+
+```text
+fhir-data-utils-ts
+  canonical claims + R4/R5/R6 import/export
+        ↓
+sos-data-utils-ts
+  product-neutral multichannel field schemas
+        ↓
+sos-sdk-core-ts / sos-sdk-node-ts
+  shared orchestration and runtime adapters
+        ↓
+vet-* / uhc-*
+  product forms, portal editors and telephone/chat dialogue
+```
+
+When Vet or UHC adds a visual, chat or telephone editor for one of these
+fields, it must consume the canonical claim key from this package. It must not
+maintain a second literal, converter or incompatible getter/setter model.
+
+The mutable GDC Bundle API remains documented separately in
+[`gdc-common-utils-ts`](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/docs/101-CLINICAL-ENTRY-GETTERS-SETTERS.md)
+and exposed to Node applications by
+[`gdc-sdk-node-ts`](https://github.com/Global-DataCare/gdc-sdk-node-ts/blob/main/docs/101-CLINICAL-ENTRY-GETTERS-SETTERS.md).