fhir-data-utils-ts 0.3.7 → 0.6.0

package/.codex/skills/govern-fhir-data-utilities/SKILL.md

@@ -29,10 +29,45 @@ description: Complete or audit migrations, claim catalogs, converters, builders,
   projection. Do not invent resource-specific scalar aliases for indexing.
 - Keep Group membership and ResearchStudy associated parties descriptive;
   neither is a Consent, SMART scope or authorization grant.
+- Keep legal Organizations, department Organizations, HealthcareServices and
+  Locations distinct. A professional Group has one department managingEntity;
+  endpoint routing and access remain downstream policy.
+- Build a department and all independently schedulable offered services with
+  `buildDepartmentServicesFlatGraph(...)`; require complete identifier and
+  coding tokens plus typed references, and persist one Organization plus one
+  claims-first HealthcareService row per service.
+- Keep `Schedule` and `Slot` as independent claims-first resources. A Schedule
+  names its HealthcareService plus all independently required Location, Device
+  or professional actors; every Slot references its Schedule and derives
+  duration only from required start/end instants.
+- Model rooms, booths, chairs and beds as child Locations using `partOf`.
+  Model equipment as Device, never as a synthetic Service or Place. R4
+  `Location.physicalType` and R5 `Location.form` project the same governed
+  version-neutral physical-form claim.
+- Keep equipment calibration and public authorization separate. A calibration
+  is a Procedure focused on the Device, a DeviceMetric calibration state/time
+  and optional DocumentReference evidence. A public operating approval is an
+  R5 RegulatedAuthorization whose holder and regulator are distinct. Neither
+  record grants the submitter authority, and neither is collapsed into the
+  Schedule or a browser-authored availability flag.
+- Treat minimal identity plus `resource.meta.claims` as the only canonical
+  persisted resource representation. R4/R5 materializers keep each department
+  and service id independent; the native result is an adapter output for
+  interop, hashing or credentials, never a parallel stored source of truth.
+- Preserve terminology-map relationship evidence. Only a strict reviewed
+  equivalence may be selected automatically; wider, related, inexact and
+  unmatched mappings require terminology governance.
 - Keep native R5 SubscriptionTopic/Subscription configuration and notification
   Bundle parsing separate from the claims-first Communication being delivered.
   This package owns their reusable types and validation, never HTTP delivery,
   subscriber persistence, authentication or product notification policy.
+- Validate and project the canonical outer `Bundle[type=batch]` ->
+  `Communication` -> inner `Bundle[type=document|batch|collection]` structure
+  here, but keep the cross-product high-level editor/reader in `sos-sdk-core`
+  and its data contracts in `sos-data-utils`. Neither replacement package may
+  import frozen `gdc-*`. Arbitrary files are DocumentReference entries in the
+  inner Bundle, never a second direct Communication attachment. Direct
+  flat-claim CRUD is an internal persistence boundary, not this wire format.
 - Keep ImagingStudy searchable metadata, clinical references and protected
   endpoint references in neutral flat claims. DICOM parsing, pixels and object
   storage remain in a separately versioned imaging/storage package.

package/.codex/skills/govern-fhir-observation-components/SKILL.md

@@ -53,6 +53,17 @@ description: Implement or audit neutral FHIR Observation claim catalogs, vital-s
   copy `Observation.*`, LOINC, UCUM or category strings into portals,
   assistants, tests or snippets.
 - Keep displays separate from `system|code` tokens and local-language text.
+- For repeated vital signs, keep every raw reading as `registered`, require the
+  configured cadence before deriving a `preliminary` mean, and preserve the
+  source links through `Observation.derived-from`.
+- Persist the EventTiming bucket through the canonical
+  `Observation.date-when` claim. Do not infer MORN/EVE from a server time zone.
+- Build one preliminary Composition per explicit local date and IANA time
+  zone. Only authorized confirmation returns a final daily document with a
+  professional attester and final top-level Observations.
+- Keep ledger hashing, individual-index writes, Digital Twin materialization
+  and research eligibility outside this neutral package. A final graph is data
+  state, not authorization for those side effects.
 
 ## Change with TDD
 

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## Unreleased
+
+## 0.6.0 - 2026-09-29
+
+- Add canonical two-level Communication Bundle validation tools recovered from
+  the frozen shared implementation: outer batch Bundle, one FHIR Bundle
+  attachment per Communication, and validated document/batch/collection inner
+  Bundles. Reject direct clinical or binary Communication payloads while
+  leaving high-level mutable editors to `sos-sdk-core`.
+- Add a typed Appointment exchange projection that preserves start/end,
+  participants, slots and supporting information while keeping an ICS calendar
+  file as an independent DocumentReference flat-claim resource.
+
+## 0.5.0 - 2026-09-29
+
+- Add claims-first equipment compliance graphs: technical calibration as a
+  Device-focused Procedure plus DeviceMetric state and optional hashed
+  DocumentReference evidence, and public operating approval as a separate R5
+  RegulatedAuthorization. Keep these records independent from Schedule
+  availability and downstream role authorization.
+
+- Add official R5 Schedule and Slot search-claim catalogs, claims-first
+  materializers and a service availability graph builder. Preserve independent
+  HealthcareService/Location actors and derive booking duration from each
+  Slot start/end interval.
+- Add schedulable child Location construction and composite Schedule actors for
+  Location, Device and PractitionerRole capacity. Correct R5 Location
+  projection to use `form` instead of the removed R4 `physicalType` field.
+- Add a strict claims-first department/service graph builder that emits a
+  department Organization and one independently schedulable HealthcareService
+  per offered service, with complete identifiers, coding tokens and Location
+  references. Add governed
+  R5 Organization description and HealthcareService comment projection without
+  presenting either as an R4 SearchParameter.
+
+- Added strict claims-first R5 materialization for Organization,
+  HealthcareService and Location. Canonical `system|value` identifiers and
+  `system|code` codings now retain their systems, while nested native FHIR
+  beside `resource.meta.claims` is rejected.
+
+- Document the ownership boundary for allergy reaction severity, medication
+  treatment period, immunization route/site and Observation reference-range
+  text across neutral FHIR projections, SOS multichannel schemas and typed SDK
+  Bundle editors.
+
+- Add the complete official FHIR R4 HealthcareService search-claim catalog and
+  a lossless R4 converter that keeps provider departments and services distinct.
+- Preserve Location WGS84 coordinates and require each professional service
+  Group to have one managing department Organization without granting access.
+- Add the supplied 115-row SNOMED CT C80 to LOINC specialty candidate map;
+  only strict equivalence is eligible for automatic selection.
+
+## 0.4.0 - 2026-09-27
+
+- Add the neutral daily vital-sign document lifecycle: registered raw readings,
+  preliminary three-reading means, MORN/EVE EventTiming, one preliminary daily
+  Composition and explicit professional finalization.
+- Preserve mean provenance through `Observation.derived-from`, validate the
+  local calendar day with an IANA time zone and project Composition status plus
+  section entry references at the FHIR R4 boundary.
+- Add governed UCUM Fahrenheit and avoirdupois-pound input alongside Celsius
+  and kilograms without moving regional UI preferences into shared FHIR data.
+
 ## 0.3.7 - 2026-09-26
 
 - Add claims-first FHIR contracts for Location-linked Encounter care journeys,

package/README.md

@@ -36,12 +36,37 @@ independent `DocumentReference`. Preliminary reports can be reviewed and
 securely exchanged; ledger and research eligibility remain downstream policy
 and normally require the confirmed final lifecycle state.
 
+Provider catalogs keep legal Organizations, department Organizations,
+HealthcareServices and Locations separate. A department uses
+`Organization.part-of`; each offered service references its provider through
+`HealthcareService.organization`, and may reference several geocoded
+Locations. Professional Groups are bound to one department without turning
+membership into authorization. See
+[Organization departments and healthcare-service catalogs](docs/HEALTHCARE_SERVICE_DEPARTMENT_CATALOG.md).
+
+Cross-participant data always uses an outer FHIR batch Bundle containing
+Communication entries. Each Communication carries exactly one
+`application/fhir+json` inner document, batch or collection Bundle; arbitrary
+files are DocumentReference resources inside that Bundle. This package owns
+strict parsing and projection tools; the shared high-level editor/reader belongs
+to `sos-sdk-core`, with cross-sector contracts in `sos-data-utils`. See
+[Communication Bundle contract](docs/COMMUNICATION_BUNDLE_CONTRACT.md).
+
+Reservable equipment remains a `Device` actor of its service-specific
+`Schedule`. Technical calibration is recorded as a `Procedure` focused on that
+Device plus the current `DeviceMetric.calibration` state and an optional
+`DocumentReference` evidence hash. A public operating approval is a separate
+R5 `RegulatedAuthorization`; it is never inferred from calibration or from an
+employee role.
+
 ## Public contract
 
 The root export and stable subpaths provide:
 
 - strict version-neutral FHIR datatypes, value/token helpers, Bundle traversal
   and typed search parsing/building;
+- the canonical Communication Bundle validation boundary and Appointment
+  exchange projection, including calendar DocumentReference evidence;
 - complete flat-claim catalogs and claim helpers for the resource families
   formerly scattered through `gdc-common-utils-ts`;
 - explicit R4/R5 conversion adapters, including Consent and PractitionerRole;
@@ -72,6 +97,11 @@ Use `fhir-data-utils-ts/claims`, `/converters`, `/fhir-bundle`,
 `/fhir-search-parameters`, `/clinical-terminology`, `/group-r5` or
 `/research-study-r5` as appropriate.
 
+The `/healthcare-service-specialty-map` subpath exposes the complete supplied
+C80-to-LOINC candidate mapping. Only strict equivalence can be selected
+automatically; wider, related, inexact and unmatched candidates remain review
+evidence.
+
 Repeatable `CodeableConcept.coding[]` identities are serialized in the owning
 token claim as a comma-separated list of complete `system|code` tokens. The
 first `*-display` remains source evidence for compatibility; authoritative
@@ -105,10 +135,24 @@ without inventing a new flat-claim family for each scale.
 `Observation.user-selected` provenance flag. Consumers submit its `entries`
 without reconstructing component claims or relationships.
 
+Repeated morning/evening capture uses `buildRepeatedVitalSignAverage`: three
+two-minute raw readings remain `registered`, while their derived arithmetic
+mean is `preliminary`. `buildVitalSignDailyDocument` groups the day's top-level
+Observations under one preliminary Composition; only
+`finalizeVitalSignDailyDocument` returns a final Composition and final
+top-level Observations with a professional attester. Ledger hashing, index
+updates, Digital Twin and research eligibility remain owning-service policy.
+See [Daily vital-sign document lifecycle](docs/VITAL_SIGN_DAILY_DOCUMENT.md).
+
 See [the UHC FHIR utilities migration](docs/UHC_FHIR_UTILS_MIGRATION.md) for the
 reuse/rewrite/retire inventory and the rule for moving frozen contracts without
 changing any `gdc-*` repository.
 
+See [Clinical typed accessor boundary](docs/CLINICAL_TYPED_ACCESSOR_BOUNDARY.md)
+for the exact division between canonical clinical claims/converters here,
+shared SOS multichannel schemas and the mutable Bundle getters/setters exposed
+by runtime SDKs.
+
 ## Coding review for imported clinical text
 
 DataConv, Vet and UHC share one neutral review contract from

package/dist/appointment-communication-test-data.d.ts

@@ -0,0 +1,63 @@
+import type { FhirBundle, FhirResource } from './fhir-types.js';
+/** Repository-safe reusable evidence for appointment Bundle and calendar tests. */
+export declare const FHIR_APPOINTMENT_COMMUNICATION_TEST_DATA: Readonly<{
+    release: "r5";
+    start: "2026-10-05T16:00:00.000Z";
+    end: "2026-10-05T16:30:00.000Z";
+    communicationId: "communication-one";
+    subjectReference: "Patient/animal-one";
+    senderReference: "Organization/clinic-one";
+    recipientReference: "RelatedPerson/controller-one";
+    appointmentReference: "Appointment/appointment-one";
+    calendarData: string;
+    appointment: Readonly<{
+        [key: string]: unknown;
+        resourceType: string;
+        id?: string;
+        language?: string;
+        meta?: Readonly<Record<string, unknown>>;
+        contained?: readonly FhirResource[];
+    }>;
+    calendarDocument: Readonly<{
+        [key: string]: unknown;
+        resourceType: string;
+        id?: string;
+        language?: string;
+        meta?: Readonly<Record<string, unknown>>;
+        contained?: readonly FhirResource[];
+    }>;
+    communication: Readonly<{
+        [key: string]: unknown;
+        resourceType: string;
+        id?: string;
+        language?: string;
+        meta?: Readonly<Record<string, unknown>>;
+        contained?: readonly FhirResource[];
+    }>;
+    outerBatch: FhirBundle;
+    outerBatchWithInvalidDocument: FhirBundle;
+    outerBatchWithInvalidInnerBatch: FhirBundle;
+    outerBatchWithBareAppointment: Readonly<{
+        resourceType: "Bundle";
+        type: "batch";
+        entry: {
+            resource: {
+                payload: {
+                    contentAttachment: {
+                        contentType: string;
+                        data: string;
+                    };
+                }[];
+                resourceType: string;
+                id?: string;
+                language?: string;
+                meta?: Readonly<Record<string, unknown>>;
+                contained?: readonly FhirResource[];
+            };
+            request: {
+                method: string;
+                url: string;
+            };
+        }[];
+    }>;
+}>;

package/dist/appointment-communication-test-data.js

@@ -0,0 +1,77 @@
+const APPOINTMENT_ID = 'appointment-one';
+const COMMUNICATION_ID = 'communication-one';
+const CALENDAR_DOCUMENT_ID = 'appointment-calendar-one';
+const SUBJECT_REFERENCE = 'Patient/animal-one';
+const SENDER_REFERENCE = 'Organization/clinic-one';
+const RECIPIENT_REFERENCE = 'RelatedPerson/controller-one';
+const APPOINTMENT_REFERENCE = `Appointment/${APPOINTMENT_ID}`;
+const CALENDAR_DOCUMENT_REFERENCE = `DocumentReference/${CALENDAR_DOCUMENT_ID}`;
+const APPOINTMENT_START = '2026-10-05T16:00:00.000Z';
+const APPOINTMENT_END = '2026-10-05T16:30:00.000Z';
+const CALENDAR_DATA = encodeBase64Utf8('BEGIN:VCALENDAR\r\nVERSION:2.0\r\nBEGIN:VEVENT\r\nDTSTART:20261005T160000Z\r\nDTEND:20261005T163000Z\r\nEND:VEVENT\r\nEND:VCALENDAR\r\n');
+const APPOINTMENT = Object.freeze({
+    resourceType: 'Appointment', id: APPOINTMENT_ID, identifier: [{ value: APPOINTMENT_ID }], status: 'booked',
+    start: APPOINTMENT_START, end: APPOINTMENT_END,
+    participant: [{ actor: { reference: SUBJECT_REFERENCE }, status: 'accepted' }, { actor: { reference: 'PractitionerRole/veterinarian-one' }, status: 'accepted' }, { actor: { reference: 'Location/consultation-one' }, status: 'accepted' }],
+    slot: [{ reference: 'Slot/consultation-one' }], supportingInformation: [{ reference: CALENDAR_DOCUMENT_REFERENCE }],
+});
+const CALENDAR_DOCUMENT = Object.freeze({
+    resourceType: 'DocumentReference', id: CALENDAR_DOCUMENT_ID, identifier: [{ value: CALENDAR_DOCUMENT_ID }], status: 'current',
+    subject: { reference: SUBJECT_REFERENCE }, context: { related: [{ reference: APPOINTMENT_REFERENCE }] },
+    content: [{ attachment: { contentType: 'text/calendar', data: CALENDAR_DATA, title: 'appointment.ics' } }],
+});
+const INNER_BUNDLE = Object.freeze({ resourceType: 'Bundle', type: 'collection', entry: [{ resource: APPOINTMENT }, { resource: CALENDAR_DOCUMENT }] });
+const COMMUNICATION = Object.freeze({
+    resourceType: 'Communication', id: COMMUNICATION_ID, identifier: [{ value: COMMUNICATION_ID }], status: 'completed',
+    subject: { reference: SUBJECT_REFERENCE }, recipient: [{ reference: RECIPIENT_REFERENCE }], sender: { reference: SENDER_REFERENCE },
+    payload: [{ contentAttachment: { contentType: 'application/fhir+json', data: encodeBase64Utf8(JSON.stringify(INNER_BUNDLE)), title: 'appointment-bundle.json' } }],
+});
+function communicationWithInnerBundle(innerBundle) {
+    return Object.freeze({
+        ...COMMUNICATION,
+        payload: [{ contentAttachment: { contentType: 'application/fhir+json', data: encodeBase64Utf8(JSON.stringify(innerBundle)) } }],
+    });
+}
+function outerBatchWithCommunication(communication) {
+    return Object.freeze({
+        resourceType: 'Bundle',
+        type: 'batch',
+        entry: [{ resource: communication, request: { method: 'POST', url: 'Communication' } }],
+    });
+}
+/** Repository-safe reusable evidence for appointment Bundle and calendar tests. */
+export const FHIR_APPOINTMENT_COMMUNICATION_TEST_DATA = Object.freeze({
+    release: 'r5',
+    start: APPOINTMENT_START,
+    end: APPOINTMENT_END,
+    communicationId: COMMUNICATION_ID,
+    subjectReference: SUBJECT_REFERENCE,
+    senderReference: SENDER_REFERENCE,
+    recipientReference: RECIPIENT_REFERENCE,
+    appointmentReference: APPOINTMENT_REFERENCE,
+    calendarData: CALENDAR_DATA,
+    appointment: APPOINTMENT,
+    calendarDocument: CALENDAR_DOCUMENT,
+    communication: COMMUNICATION,
+    outerBatch: outerBatchWithCommunication(COMMUNICATION),
+    outerBatchWithInvalidDocument: outerBatchWithCommunication(communicationWithInnerBundle(Object.freeze({
+        resourceType: 'Bundle',
+        type: 'document',
+        entry: [{ resource: APPOINTMENT }],
+    }))),
+    outerBatchWithInvalidInnerBatch: outerBatchWithCommunication(communicationWithInnerBundle(Object.freeze({
+        resourceType: 'Bundle',
+        type: 'batch',
+        entry: [{ resource: APPOINTMENT }],
+    }))),
+    outerBatchWithBareAppointment: Object.freeze({
+        resourceType: 'Bundle', type: 'batch', entry: [{ resource: { ...COMMUNICATION, payload: [{ contentAttachment: { contentType: 'application/fhir+json', data: encodeBase64Utf8(JSON.stringify(APPOINTMENT)) } }] }, request: { method: 'POST', url: 'Communication' } }],
+    }),
+});
+function encodeBase64Utf8(value) {
+    const bytes = new TextEncoder().encode(value);
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return globalThis.btoa(binary);
+}

package/dist/builders/department-service-graph.d.ts

@@ -0,0 +1,32 @@
+export type ClaimsFirstGraphResource = Readonly<{
+    resourceType: 'Organization' | 'HealthcareService';
+    id: string;
+    meta: Readonly<{
+        claims: Readonly<Record<string, string | readonly string[]>>;
+    }>;
+}>;
+export type DepartmentServiceInput = Readonly<{
+    serviceId: string;
+    serviceIdentifier: string;
+    name: string;
+    description?: string;
+    serviceCategory?: readonly string[];
+    serviceType: readonly string[];
+    specialty?: readonly string[];
+    locationReferences: readonly string[];
+}>;
+export type DepartmentServicesFlatGraphInput = Readonly<{
+    departmentId: string;
+    departmentIdentifier: string;
+    parentOrganizationReference: string;
+    name: string;
+    description?: string;
+    organizationType?: string;
+    services: readonly DepartmentServiceInput[];
+}>;
+/**
+ * Builds one department Organization and one independent HealthcareService
+ * row per offered service. Schedule actors can therefore target a blood,
+ * plasma or other service independently even when they share a department.
+ */
+export declare function buildDepartmentServicesFlatGraph(input: DepartmentServicesFlatGraphInput): readonly ClaimsFirstGraphResource[];

package/dist/builders/department-service-graph.js

@@ -0,0 +1,102 @@
+import { HealthcareServiceClaim } from '../claims/healthcare-service-claims.js';
+import { OrganizationClaim } from '../claims/organization-claims.js';
+const required = (value, error) => {
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        throw new TypeError(error);
+    return normalized;
+};
+const resourceId = (value) => {
+    const normalized = required(value, 'department_service_id_required');
+    if (!/^[A-Za-z0-9.-]{1,64}$/.test(normalized))
+        throw new TypeError('department_service_id_invalid');
+    return normalized;
+};
+const reference = (value, prefix, error) => {
+    const normalized = required(value, error);
+    if (!normalized.startsWith(`${prefix}/`) || normalized.length === prefix.length + 1)
+        throw new TypeError(error);
+    return normalized;
+};
+const token = (value, error) => {
+    const normalized = required(value, error);
+    const separator = normalized.lastIndexOf('|');
+    if (separator < 1 || separator === normalized.length - 1)
+        throw new TypeError(error);
+    return normalized;
+};
+const tokenList = (values, error, requiredList = false) => {
+    const normalized = Object.freeze((values ?? []).map(value => token(value, error)));
+    if (requiredList && !normalized.length)
+        throw new TypeError(error);
+    return normalized.length ? normalized : undefined;
+};
+const referenceList = (values, prefix, error) => {
+    const normalized = Object.freeze(values.map(value => reference(value, prefix, error)));
+    if (!normalized.length)
+        throw new TypeError(error);
+    return normalized;
+};
+const compactClaims = (claims) => Object.freeze(Object.fromEntries(Object.entries(claims).filter((entry) => entry[1] !== undefined)));
+/**
+ * Builds one department Organization and one independent HealthcareService
+ * row per offered service. Schedule actors can therefore target a blood,
+ * plasma or other service independently even when they share a department.
+ */
+export function buildDepartmentServicesFlatGraph(input) {
+    const departmentId = resourceId(input.departmentId);
+    const departmentIdentifier = token(input.departmentIdentifier, 'department_service_identifier_invalid');
+    const parentOrganizationReference = reference(input.parentOrganizationReference, 'Organization', 'department_service_parent_reference_invalid');
+    const name = required(input.name, 'department_service_name_required');
+    const description = input.description?.trim() || undefined;
+    const organizationType = input.organizationType
+        ? token(input.organizationType, 'department_service_organization_type_invalid')
+        : undefined;
+    const departmentReference = `Organization/${departmentId}`;
+    if (!input.services.length)
+        throw new TypeError('department_services_required');
+    const serviceIds = new Set();
+    const services = input.services.map(service => {
+        const serviceId = resourceId(service.serviceId);
+        if (serviceIds.has(serviceId))
+            throw new TypeError('department_service_id_duplicate');
+        serviceIds.add(serviceId);
+        const serviceIdentifier = token(service.serviceIdentifier, 'department_service_identifier_invalid');
+        const serviceName = required(service.name, 'department_service_name_required');
+        const serviceDescription = service.description?.trim() || undefined;
+        const serviceCategory = tokenList(service.serviceCategory, 'department_service_category_invalid');
+        const serviceType = tokenList(service.serviceType, 'department_service_type_invalid', true);
+        const specialty = tokenList(service.specialty, 'department_service_specialty_invalid');
+        const locationReferences = referenceList(service.locationReferences, 'Location', 'department_service_location_reference_invalid');
+        return Object.freeze({
+            resourceType: 'HealthcareService',
+            id: serviceId,
+            meta: Object.freeze({ claims: compactClaims({
+                    [HealthcareServiceClaim.Identifier]: serviceIdentifier,
+                    [HealthcareServiceClaim.Active]: 'true',
+                    [HealthcareServiceClaim.Organization]: departmentReference,
+                    [HealthcareServiceClaim.ServiceCategory]: serviceCategory,
+                    [HealthcareServiceClaim.ServiceType]: serviceType,
+                    [HealthcareServiceClaim.Specialty]: specialty,
+                    [HealthcareServiceClaim.Location]: locationReferences,
+                    [HealthcareServiceClaim.Name]: serviceName,
+                    [HealthcareServiceClaim.Comment]: serviceDescription,
+                }) }),
+        });
+    });
+    return Object.freeze([
+        Object.freeze({
+            resourceType: 'Organization',
+            id: departmentId,
+            meta: Object.freeze({ claims: compactClaims({
+                    [OrganizationClaim.Identifier]: departmentIdentifier,
+                    [OrganizationClaim.Active]: 'true',
+                    [OrganizationClaim.Type]: organizationType,
+                    [OrganizationClaim.Name]: name,
+                    [OrganizationClaim.Description]: description,
+                    [OrganizationClaim.PartOf]: parentOrganizationReference,
+                }) }),
+        }),
+        ...services,
+    ]);
+}

package/dist/builders/device-compliance-graph.d.ts

@@ -0,0 +1,51 @@
+type FlatResourceType = 'Procedure' | 'DeviceMetric' | 'DocumentReference' | 'RegulatedAuthorization';
+export type DeviceComplianceFlatResource = Readonly<{
+    resourceType: FlatResourceType;
+    id: string;
+    meta: Readonly<{
+        claims: Readonly<Record<string, string>>;
+    }>;
+}>;
+/**
+ * Builds the technical calibration event separately from the current metric state and its evidence.
+ * Performer references are descriptive; product authorization decides which credentialed actor may submit.
+ */
+export declare function buildDeviceCalibrationFlatGraph(input: Readonly<{
+    procedureId: string;
+    procedureIdentifier: string;
+    procedureCode: string;
+    deviceReference: string;
+    metricId: string;
+    metricIdentifier: string;
+    metricType: string;
+    metricUnit?: string;
+    calibrationType: 'unspecified' | 'offset' | 'gain' | 'two-point';
+    calibrationState: 'not-calibrated' | 'calibration-required' | 'calibrated' | 'unspecified';
+    calibrationTime: string;
+    performerReferences: readonly string[];
+    locationReference?: string;
+    evidence?: Readonly<{
+        documentId: string;
+        documentIdentifier: string;
+        contentHash: string;
+        contentType: string;
+    }>;
+}>): readonly DeviceComplianceFlatResource[];
+/** Builds a public-authority operating authorization without conflating it with calibration. */
+export declare function buildDeviceOperatingAuthorizationFlatResource(input: Readonly<{
+    authorizationId: string;
+    identifier: string;
+    subjectReference: string;
+    holderReference: string;
+    regulatorReference: string;
+    type: string;
+    status: string;
+    statusDate: string;
+    validityPeriod: Readonly<{
+        start: string;
+        end: string;
+    }>;
+    region: string;
+    basis: string;
+}>): DeviceComplianceFlatResource;
+export {};

package/dist/builders/device-compliance-graph.js

@@ -0,0 +1,115 @@
+import { DeviceMetricClaim } from '../claims/device-metric-claims.js';
+import { DocumentReferenceClaim } from '../claims/document-reference-claims.js';
+import { ProcedureClaim } from '../claims/procedure-claims.js';
+import { RegulatedAuthorizationClaim } from '../claims/regulated-authorization-claims.js';
+const required = (value, error) => {
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        throw new TypeError(error);
+    return normalized;
+};
+const id = (value) => {
+    const normalized = required(value, 'device_compliance_id_required');
+    if (!/^[A-Za-z0-9.-]{1,64}$/.test(normalized))
+        throw new TypeError('device_compliance_id_invalid');
+    return normalized;
+};
+const reference = (value, resourceType, error) => {
+    const normalized = required(value, error);
+    if (!new RegExp(`^${resourceType}/[A-Za-z0-9.-]+$`).test(normalized))
+        throw new TypeError(error);
+    return normalized;
+};
+const actorReference = (value) => {
+    const normalized = required(value, 'calibration_performer_reference_invalid');
+    if (!/^(?:Practitioner|PractitionerRole|Organization|HealthcareService|Device)\/[A-Za-z0-9.-]+$/.test(normalized)) {
+        throw new TypeError('calibration_performer_reference_invalid');
+    }
+    return normalized;
+};
+const token = (value, error) => {
+    const normalized = required(value, error);
+    const separator = normalized.lastIndexOf('|');
+    if (separator < 1 || separator === normalized.length - 1)
+        throw new TypeError(error);
+    return normalized;
+};
+const instant = (value, error) => {
+    const normalized = required(value, error);
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(normalized))
+        throw new TypeError(error);
+    return normalized;
+};
+const resource = (resourceType, resourceId, claims) => Object.freeze({
+    resourceType,
+    id: id(resourceId),
+    meta: Object.freeze({ claims: Object.freeze(claims) }),
+});
+/**
+ * Builds the technical calibration event separately from the current metric state and its evidence.
+ * Performer references are descriptive; product authorization decides which credentialed actor may submit.
+ */
+export function buildDeviceCalibrationFlatGraph(input) {
+    const deviceReference = reference(input.deviceReference, 'Device', 'device_reference_invalid');
+    const performers = [...new Set(input.performerReferences.map(actorReference))];
+    if (!performers.length)
+        throw new TypeError('calibration_performer_required');
+    const calibrationTime = instant(input.calibrationTime, 'calibration_time_invalid');
+    const reportReference = input.evidence ? `DocumentReference/${id(input.evidence.documentId)}` : undefined;
+    const procedure = resource('Procedure', input.procedureId, {
+        [ProcedureClaim.Identifier]: required(input.procedureIdentifier, 'procedure_identifier_required'),
+        [ProcedureClaim.Status]: 'completed',
+        [ProcedureClaim.Code]: token(input.procedureCode, 'procedure_code_invalid'),
+        [ProcedureClaim.Subject]: deviceReference,
+        [ProcedureClaim.FocalDevice]: deviceReference,
+        [ProcedureClaim.Date]: calibrationTime,
+        [ProcedureClaim.Performer]: performers.join(','),
+        ...(input.locationReference ? { [ProcedureClaim.Location]: reference(input.locationReference, 'Location', 'calibration_location_reference_invalid') } : {}),
+        ...(reportReference ? { [ProcedureClaim.Report]: reportReference } : {}),
+    });
+    const metric = resource('DeviceMetric', input.metricId, {
+        [DeviceMetricClaim.Identifier]: required(input.metricIdentifier, 'metric_identifier_required'),
+        [DeviceMetricClaim.Type]: token(input.metricType, 'metric_type_invalid'),
+        ...(input.metricUnit ? { [DeviceMetricClaim.Unit]: token(input.metricUnit, 'metric_unit_invalid') } : {}),
+        [DeviceMetricClaim.Device]: deviceReference,
+        [DeviceMetricClaim.Category]: 'measurement',
+        [DeviceMetricClaim.CalibrationType]: input.calibrationType,
+        [DeviceMetricClaim.CalibrationState]: input.calibrationState,
+        [DeviceMetricClaim.CalibrationTime]: calibrationTime,
+    });
+    const evidence = input.evidence
+        ? [resource('DocumentReference', input.evidence.documentId, {
+                [DocumentReferenceClaim.Identifier]: required(input.evidence.documentIdentifier, 'calibration_evidence_identifier_required'),
+                [DocumentReferenceClaim.Subject]: deviceReference,
+                [DocumentReferenceClaim.Context]: `Procedure/${procedure.id}`,
+                [DocumentReferenceClaim.ContentHash]: required(input.evidence.contentHash, 'calibration_evidence_hash_required'),
+                [DocumentReferenceClaim.ContentType]: required(input.evidence.contentType, 'calibration_evidence_content_type_required'),
+                [DocumentReferenceClaim.Date]: calibrationTime,
+            })]
+        : [];
+    return Object.freeze([procedure, metric, ...evidence]);
+}
+/** Builds a public-authority operating authorization without conflating it with calibration. */
+export function buildDeviceOperatingAuthorizationFlatResource(input) {
+    const start = required(input.validityPeriod.start, 'authorization_validity_invalid');
+    const end = required(input.validityPeriod.end, 'authorization_validity_invalid');
+    if (Date.parse(end) < Date.parse(start))
+        throw new TypeError('authorization_validity_invalid');
+    const subjectReference = required(input.subjectReference, 'authorization_subject_reference_invalid');
+    if (!/^(?:DeviceDefinition|Organization|Location|ActivityDefinition|PlanDefinition)\/[A-Za-z0-9.-]+$/.test(subjectReference)) {
+        throw new TypeError('authorization_subject_reference_invalid');
+    }
+    return resource('RegulatedAuthorization', input.authorizationId, {
+        [RegulatedAuthorizationClaim.Identifier]: required(input.identifier, 'authorization_identifier_required'),
+        [RegulatedAuthorizationClaim.Subject]: subjectReference,
+        [RegulatedAuthorizationClaim.Type]: token(input.type, 'authorization_type_invalid'),
+        [RegulatedAuthorizationClaim.Region]: token(input.region, 'authorization_region_invalid'),
+        [RegulatedAuthorizationClaim.Status]: required(input.status, 'authorization_status_required'),
+        [RegulatedAuthorizationClaim.StatusDate]: instant(input.statusDate, 'authorization_status_date_invalid'),
+        [RegulatedAuthorizationClaim.ValidityStart]: start,
+        [RegulatedAuthorizationClaim.ValidityEnd]: end,
+        [RegulatedAuthorizationClaim.Basis]: token(input.basis, 'authorization_basis_invalid'),
+        [RegulatedAuthorizationClaim.Holder]: reference(input.holderReference, 'Organization', 'authorization_holder_reference_invalid'),
+        [RegulatedAuthorizationClaim.Regulator]: reference(input.regulatorReference, 'Organization', 'authorization_regulator_reference_invalid'),
+    });
+}

package/dist/builders/index.d.ts

@@ -1,3 +1,6 @@
 export * from './diagnostic-report-graph.js';
+export * from './department-service-graph.js';
+export * from './service-schedule-graph.js';
+export * from './device-compliance-graph.js';
 export * from './immunization-graph.js';
 export * from './immunization-reminders.js';