fhir-data-utils-ts 0.3.6 → 0.4.0

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

@@ -38,6 +38,18 @@ description: Complete or audit migrations, claim catalogs, converters, builders,
   storage remain in a separately versioned imaging/storage package.
 - Preserve `Encounter.appointment`; an Appointment lifecycle transition must
   not sever the encounter from the scheduling event that originated it.
+- Represent actual care movement as independent child Encounters linked with
+  `Encounter.partOf` and their own Location. The graph is descriptive and does
+  not grant family or professional access.
+- Represent resilient emergency intake as a canonical `ServiceRequest` and
+  acknowledgement/triage as a separate durable `Task` focused on it. Never
+  infer authorization from requester, performer or owner references.
+- Represent a population campaign with one `CommunicationRequest` against a
+  frozen enumerated Group snapshot. Consent, exclusions, channel status and
+  eligibility are rechecked per recipient outside this neutral package.
+- Emit coded values as compact `system|code`. Do not create split
+  `code-system`, `code-value` or stored `code-display` claims; preserve local
+  text separately and resolve trusted displays through terminology.
 - Build laboratory panels with `buildDiagnosticReportFlatGraph(...)`.
   `DiagnosticReport.code` is mandatory and names the report/panel; result
   measurements are independent `Observation` entries and formatted PDF/image

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,25 @@
 # Changelog
 
+## 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,
+  emergency ServiceRequest plus triage Task, and Group-snapshot
+  CommunicationRequest campaigns.
+- Add R4 projections for ServiceRequest and CommunicationRequest and preserve
+  `Encounter.partOf` without introducing split coding claims or persisted code
+  displays.
+
 ## 0.3.6 - 2026-09-26
 
 - Add a product-neutral claims-first DiagnosticReport graph builder for coded

package/README.md

@@ -105,6 +105,15 @@ 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.
@@ -150,6 +159,15 @@ its canonical `Communication.recipient` claim.
 coverage over converters, builders and core FHIR utilities. The package also
 tests every stable export subpath. Release validation additionally inspects the
 packed artifact and installs it in an isolated consumer before publication.
+
+## Care, emergency and population-alert graphs
+
+The package provides the neutral FHIR foundation for the three SOSChain
+journeys proven first in VetChain/PetChain: Location-linked Encounter care
+journeys, emergency ServiceRequest plus triage Task, and cohort
+CommunicationRequest against a frozen Group snapshot. See
+[the contract guide](docs/CARE_EMERGENCY_ALERT_CONTRACTS.md). Product policy,
+access, encryption and delivery do not belong in these builders.
 # Coding-review workflow
 
 Imported wording remains in the resource's canonical `*-text` flat claim. Each

package/dist/care-emergency-alert.d.ts

@@ -0,0 +1,70 @@
+import { type FlatClaimResourceEntry } from './flat-claim-resource-graph.js';
+export type ClinicalCoding = Readonly<{
+    system: string;
+    code: string;
+    display?: string;
+    text?: string;
+}>;
+export type EncounterJourneyNode = Readonly<{
+    entryId: string;
+    identifier: string;
+    status: 'planned' | 'arrived' | 'triaged' | 'in-progress' | 'onleave' | 'finished' | 'cancelled';
+    periodStart: string;
+    periodEnd?: string;
+    locationReference: string;
+    type?: ClinicalCoding;
+}>;
+/**
+ * Builds one actual-care Encounter graph from an originating Appointment.
+ * Child service/location encounters inherit subject and provider and reference
+ * the parent with FHIR `Encounter.partOf`; Appointment remains planning input.
+ */
+export declare function buildEncounterCareJourneyFlatGraph(input: Readonly<{
+    parent: EncounterJourneyNode & Readonly<{
+        subjectReference: string;
+        appointmentReference?: string;
+        serviceProviderReference: string;
+    }>;
+    stages?: readonly EncounterJourneyNode[];
+}>): readonly FlatClaimResourceEntry[];
+/** Builds one standard claims-first ServiceRequest; caller identity is input, not inferred authority. */
+export declare function buildServiceRequestFlatEntry(input: Readonly<{
+    entryId: string;
+    identifier: string;
+    status: 'draft' | 'active' | 'on-hold' | 'revoked' | 'completed' | 'entered-in-error' | 'unknown';
+    intent: 'proposal' | 'plan' | 'directive' | 'order' | 'original-order' | 'reflex-order' | 'filler-order' | 'instance-order' | 'option';
+    priority?: 'routine' | 'urgent' | 'asap' | 'stat';
+    category?: ClinicalCoding;
+    code: ClinicalCoding;
+    subjectReference: string;
+    encounterReference?: string;
+    requesterReference: string;
+    performerReferences: readonly string[];
+    authoredAt: string;
+    occurrence?: string;
+    reasonCodes?: readonly ClinicalCoding[];
+    reasonReferences?: readonly string[];
+}>): FlatClaimResourceEntry;
+/** Builds the independent durable Task used to acknowledge and triage one ServiceRequest. */
+export declare function buildServiceRequestTriageTaskFlatEntry(input: Readonly<{
+    entryId: string;
+    identifier: string;
+    serviceRequestReference: string;
+    subjectReference: string;
+    requesterReference: string;
+    ownerReference: string;
+    authoredAt: string;
+}>): FlatClaimResourceEntry;
+/** Builds one campaign-level request against a frozen enumerated Group snapshot. */
+export declare function buildCohortCommunicationRequestFlatEntry(input: Readonly<{
+    entryId: string;
+    identifier: string;
+    status: 'draft' | 'active' | 'on-hold' | 'revoked' | 'completed' | 'entered-in-error' | 'unknown';
+    priority?: 'routine' | 'urgent' | 'asap' | 'stat';
+    category: ClinicalCoding;
+    subjectReference: string;
+    requesterReference: string;
+    authoredAt: string;
+    occurrence?: string;
+    reasonReferences: readonly string[];
+}>): FlatClaimResourceEntry;

package/dist/care-emergency-alert.js

@@ -0,0 +1,135 @@
+import { CommunicationRequestClaim, EncounterClaim, ServiceRequestClaim, TaskClaim, } from './claims/index.js';
+import { buildFlatClaimResourceEntry } from './flat-claim-resource-graph.js';
+/**
+ * Builds one actual-care Encounter graph from an originating Appointment.
+ * Child service/location encounters inherit subject and provider and reference
+ * the parent with FHIR `Encounter.partOf`; Appointment remains planning input.
+ */
+export function buildEncounterCareJourneyFlatGraph(input) {
+    const parent = encounterEntry(input.parent);
+    const stages = (input.stages ?? []).map(stage => encounterEntry({
+        ...stage,
+        subjectReference: input.parent.subjectReference,
+        serviceProviderReference: input.parent.serviceProviderReference,
+        partOfReference: parent.reference,
+    }));
+    return Object.freeze([parent, ...stages]);
+}
+/** Builds one standard claims-first ServiceRequest; caller identity is input, not inferred authority. */
+export function buildServiceRequestFlatEntry(input) {
+    const claims = {
+        [ServiceRequestClaim.Identifier]: required(input.identifier, 'service_request_identifier_required'),
+        [ServiceRequestClaim.Status]: input.status,
+        [ServiceRequestClaim.Intent]: input.intent,
+        [ServiceRequestClaim.Code]: coding(input.code, 'service_request_code_invalid'),
+        [ServiceRequestClaim.Subject]: reference(input.subjectReference, 'service_request_subject_invalid'),
+        [ServiceRequestClaim.Requester]: reference(input.requesterReference, 'service_request_requester_invalid'),
+        [ServiceRequestClaim.Performer]: references(input.performerReferences, 'service_request_performer_required'),
+        [ServiceRequestClaim.AuthoredOn]: dateTime(input.authoredAt, 'service_request_authored_on_invalid'),
+    };
+    if (input.priority)
+        claims[ServiceRequestClaim.Priority] = input.priority;
+    if (input.category)
+        claims[ServiceRequestClaim.Category] = coding(input.category, 'service_request_category_invalid');
+    if (input.code.text?.trim())
+        claims[ServiceRequestClaim.CodeText] = input.code.text.trim();
+    if (input.encounterReference)
+        claims[ServiceRequestClaim.Encounter] = reference(input.encounterReference, 'service_request_encounter_invalid');
+    if (input.occurrence)
+        claims[ServiceRequestClaim.Occurrence] = dateTime(input.occurrence, 'service_request_occurrence_invalid');
+    if (input.reasonCodes?.length)
+        claims[ServiceRequestClaim.ReasonCode] = input.reasonCodes.map(value => coding(value, 'service_request_reason_code_invalid')).join(',');
+    if (input.reasonReferences?.length)
+        claims[ServiceRequestClaim.ReasonReference] = references(input.reasonReferences, 'service_request_reason_reference_invalid');
+    return buildFlatClaimResourceEntry({ entryId: input.entryId, resourceType: 'ServiceRequest', claims });
+}
+/** Builds the independent durable Task used to acknowledge and triage one ServiceRequest. */
+export function buildServiceRequestTriageTaskFlatEntry(input) {
+    return buildFlatClaimResourceEntry({
+        entryId: input.entryId,
+        resourceType: 'Task',
+        claims: {
+            [TaskClaim.Identifier]: required(input.identifier, 'triage_task_identifier_required'),
+            [TaskClaim.Status]: 'requested',
+            [TaskClaim.Intent]: 'order',
+            [TaskClaim.Code]: 'triage',
+            [TaskClaim.For]: reference(input.subjectReference, 'triage_task_subject_invalid'),
+            [TaskClaim.Requester]: reference(input.requesterReference, 'triage_task_requester_invalid'),
+            [TaskClaim.Owner]: reference(input.ownerReference, 'triage_task_owner_invalid'),
+            [TaskClaim.Focus]: reference(input.serviceRequestReference, 'triage_task_focus_invalid'),
+            [TaskClaim.AuthoredOn]: dateTime(input.authoredAt, 'triage_task_authored_on_invalid'),
+        },
+    });
+}
+/** Builds one campaign-level request against a frozen enumerated Group snapshot. */
+export function buildCohortCommunicationRequestFlatEntry(input) {
+    const claims = {
+        [CommunicationRequestClaim.Identifier]: required(input.identifier, 'communication_request_identifier_required'),
+        [CommunicationRequestClaim.Status]: input.status,
+        [CommunicationRequestClaim.Category]: coding(input.category, 'communication_request_category_invalid'),
+        [CommunicationRequestClaim.Subject]: groupReference(input.subjectReference, 'communication_request_subject_group_required'),
+        [CommunicationRequestClaim.Requester]: reference(input.requesterReference, 'communication_request_requester_invalid'),
+        [CommunicationRequestClaim.AuthoredOn]: dateTime(input.authoredAt, 'communication_request_authored_on_invalid'),
+        [CommunicationRequestClaim.ReasonReference]: references(input.reasonReferences, 'communication_request_reason_reference_required'),
+    };
+    if (input.priority)
+        claims[CommunicationRequestClaim.Priority] = input.priority;
+    if (input.occurrence)
+        claims[CommunicationRequestClaim.Occurrence] = dateTime(input.occurrence, 'communication_request_occurrence_invalid');
+    return buildFlatClaimResourceEntry({ entryId: input.entryId, resourceType: 'CommunicationRequest', claims });
+}
+function encounterEntry(input) {
+    const claims = {
+        [EncounterClaim.Identifier]: required(input.identifier, 'encounter_identifier_required'),
+        [EncounterClaim.Status]: input.status,
+        [EncounterClaim.Subject]: reference(input.subjectReference, 'encounter_subject_invalid'),
+        [EncounterClaim.ServiceProvider]: reference(input.serviceProviderReference, 'encounter_service_provider_invalid'),
+        [EncounterClaim.PeriodStart]: dateTime(input.periodStart, 'encounter_period_start_invalid'),
+        [EncounterClaim.Location]: reference(input.locationReference, 'encounter_location_invalid'),
+    };
+    if (input.periodEnd)
+        claims[EncounterClaim.PeriodEnd] = dateTime(input.periodEnd, 'encounter_period_end_invalid');
+    if (input.appointmentReference)
+        claims[EncounterClaim.Appointment] = reference(input.appointmentReference, 'encounter_appointment_invalid');
+    if (input.partOfReference)
+        claims[EncounterClaim.PartOf] = reference(input.partOfReference, 'encounter_part_of_invalid');
+    if (input.type)
+        claims[EncounterClaim.Type] = coding(input.type, 'encounter_type_invalid');
+    return buildFlatClaimResourceEntry({ entryId: input.entryId, resourceType: 'Encounter', claims });
+}
+function coding(value, error) {
+    const system = required(value.system, error);
+    const code = required(value.code, error);
+    if (system.includes('|') || code.includes('|') || system.includes(',') || code.includes(','))
+        throw new TypeError(error);
+    return `${system}|${code}`;
+}
+function references(values, error) {
+    const normalized = [...new Set(values.map(value => reference(value, error)))];
+    if (!normalized.length)
+        throw new TypeError(error);
+    return normalized.join(',');
+}
+function reference(value, error) {
+    const normalized = required(value, error);
+    if (normalized.includes(','))
+        throw new TypeError(error);
+    return normalized;
+}
+function groupReference(value, error) {
+    const normalized = reference(value, error);
+    if (!normalized.startsWith('Group/'))
+        throw new TypeError(error);
+    return normalized;
+}
+function dateTime(value, error) {
+    const normalized = required(value, error);
+    if (!/^\d{4}-\d{2}-\d{2}T/.test(normalized) || Number.isNaN(Date.parse(normalized)))
+        throw new TypeError(error);
+    return normalized;
+}
+function required(value, error) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError(error);
+    return value.trim();
+}

package/dist/claims/communication-request-claims.d.ts

@@ -0,0 +1,21 @@
+import type { ClaimSpec } from './claim-types.js';
+/** Canonical claims-first keys for FHIR CommunicationRequest. */
+export declare const CommunicationRequestClaim: Readonly<{
+    readonly Identifier: "CommunicationRequest.identifier";
+    readonly BasedOn: "CommunicationRequest.based-on";
+    readonly Status: "CommunicationRequest.status";
+    readonly Priority: "CommunicationRequest.priority";
+    readonly Category: "CommunicationRequest.category";
+    readonly Subject: "CommunicationRequest.subject";
+    readonly About: "CommunicationRequest.about";
+    readonly Encounter: "CommunicationRequest.encounter";
+    readonly Requester: "CommunicationRequest.requester";
+    readonly Recipient: "CommunicationRequest.recipient";
+    readonly AuthoredOn: "CommunicationRequest.authored-on";
+    readonly Occurrence: "CommunicationRequest.occurrence";
+    readonly ReasonCode: "CommunicationRequest.reason-code";
+    readonly ReasonReference: "CommunicationRequest.reason-reference";
+    readonly PayloadContent: "CommunicationRequest.payload-content";
+}>;
+export type CommunicationRequestClaimKey = typeof CommunicationRequestClaim[keyof typeof CommunicationRequestClaim];
+export declare const CommunicationRequestClaimSpecs: readonly ClaimSpec[];

package/dist/claims/communication-request-claims.js

@@ -0,0 +1,27 @@
+/** Canonical claims-first keys for FHIR CommunicationRequest. */
+export const CommunicationRequestClaim = Object.freeze({
+    Identifier: 'CommunicationRequest.identifier',
+    BasedOn: 'CommunicationRequest.based-on',
+    Status: 'CommunicationRequest.status',
+    Priority: 'CommunicationRequest.priority',
+    Category: 'CommunicationRequest.category',
+    Subject: 'CommunicationRequest.subject',
+    About: 'CommunicationRequest.about',
+    Encounter: 'CommunicationRequest.encounter',
+    Requester: 'CommunicationRequest.requester',
+    Recipient: 'CommunicationRequest.recipient',
+    AuthoredOn: 'CommunicationRequest.authored-on',
+    Occurrence: 'CommunicationRequest.occurrence',
+    ReasonCode: 'CommunicationRequest.reason-code',
+    ReasonReference: 'CommunicationRequest.reason-reference',
+    PayloadContent: 'CommunicationRequest.payload-content',
+});
+export const CommunicationRequestClaimSpecs = Object.freeze([
+    { key: CommunicationRequestClaim.Identifier, meaning: 'Business identifier.', example: 'urn:uuid:campaign-1' },
+    { key: CommunicationRequestClaim.Status, meaning: 'Request lifecycle status.', example: 'active' },
+    { key: CommunicationRequestClaim.Priority, meaning: 'Delivery priority.', example: 'routine' },
+    { key: CommunicationRequestClaim.Category, meaning: 'Communication category token.', example: 'http://terminology.hl7.org/CodeSystem/communication-category|notification' },
+    { key: CommunicationRequestClaim.Subject, meaning: 'Subject or evaluated Group reference.', example: 'Group/snapshot-1' },
+    { key: CommunicationRequestClaim.Requester, meaning: 'Requesting organization or service.', example: 'Organization/blood-bank-1' },
+    { key: CommunicationRequestClaim.AuthoredOn, meaning: 'Request authoring time.', example: '2026-09-26T11:00:00Z' },
+]);

package/dist/claims/composition-claims.d.ts

@@ -1,4 +1,5 @@
 export declare const CompositionClaim: {
+    readonly Status: "Composition.status";
     readonly Subject: "Composition.subject";
     readonly Section: "Composition.section";
     readonly Author: "Composition.author";

package/dist/claims/composition-claims.js

@@ -1,6 +1,7 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // File: src/models/interoperable-claims/composition-claims.ts
 export const CompositionClaim = {
+    Status: 'Composition.status',
     Subject: 'Composition.subject',
     Section: 'Composition.section',
     Author: 'Composition.author',

package/dist/claims/encounter-claims.d.ts

@@ -14,6 +14,7 @@ export declare const EncounterClaim: {
     readonly ReasonCode: "Encounter.reason-code";
     readonly Diagnosis: "Encounter.diagnosis";
     readonly Location: "Encounter.location";
+    readonly PartOf: "Encounter.part-of";
 };
 /** Canonical FHIR R4 Encounter lifecycle codes. */
 export declare enum EncounterStatus {

package/dist/claims/encounter-claims.js

@@ -15,6 +15,7 @@ export const EncounterClaim = {
     ReasonCode: 'Encounter.reason-code',
     Diagnosis: 'Encounter.diagnosis',
     Location: 'Encounter.location',
+    PartOf: 'Encounter.part-of',
 };
 /** Canonical FHIR R4 Encounter lifecycle codes. */
 export var EncounterStatus;
@@ -44,4 +45,5 @@ export const EncounterClaimSpecs = [
     { key: EncounterClaim.ReasonCode, meaning: 'Reason code token.', example: 'http://snomed.info/sct|65363002' },
     { key: EncounterClaim.Diagnosis, meaning: 'Diagnosis references (CSV).', example: 'Condition/cond-1' },
     { key: EncounterClaim.Location, meaning: 'Location references (CSV).', example: 'Location/loc-1' },
+    { key: EncounterClaim.PartOf, meaning: 'Parent Encounter reference.', example: 'Encounter/encounter-1' },
 ];

package/dist/claims/index.d.ts

@@ -5,6 +5,7 @@ export * from './appointment-response-claims.js';
 export * from './care-plan-claims.js';
 export * from './clinical-impression-claims.js';
 export * from './communication-claims.js';
+export * from './communication-request-claims.js';
 export * from './composition-claims.js';
 export * from './consent-claims.js';
 export * from './condition-claims.js';
@@ -27,4 +28,5 @@ export * from './practitioner-role-claims.js';
 export * from './procedure-claims.js';
 export * from './related-person-claims.js';
 export * from './research-subject-claims.js';
+export * from './service-request-claims.js';
 export * from './task-claims.js';

package/dist/claims/index.js

@@ -5,6 +5,7 @@ export * from './appointment-response-claims.js';
 export * from './care-plan-claims.js';
 export * from './clinical-impression-claims.js';
 export * from './communication-claims.js';
+export * from './communication-request-claims.js';
 export * from './composition-claims.js';
 export * from './consent-claims.js';
 export * from './condition-claims.js';
@@ -27,4 +28,5 @@ export * from './practitioner-role-claims.js';
 export * from './procedure-claims.js';
 export * from './related-person-claims.js';
 export * from './research-subject-claims.js';
+export * from './service-request-claims.js';
 export * from './task-claims.js';

package/dist/claims/service-request-claims.d.ts

@@ -0,0 +1,24 @@
+import type { ClaimSpec } from './claim-types.js';
+/** Canonical claims-first keys for FHIR ServiceRequest. */
+export declare const ServiceRequestClaim: Readonly<{
+    readonly Identifier: "ServiceRequest.identifier";
+    readonly Status: "ServiceRequest.status";
+    readonly Intent: "ServiceRequest.intent";
+    readonly Priority: "ServiceRequest.priority";
+    readonly Category: "ServiceRequest.category";
+    readonly Code: "ServiceRequest.code";
+    readonly CodeText: "ServiceRequest.code-text";
+    readonly Subject: "ServiceRequest.subject";
+    readonly Encounter: "ServiceRequest.encounter";
+    readonly Requester: "ServiceRequest.requester";
+    readonly Performer: "ServiceRequest.performer";
+    readonly AuthoredOn: "ServiceRequest.authored-on";
+    readonly Occurrence: "ServiceRequest.occurrence";
+    readonly ReasonCode: "ServiceRequest.reason-code";
+    readonly ReasonReference: "ServiceRequest.reason-reference";
+    readonly SupportingInfo: "ServiceRequest.supporting-info";
+    readonly Specimen: "ServiceRequest.specimen";
+    readonly BodySite: "ServiceRequest.body-site";
+}>;
+export type ServiceRequestClaimKey = typeof ServiceRequestClaim[keyof typeof ServiceRequestClaim];
+export declare const ServiceRequestClaimSpecs: readonly ClaimSpec[];

package/dist/claims/service-request-claims.js

@@ -0,0 +1,33 @@
+/** Canonical claims-first keys for FHIR ServiceRequest. */
+export const ServiceRequestClaim = Object.freeze({
+    Identifier: 'ServiceRequest.identifier',
+    Status: 'ServiceRequest.status',
+    Intent: 'ServiceRequest.intent',
+    Priority: 'ServiceRequest.priority',
+    Category: 'ServiceRequest.category',
+    Code: 'ServiceRequest.code',
+    CodeText: 'ServiceRequest.code-text',
+    Subject: 'ServiceRequest.subject',
+    Encounter: 'ServiceRequest.encounter',
+    Requester: 'ServiceRequest.requester',
+    Performer: 'ServiceRequest.performer',
+    AuthoredOn: 'ServiceRequest.authored-on',
+    Occurrence: 'ServiceRequest.occurrence',
+    ReasonCode: 'ServiceRequest.reason-code',
+    ReasonReference: 'ServiceRequest.reason-reference',
+    SupportingInfo: 'ServiceRequest.supporting-info',
+    Specimen: 'ServiceRequest.specimen',
+    BodySite: 'ServiceRequest.body-site',
+});
+export const ServiceRequestClaimSpecs = Object.freeze([
+    { key: ServiceRequestClaim.Identifier, meaning: 'Business identifier.', example: 'urn:uuid:request-1' },
+    { key: ServiceRequestClaim.Status, meaning: 'Request lifecycle status.', example: 'active' },
+    { key: ServiceRequestClaim.Intent, meaning: 'Request intent.', example: 'order' },
+    { key: ServiceRequestClaim.Priority, meaning: 'Request priority.', example: 'stat' },
+    { key: ServiceRequestClaim.Category, meaning: 'Category token.', example: 'http://snomed.info/sct|409971007' },
+    { key: ServiceRequestClaim.Code, meaning: 'Requested service token.', example: 'http://snomed.info/sct|225358003' },
+    { key: ServiceRequestClaim.Subject, meaning: 'Subject reference.', example: 'Patient/subject-1' },
+    { key: ServiceRequestClaim.Requester, meaning: 'Requester reference.', example: 'RelatedPerson/requester-1' },
+    { key: ServiceRequestClaim.Performer, meaning: 'Requested performer references (CSV).', example: 'HealthcareService/emergency-1' },
+    { key: ServiceRequestClaim.AuthoredOn, meaning: 'Request authoring time.', example: '2026-09-26T10:00:00Z' },
+]);

package/dist/constants/fhir-resource-types.d.ts

@@ -13,6 +13,7 @@ export declare const ResourceTypesFhirR4: Readonly<{
     readonly CarePlan: "CarePlan";
     readonly ClinicalImpression: "ClinicalImpression";
     readonly Communication: "Communication";
+    readonly CommunicationRequest: "CommunicationRequest";
     readonly Composition: "Composition";
     readonly Condition: "Condition";
     readonly Consent: "Consent";
@@ -68,6 +69,7 @@ export declare const FhirResourceTypes: Readonly<{
     readonly CarePlan: "CarePlan";
     readonly ClinicalImpression: "ClinicalImpression";
     readonly Communication: "Communication";
+    readonly CommunicationRequest: "CommunicationRequest";
     readonly Composition: "Composition";
     readonly Condition: "Condition";
     readonly Consent: "Consent";
@@ -119,6 +121,7 @@ export declare const ResourceTypesFhirR5: Readonly<{
     readonly CarePlan: "CarePlan";
     readonly ClinicalImpression: "ClinicalImpression";
     readonly Communication: "Communication";
+    readonly CommunicationRequest: "CommunicationRequest";
     readonly Composition: "Composition";
     readonly Condition: "Condition";
     readonly Consent: "Consent";

package/dist/constants/fhir-resource-types.js

@@ -13,6 +13,7 @@ export const ResourceTypesFhirR4 = Object.freeze({
     CarePlan: 'CarePlan',
     ClinicalImpression: 'ClinicalImpression',
     Communication: 'Communication',
+    CommunicationRequest: 'CommunicationRequest',
     Composition: 'Composition',
     Condition: 'Condition',
     Consent: 'Consent',

package/dist/converters/convert-communication-request.d.ts

@@ -0,0 +1,5 @@
+import type { FhirResource, FlatClaims } from './convert-shared.js';
+/** Projects one governed communication request to the FHIR R4 wire shape. */
+export declare function communicationRequestFlatToFhirR4(claims: FlatClaims): FhirResource;
+/** Reads a FHIR R4 CommunicationRequest into canonical flat claims. */
+export declare function communicationRequestFhirR4ToFlat(resource: FhirResource): FlatClaims;

package/dist/converters/convert-communication-request.js

@@ -0,0 +1,40 @@
+import { CommunicationRequestClaim } from '../claims/communication-request-claims.js';
+import { codingFromValue, codingListFromCsv, codingListToCsv, codingToValue, referenceListToCsv, referenceToValue } from './convert-shared.js';
+/** Projects one governed communication request to the FHIR R4 wire shape. */
+export function communicationRequestFlatToFhirR4(claims) {
+    return {
+        resourceType: 'CommunicationRequest', identifier: claims[CommunicationRequestClaim.Identifier] ? [{ value: claims[CommunicationRequestClaim.Identifier] }] : undefined,
+        basedOn: referenceCsv(claims[CommunicationRequestClaim.BasedOn]), status: claims[CommunicationRequestClaim.Status], priority: claims[CommunicationRequestClaim.Priority],
+        category: claims[CommunicationRequestClaim.Category] ? [{ coding: codingFromValue(claims[CommunicationRequestClaim.Category]) }] : undefined,
+        subject: claims[CommunicationRequestClaim.Subject] ? { reference: claims[CommunicationRequestClaim.Subject] } : undefined,
+        about: referenceCsv(claims[CommunicationRequestClaim.About]), encounter: claims[CommunicationRequestClaim.Encounter] ? { reference: claims[CommunicationRequestClaim.Encounter] } : undefined,
+        requester: claims[CommunicationRequestClaim.Requester] ? { reference: claims[CommunicationRequestClaim.Requester] } : undefined,
+        recipient: referenceCsv(claims[CommunicationRequestClaim.Recipient]), authoredOn: claims[CommunicationRequestClaim.AuthoredOn],
+        occurrenceDateTime: claims[CommunicationRequestClaim.Occurrence],
+        reasonCode: claims[CommunicationRequestClaim.ReasonCode] ? [{ coding: codingListFromCsv(claims[CommunicationRequestClaim.ReasonCode]) }] : undefined,
+        reasonReference: referenceCsv(claims[CommunicationRequestClaim.ReasonReference]),
+        payload: claims[CommunicationRequestClaim.PayloadContent] ? [{ contentString: claims[CommunicationRequestClaim.PayloadContent] }] : undefined,
+    };
+}
+/** Reads a FHIR R4 CommunicationRequest into canonical flat claims. */
+export function communicationRequestFhirR4ToFlat(resource) {
+    return {
+        [CommunicationRequestClaim.Identifier]: resource.identifier?.[0]?.value,
+        [CommunicationRequestClaim.BasedOn]: referenceListToCsv(resource.basedOn),
+        [CommunicationRequestClaim.Status]: resource.status, [CommunicationRequestClaim.Priority]: resource.priority,
+        [CommunicationRequestClaim.Category]: codingToValue(resource.category?.[0]?.coding?.[0]),
+        [CommunicationRequestClaim.Subject]: referenceToValue(resource.subject),
+        [CommunicationRequestClaim.About]: referenceListToCsv(resource.about),
+        [CommunicationRequestClaim.Encounter]: referenceToValue(resource.encounter),
+        [CommunicationRequestClaim.Requester]: referenceToValue(resource.requester),
+        [CommunicationRequestClaim.Recipient]: referenceListToCsv(resource.recipient),
+        [CommunicationRequestClaim.AuthoredOn]: resource.authoredOn, [CommunicationRequestClaim.Occurrence]: resource.occurrenceDateTime,
+        [CommunicationRequestClaim.ReasonCode]: codingListToCsv(resource.reasonCode?.flatMap(value => value.coding ?? [])),
+        [CommunicationRequestClaim.ReasonReference]: referenceListToCsv(resource.reasonReference),
+        [CommunicationRequestClaim.PayloadContent]: resource.payload?.[0]?.contentString,
+    };
+}
+function referenceCsv(value) {
+    const references = value?.split(',').map(reference => reference.trim()).filter(Boolean) ?? [];
+    return references.length ? references.map(reference => ({ reference })) : undefined;
+}

package/dist/converters/convert-composition.js

@@ -31,6 +31,7 @@ function alignedAttesterValue(attesters, select) {
 export function compositionFlatToFhirR4(claims) {
     return {
         resourceType: 'Composition',
+        status: claims[CompositionClaim.Status],
         identifier: claims[CompositionClaim.Identifier] ? { value: claims[CompositionClaim.Identifier] } : undefined,
         subject: claims[CompositionClaim.Subject] ? { reference: claims[CompositionClaim.Subject] } : undefined,
         author: claims[CompositionClaim.Author] ? claims[CompositionClaim.Author].split(',').map((reference) => ({ reference: reference.trim() })) : undefined,
@@ -41,7 +42,9 @@ export function compositionFlatToFhirR4(claims) {
         type: claims[CompositionClaim.Type] ? { coding: codingFromValue(claims[CompositionClaim.Type]) } : undefined,
         section: claims[CompositionClaim.Section]
             ? claims[CompositionClaim.Section].split(',').map((value) => ({ code: { coding: codingFromValue(value.trim()) } }))
-            : undefined,
+            : claims[CompositionClaim.Entry]
+                ? [{ entry: claims[CompositionClaim.Entry].split(',').map((reference) => ({ reference: reference.trim() })) }]
+                : undefined,
     };
 }
 export function compositionFhirR4ToFlat(resource) {
@@ -53,7 +56,14 @@ export function compositionFhirR4ToFlat(resource) {
             .map((item) => codingToValue(item?.code?.coding?.[0]))
             .filter((item) => Boolean(item))
         : [];
+    const entryReferences = Array.isArray(resource.section)
+        ? resource.section
+            .flatMap((section) => Array.isArray(section.entry) ? section.entry : [])
+            .map((entry) => referenceToValue(entry))
+            .filter((item) => Boolean(item))
+        : [];
     return {
+        [CompositionClaim.Status]: resource.status,
         [CompositionClaim.Subject]: referenceToValue(resource.subject),
         [CompositionClaim.Section]: sectionValues.length ? sectionValues.join(',') : undefined,
         [CompositionClaim.Author]: referenceListToCsv(resource.author),
@@ -62,7 +72,7 @@ export function compositionFhirR4ToFlat(resource) {
         [CompositionClaim.AttesterTime]: alignedAttesterValue(attesters, (attester) => attester.time),
         [CompositionClaim.Custodian]: referenceToValue(resource.custodian),
         [CompositionClaim.Date]: resource.date,
-        [CompositionClaim.Entry]: undefined,
+        [CompositionClaim.Entry]: entryReferences.length ? entryReferences.join(',') : undefined,
         [CompositionClaim.Type]: codingToValue(resource.type?.coding?.[0]),
         [CompositionClaim.Identifier]: resource.identifier?.value,
         [CompositionClaim.Title]: resource.title,

package/dist/converters/convert-encounter.js

@@ -34,6 +34,7 @@ export function encounterFlatToFhirR4(claims) {
         location: claims[EncounterClaim.Location]
             ? claims[EncounterClaim.Location].split(',').map((reference) => ({ location: { reference: reference.trim() } }))
             : undefined,
+        partOf: claims[EncounterClaim.PartOf] ? { reference: claims[EncounterClaim.PartOf] } : undefined,
     };
 }
 export function encounterFhirR4ToFlat(resource) {
@@ -68,5 +69,6 @@ export function encounterFhirR4ToFlat(resource) {
                 .filter((item) => Boolean(item))
                 .join(',')
             : undefined,
+        [EncounterClaim.PartOf]: referenceToValue(resource.partOf),
     };
 }

package/dist/converters/convert-service-request.d.ts

@@ -0,0 +1,5 @@
+import type { FhirResource, FlatClaims } from './convert-shared.js';
+/** Projects canonical ServiceRequest flat claims to the FHIR R4 wire shape. */
+export declare function serviceRequestFlatToFhirR4(claims: FlatClaims): FhirResource;
+/** Reads a FHIR R4 ServiceRequest into canonical compact-token flat claims. */
+export declare function serviceRequestFhirR4ToFlat(resource: FhirResource): FlatClaims;