fhir-data-utils-ts 0.4.0 → 0.6.0

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,5 @@ 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';

package/dist/index.js

@@ -24,3 +24,5 @@ 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';

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).

package/docs/COMMUNICATION_BUNDLE_CONTRACT.md

@@ -0,0 +1,61 @@
+# Communication Bundle contract
+
+Every cross-participant clinical or administrative exchange uses the same
+two-level FHIR envelope. This is the portable contract for Vet, UHC and
+SOSChain channels; HTTP, DIDComm, encryption and recipient resolution remain
+in their owning SDK or service.
+
+```text
+outer Bundle (type=batch)
+└── Communication
+    └── payload.contentAttachment
+        ├── contentType = application/fhir+json
+        └── data = base64(inner Bundle)
+            ├── type=document | batch | collection
+            └── Appointment, DocumentReference, Observation, ...
+```
+
+The outer batch is the delivery command. The Communication supplies sender,
+recipient, subject, status and conversation context. Its single attachment is
+always the inner Bundle. A PDF, image, audio file or `text/calendar` event is
+not another direct Communication attachment: it is a `DocumentReference`
+resource inside the inner Bundle. This keeps one entry point for parsing,
+authorization, persistence and audit regardless of channel.
+
+Inner Bundle types keep their ordinary FHIR meaning:
+
+- `document` starts with `Composition` and represents an attested document;
+- `batch` contains executable entries and every entry has `request.method` and
+  `request.url`;
+- `collection` groups related resources without execution or document order.
+
+## Neutral tools and high-level ownership
+
+`fhir-data-utils-ts` owns only the FHIR tools. It validates and projects a
+received exchange without owning mutable application sessions:
+
+```ts
+import { readCommunicationBundlePayloads } from 'fhir-data-utils-ts'
+
+const payloads = readCommunicationBundlePayloads(receivedOuterBatch)
+const innerBundle = payloads[0].bundle
+```
+
+The validator fails closed when the outer resource is not a batch Bundle, an outer
+batch entry lacks its request, the Communication has anything other than one
+FHIR Bundle attachment, or the inner Bundle violates its declared type.
+
+`sos-sdk-core` owns the high-level Bundle and Communication editor/reader used
+by SOS, Vet and UHC. `sos-data-utils` owns its cross-sector input contracts and
+fixtures. The historical `gdc-*` editors remain compatibility surfaces until
+their consumers migrate; this package neither imports nor wraps them.
+
+At the GW persistence boundary, the validated native resources are projected
+to independent `resource.meta.claims` rows. Direct flat-claim CRUD is an
+internal storage operation; it is not a replacement wire format for this
+cross-participant exchange contract.
+
+`projectAppointmentCommunicationBatchToFlatGraph(...)` is the first typed
+projection using this boundary. It preserves Appointment timing and references
+and emits the calendar DocumentReference independently. Consumers must not
+decode the attachment or recreate these claims with literals.

package/docs/HEALTHCARE_SERVICE_DEPARTMENT_CATALOG.md

@@ -0,0 +1,190 @@
+# Organization departments and healthcare-service catalogs
+
+This contract keeps four different concepts separate:
+
+1. A legal provider is a FHIR `Organization`.
+2. A suborganization or department is another `Organization` whose
+   `partOf` references exactly one parent Organization.
+3. An offered capability is a `HealthcareService` whose `providedBy`
+   references the department that provides it.
+4. A physical or virtual delivery place is a `Location`; one
+   `HealthcareService` can reference several Locations.
+
+A department and every offered `HealthcareService` remain distinct FHIR
+resources. A claims-first directory projects one
+`Organization/<department-id>` and one `HealthcareService/<service-id>` per
+offered service. A blood bank can therefore expose blood donation and plasma
+donation independently. Each service can own different Location references and
+be the actor of a different Schedule; Slot duration and availability follow
+that Schedule rather than the department.
+
+`buildServiceScheduleFlatGraph(...)` implements that boundary. It emits one
+independent claims-first `Schedule` plus independent `Slot` rows. A 15-minute
+blood-donation interval and a one-hour plasma-donation interval are represented
+by different `Slot.start`/`Slot.end` pairs; duration is never an invented flat
+claim. `Schedule.actor` contains the applicable `HealthcareService` and
+`Location`, while `Schedule.service-type-reference` retains the exact service.
+
+```ts
+const bloodAvailability = buildServiceScheduleFlatGraph({
+  scheduleId: 'blood-donation-weekday',
+  scheduleIdentifier: 'urn:uuid:blood-donation-weekday',
+  name: 'Blood donation weekday schedule',
+  healthcareServiceReference: 'HealthcareService/blood-donation',
+  locationReference: 'Location/blood-donation-room',
+  serviceType: 'http://terminology.hl7.org/CodeSystem/service-type|117',
+  planningHorizon: { start: '2026-10-01', end: '2026-10-31' },
+  slots: [{
+    slotId: 'blood-20261001-0900',
+    slotIdentifier: 'urn:uuid:blood-20261001-0900',
+    status: 'free',
+    start: '2026-10-01T09:00:00-07:00',
+    end: '2026-10-01T09:15:00-07:00',
+  }],
+})
+```
+
+The adapters use the published R5 `CodeableReference(HealthcareService)` shape
+for `Schedule.serviceType` and `Slot.serviceType`. Schedule and Slot remain
+separate resources because slots change more frequently than their planning
+container.
+
+## Reservable capacity inside one place
+
+A public donation or extraction point is a parent `Location`. Each independently
+reservable room, booth, chair or bed is a child `Location.partOf` that parent.
+`buildSchedulableLocationFlatResource(...)` creates those child Locations; a
+clone may reuse coordinates but must use a new Location id and identifier.
+
+Equipment is not disguised as a place. An apheresis machine is a FHIR `Device`.
+The Schedule's actor list combines the offered `HealthcareService` with every
+resource that must be available together, for example:
+
+```text
+HealthcareService/plasma-donation
+Location/plasma-donation-station-1
+Device/apheresis-machine-1
+PractitionerRole/plasma-professional-1
+```
+
+Closing one station suspends its Location or blocks/deactivates its Schedule;
+it does not cancel sibling stations. FHIR R4 materializes the governed physical
+coding as `Location.physicalType`; R5 materializes it as `Location.form`.
+
+## Equipment calibration and authorization
+
+A machine used as schedule capacity is still a stable `Device`. Its lifecycle
+has two independent evidence streams:
+
+- `buildDeviceCalibrationFlatGraph(...)` records the completed technical work
+  as a `Procedure` whose subject and focal device are the machine, records the
+  corresponding `DeviceMetric.calibration` state/time, and can attach a
+  `DocumentReference` carrying the certificate hash. The maintenance
+  Organization and acting PractitionerRole are performers, not public
+  regulators.
+- `buildDeviceOperatingAuthorizationFlatResource(...)` records an R5
+  `RegulatedAuthorization` issued by the regulator to the holder for the
+  installed Location, DeviceDefinition, Organization or governed activity.
+  FHIR R5 does not allow an individual Device instance as that resource's
+  subject, so installation-specific authorization targets the installed
+  Location and retains the individual Device through the associated evidence
+  graph.
+
+Both builders emit only minimal resource identity and `resource.meta.claims`.
+The product authorization layer must validate the submitting organization's
+credential, the acting role, jurisdiction and current assignment; this neutral
+package deliberately does not decide whether an assistant, laboratory
+technician, maintenance technician or inspector is permitted. Scheduling may
+derive machine eligibility only after authoritative readback shows an active
+Device, a current required calibration and a valid operating authorization.
+It must not trust a browser-supplied `available` boolean.
+
+`buildDepartmentServicesFlatGraph(...)` authors the department row followed by
+one row for every service. Its input accepts complete `system|value`
+identifiers, complete `system|code` service/category/specialty tokens and typed
+`Organization/...` or `Location/...` references. It rejects bare split
+fragments and duplicate service ids. The builder writes only `resourceType`,
+`id` and `meta.claims`; it never persists a nested FHIR resource.
+
+```ts
+const [department, bloodDonation, plasmaDonation] = buildDepartmentServicesFlatGraph({
+  departmentId: 'blood-bank',
+  departmentIdentifier: 'https://example.invalid/departments|blood-bank',
+  parentOrganizationReference: 'Organization/provider',
+  name: 'Blood bank',
+  services: [{
+    serviceId: 'blood-donation',
+    serviceIdentifier: 'https://example.invalid/services|blood-donation',
+    name: 'Blood donation',
+    serviceType: ['https://example.invalid/CodeSystem/service-type|blood-donation'],
+    locationReferences: ['Location/blood-donation-room'],
+  }, {
+    serviceId: 'plasma-donation',
+    serviceIdentifier: 'https://example.invalid/services|plasma-donation',
+    name: 'Plasma donation',
+    serviceType: ['https://example.invalid/CodeSystem/service-type|plasma-donation'],
+    locationReferences: ['Location/plasma-donation-room'],
+  }],
+})
+```
+
+Two service Locations may carry identical coordinates and copied public media
+when they describe separate operational rooms or check-in configurations. They
+must still have distinct Location identities if schedules or instructions
+differ. If the physical delivery place is genuinely the same resource, both
+services may reference that one Location instead.
+
+## Claims-first boundary
+
+`HealthcareServiceClaim` contains the complete resource-specific FHIR R4
+search surface. `healthcareServiceFlatToFhirR4` and
+`healthcareServiceFhirR4ToFlat` are the only native-R4 adapter boundary.
+Repeatable coding identities remain complete `system|code` tokens; labels are
+resolved by the terminology service and are not trusted storage identity.
+`HealthcareService.comment` and R5 `Organization.description` are governed
+materialization claims, but are not falsely advertised as R4 SearchParameters.
+
+`materializeClaimsFirstResourceToFhirR5(...)` accepts only minimal resource
+identity plus `resource.meta.claims`. It rejects nested native FHIR fields and
+materializes Organization, HealthcareService, Location, Schedule or Slot only for export,
+interop, hashing or credential generation. The resulting R5 object is never
+persisted as a second business source of truth.
+
+`LocationClaim` also preserves the official WGS84 longitude, latitude and
+optional altitude needed by a marketplace. Schema.org `Place.image`,
+Organization logos and governed object-storage evidence remain downstream
+catalog concerns because FHIR R4 `Location` has no native image field.
+
+## Professional group boundary
+
+`normalizeGroupR5ProfessionalServiceTeam` requires one singular
+`Group.managingEntity` reference to one department Organization. A
+professional can belong to several Groups, but one Group cannot span several
+departments in this initial contract. Group membership is descriptive and
+does not grant read, search, appointment, break-glass or communication access.
+
+The department needs no independent DID document merely to own a Group or
+HealthcareService. A stable registered Group endpoint can receive a reply for
+the unit. Transport sender, clinical-document author and professional attester
+remain different identities:
+
+- product policy may set the legal Organization as `Composition.author`;
+- the acting `PractitionerRole` is the professional attester;
+- the authenticated employee/device is transport audit evidence; and
+- a reply is addressed to the Group endpoint, not authored by the Group.
+
+Those authorization, endpoint-registration and authorship policies belong to
+the BFF/high-level SDK, not this neutral package.
+
+## C80 to LOINC candidate mapping
+
+`SnomedC80ToLoincSpecialtyConceptMap` preserves the supplied 115 distinct C80
+rows and their reviewed relationship to LOINC Subject Matter Domain or
+LL402-9 codes. It is candidate evidence, not an official SNOMED or LOINC map.
+Only rows explicitly classified as strict `equivalent` are returned by
+`findAutomaticLoincSpecialty`. Wider, related, inexact and unmatched rows must
+remain visible for terminology governance and are never applied automatically.
+
+Service type and clinical specialty are not interchangeable. For example,
+respite is retained as a related type-of-service candidate rather than being
+silently promoted to a specialty.

package/docs/UHC_FHIR_UTILS_MIGRATION.md

@@ -22,6 +22,7 @@ and transport assumptions must not be copied.
 | Old area | Decision | Current destination or gate |
 | --- | --- | --- |
 | `Bundle` and `Composition` traversal | Rewrite from tests | Neutral graph and explicit R4/R5/R6 adapters; preserve author, attester and section boundaries |
+| `gdc-common-utils-ts` Communication attached-Bundle editor/reader | Preserve as read-only migration evidence | Neutral validation/projection tools live here; the replacement high-level editor/reader belongs to `sos-sdk-core`, with shared input contracts in `sos-data-utils` |
 | `CodeableConcept`, `Identifier`, `Reference`, `Quantity` | Rewrite and reuse behavior | Small typed value modules with round-trip tests |
 | `Observation` and resource parameter models | Rewrite | Canonical claim catalogs plus version-specific projection adapters |
 | `Parameters` conversion | Rewrite | A typed FHIR Parameters module; never a transport-specific envelope |
@@ -45,8 +46,15 @@ and transport assumptions must not be copied.
 | `uhc-fhir-utils-typescript` imaging | DICOMDIR structural types only | Byte parsing and pixel extraction require a separately versioned imaging package |
 | `sos-data-utils-ts` | Cross-sector terminology contract and fixtures, Immunization graph and reminder planning | SOS authorization, repository and emergency policy |
 | `vet-data-utils-ts` | Product-neutral FHIR R5 Group and ResearchStudy contracts/search projections | Animal identity, veterinary sections, species, insurance, payment and other Vet policy |
+| Provider catalogs | R4 HealthcareService claims/converter, geocoded Location claims, one-department professional Group normalization and reviewed C80-to-LOINC candidate mappings | Schema.org images/logo storage, marketplace sector policy, endpoint authorization and communication routing |
 | UHC/Vet SDKs | No transport client was copied | SMART clients, Oracle clients, BFF calls and product workflows remain SDK responsibilities |
 
+The frozen `gdc-*` implementation remains compatibility evidence. New Vet,
+UHC and SOS code uses the replacement high-level API in `sos-sdk-core`, which
+composes the neutral tools exported here. Neither shared replacement package
+imports `gdc-*`. DIDComm wrapping, post-quantum encryption, endpoint selection
+and delivery retries remain in the SDK/service layer.
+
 The migration surface is executable rather than documentary only:
 
 - every migrated claim family has a named catalog and shared list helpers;
@@ -56,10 +64,21 @@ The migration surface is executable rather than documentary only:
   searchable metadata without embedding DICOM object bytes;
 - FHIR primitives, typed searches, Bundle traversal and fallback conversion
   have strict success and rejection tests;
+- Communication exchange is authored and read only as outer batch Bundle to
+  Communication to inner document/batch/collection Bundle, with files modeled
+  as inner DocumentReference resources;
 - Immunization graphs and reminders live once under `src/builders/`; the former
   root modules are deprecated re-export shims;
 - Group and ResearchStudy expose named claim constants, preserve member/party
-  correlation as separate rows and reject authorization-shaped data; and
+  correlation as separate rows and reject authorization-shaped data;
+- Organization departments remain distinct from offered HealthcareServices;
+  every independently schedulable service keeps its own stable identity and
+  Location references, while professional Group ownership remains explicit;
+- `buildServiceScheduleFlatGraph(...)` and the R5 Schedule/Slot adapters keep
+  per-service planning horizons and slot intervals shared between Vet and UHC;
+- schedulable child Locations preserve `partOf`, while Schedule actors can
+  combine the service with Location, Device and PractitionerRole capacity;
+  and
 - `npm run check` enforces minimum line, function and branch coverage across
   converters, builders and core FHIR modules.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhir-data-utils-ts",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "FHIR-version-neutral flat-claim and SearchParameter data utilities",
   "license": "Apache-2.0",
   "type": "module",
@@ -103,6 +103,10 @@
       "types": "./dist/group-r5.d.ts",
       "default": "./dist/group-r5.js"
     },
+    "./healthcare-service-specialty-map": {
+      "types": "./dist/healthcare-service-specialty-map.d.ts",
+      "default": "./dist/healthcare-service-specialty-map.js"
+    },
     "./research-study-r5": {
       "types": "./dist/research-study-r5.d.ts",
       "default": "./dist/research-study-r5.js"