fhir-data-utils-ts 0.3.6 → 0.3.7

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/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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

@@ -150,6 +150,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/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-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;

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

@@ -0,0 +1,47 @@
+import { ServiceRequestClaim } from '../claims/service-request-claims.js';
+import { codingFromValue, codingListFromCsv, codingListToCsv, codingToValue, referenceListToCsv, referenceToValue } from './convert-shared.js';
+/** Projects canonical ServiceRequest flat claims to the FHIR R4 wire shape. */
+export function serviceRequestFlatToFhirR4(claims) {
+    const codeCoding = codingFromValue(claims[ServiceRequestClaim.Code])?.[0];
+    return {
+        resourceType: 'ServiceRequest',
+        identifier: claims[ServiceRequestClaim.Identifier] ? [{ value: claims[ServiceRequestClaim.Identifier] }] : undefined,
+        status: claims[ServiceRequestClaim.Status], intent: claims[ServiceRequestClaim.Intent], priority: claims[ServiceRequestClaim.Priority],
+        category: claims[ServiceRequestClaim.Category] ? [{ coding: codingFromValue(claims[ServiceRequestClaim.Category]) }] : undefined,
+        code: codeCoding || claims[ServiceRequestClaim.CodeText] ? { coding: codeCoding ? [codeCoding] : undefined, text: claims[ServiceRequestClaim.CodeText] } : undefined,
+        subject: claims[ServiceRequestClaim.Subject] ? { reference: claims[ServiceRequestClaim.Subject] } : undefined,
+        encounter: claims[ServiceRequestClaim.Encounter] ? { reference: claims[ServiceRequestClaim.Encounter] } : undefined,
+        requester: claims[ServiceRequestClaim.Requester] ? { reference: claims[ServiceRequestClaim.Requester] } : undefined,
+        performer: referenceCsv(claims[ServiceRequestClaim.Performer]), authoredOn: claims[ServiceRequestClaim.AuthoredOn],
+        occurrenceDateTime: claims[ServiceRequestClaim.Occurrence],
+        reasonCode: claims[ServiceRequestClaim.ReasonCode] ? [{ coding: codingListFromCsv(claims[ServiceRequestClaim.ReasonCode]) }] : undefined,
+        reasonReference: referenceCsv(claims[ServiceRequestClaim.ReasonReference]),
+        supportingInfo: referenceCsv(claims[ServiceRequestClaim.SupportingInfo]), specimen: referenceCsv(claims[ServiceRequestClaim.Specimen]),
+        bodySite: claims[ServiceRequestClaim.BodySite] ? [{ coding: codingListFromCsv(claims[ServiceRequestClaim.BodySite]) }] : undefined,
+    };
+}
+/** Reads a FHIR R4 ServiceRequest into canonical compact-token flat claims. */
+export function serviceRequestFhirR4ToFlat(resource) {
+    const code = resource.code;
+    return {
+        [ServiceRequestClaim.Identifier]: resource.identifier?.[0]?.value,
+        [ServiceRequestClaim.Status]: resource.status, [ServiceRequestClaim.Intent]: resource.intent,
+        [ServiceRequestClaim.Priority]: resource.priority,
+        [ServiceRequestClaim.Category]: codingToValue(resource.category?.[0]?.coding?.[0]),
+        [ServiceRequestClaim.Code]: codingToValue(code?.coding?.[0]), [ServiceRequestClaim.CodeText]: code?.text,
+        [ServiceRequestClaim.Subject]: referenceToValue(resource.subject),
+        [ServiceRequestClaim.Encounter]: referenceToValue(resource.encounter),
+        [ServiceRequestClaim.Requester]: referenceToValue(resource.requester),
+        [ServiceRequestClaim.Performer]: referenceListToCsv(resource.performer),
+        [ServiceRequestClaim.AuthoredOn]: resource.authoredOn, [ServiceRequestClaim.Occurrence]: resource.occurrenceDateTime,
+        [ServiceRequestClaim.ReasonCode]: codingListToCsv(resource.reasonCode?.flatMap(value => value.coding ?? [])),
+        [ServiceRequestClaim.ReasonReference]: referenceListToCsv(resource.reasonReference),
+        [ServiceRequestClaim.SupportingInfo]: referenceListToCsv(resource.supportingInfo),
+        [ServiceRequestClaim.Specimen]: referenceListToCsv(resource.specimen),
+        [ServiceRequestClaim.BodySite]: codingListToCsv(resource.bodySite?.flatMap(value => value.coding ?? [])),
+    };
+}
+function referenceCsv(value) {
+    const references = value?.split(',').map(reference => reference.trim()).filter(Boolean) ?? [];
+    return references.length ? references.map(reference => ({ reference })) : undefined;
+}

package/dist/converters/index.d.ts

@@ -4,6 +4,7 @@ export * from './convert-appointment-response.js';
 export * from './convert-appointment.js';
 export * from './convert-care-plan.js';
 export * from './convert-clinical-impression.js';
+export * from './convert-communication-request.js';
 export * from './convert-composition.js';
 export * from './convert-consent.js';
 export * from './convert-condition.js';
@@ -23,3 +24,4 @@ export * from './convert-organization.js';
 export * from './convert-practitioner-role.js';
 export * from './convert-procedure.js';
 export * from './convert-related-person.js';
+export * from './convert-service-request.js';

package/dist/converters/index.js

@@ -4,6 +4,7 @@ export * from './convert-appointment-response.js';
 export * from './convert-appointment.js';
 export * from './convert-care-plan.js';
 export * from './convert-clinical-impression.js';
+export * from './convert-communication-request.js';
 export * from './convert-composition.js';
 export * from './convert-consent.js';
 export * from './convert-condition.js';
@@ -23,3 +24,4 @@ export * from './convert-organization.js';
 export * from './convert-practitioner-role.js';
 export * from './convert-procedure.js';
 export * from './convert-related-person.js';
+export * from './convert-service-request.js';

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from './fhir-bundle.js';
 export * from './terminology-models/index.js';
 export * from './constants/index.js';
 export * from './clinical-terminology.js';
+export * from './care-emergency-alert.js';
 export * from './immunization-flat-claims.js';
 export * from './immunization-reminder-plan.js';
 export * from './builders/index.js';

package/dist/index.js

@@ -14,6 +14,7 @@ export * from './fhir-bundle.js';
 export * from './terminology-models/index.js';
 export * from './constants/index.js';
 export * from './clinical-terminology.js';
+export * from './care-emergency-alert.js';
 export * from './immunization-flat-claims.js';
 export * from './immunization-reminder-plan.js';
 export * from './builders/index.js';

package/docs/CARE_EMERGENCY_ALERT_CONTRACTS.md

@@ -0,0 +1,50 @@
+# Care, emergency and population-alert FHIR contracts
+
+This package owns only the product-neutral FHIR representation used by the
+three SOSChain journeys that are first proven in VetChain and PetChain.
+Authorization, controller discovery, encryption, transport, storage and UI
+policy remain in their owning product or service layers.
+
+## Hospital or clinic care journey
+
+An `Appointment` plans care. Marking it fulfilled can originate one parent
+`Encounter`; it must not erase the `Encounter.appointment` reference. Admission,
+imaging, intensive care and discharge are independent child `Encounter`
+resources linked through `Encounter.partOf`, each with its actual `Location`.
+This graph supports a bounded location timeline. It does not itself grant a
+relative permission to see locations or clinical records.
+
+A voice/video call or encrypted missed-call message may occur before a report
+is published. Transport events are not clinical attestation and must not
+silently change an Encounter, a daily draft or the individual's index.
+
+## Resilient emergency request
+
+An emergency request is a standard claims-first `ServiceRequest`. Its service
+and category are compact `system|code` tokens; writers never emit split
+`code-system`, `code-value` or stored `code-display` claims. A local phrase may
+remain in `ServiceRequest.code-text`; a trusted display is resolved from the
+code at the terminology boundary.
+
+Acknowledgement and triage use a separate durable `Task` whose `focus`
+references the request. Requester, subject, intended performer and task owner
+are explicit inputs. None of those references is inferred as authorization.
+
+## Donation and public-risk campaign
+
+The campaign-level `CommunicationRequest.subject` is a frozen, enumerated
+`Group` snapshot. Its `reasonReference` points to the definitional cohort used
+to create that snapshot. Per-recipient eligibility, current Consent,
+subscription/channel status, exclusions and delivery audit must be rechecked
+outside this neutral package immediately before creating each individual
+`Communication`.
+
+The snapshot and request are evidence of evaluation and intent, not permission
+to disclose group membership or send a message.
+
+## Public API
+
+Use `fhir-data-utils-ts/care-emergency-alert` for graph builders and the package
+root or `fhir-data-utils-ts/converters` for R4 projections. Persistence remains
+flat claims. Native FHIR is materialized only at an explicit import/export
+boundary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhir-data-utils-ts",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "FHIR-version-neutral flat-claim and SearchParameter data utilities",
   "license": "Apache-2.0",
   "type": "module",
@@ -19,6 +19,10 @@
       "types": "./dist/flat-claim-resource-graph.d.ts",
       "default": "./dist/flat-claim-resource-graph.js"
     },
+    "./care-emergency-alert": {
+      "types": "./dist/care-emergency-alert.d.ts",
+      "default": "./dist/care-emergency-alert.js"
+    },
     "./search-parameters": {
       "types": "./dist/search-parameters.d.ts",
       "default": "./dist/search-parameters.js"