fhir-data-utils-ts 0.3.5 → 0.3.7

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

@@ -38,6 +38,23 @@ 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
+  evidence is an independent `DocumentReference`. Preliminary state does not
+  itself authorize ledger or research projection.
 
 ## Change with executable contracts
 

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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
+  laboratory panels, independent Observation results and PDF/image
+  DocumentReference evidence.
+- Correct the document builder to emit the canonical DocumentReference claim
+  catalog and complete list helpers for report results, performers, specimens
+  and graph references.
+
 ## 0.3.5 - 2026-09-26
 
 - Preserve the originating `Encounter.appointment` reference and expose the

package/README.md

@@ -29,6 +29,13 @@ through `<ResourceType>.contained-reference-list`; children do not carry
 as `<ResourceType>.language`, `.narrative-status` and `.xhtml`. Native FHIR is
 materialized only by an explicit R4/R5/R6 import or export adapter.
 
+Laboratory authoring uses `buildDiagnosticReportFlatGraph(...)`.
+`DiagnosticReport.code` is the coded report or panel type, atomic results are
+independent LOINC-coded `Observation` entries, and PDF/JPEG/PNG evidence is an
+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.
+
 ## Public contract
 
 The root export and stable subpaths provide:
@@ -143,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/builders/diagnostic-report-graph.d.ts

@@ -0,0 +1,31 @@
+import { type DiagnosticReportStatus } from '../constants/clinical-statuses.js';
+import { type FlatClaimResourceEntry } from '../flat-claim-resource-graph.js';
+export type DiagnosticReportCoding = Readonly<{
+    system: string;
+    code: string;
+    display?: string;
+    text?: string;
+}>;
+export type DiagnosticReportFlatInput = Readonly<{
+    entryId: string;
+    identifier: string;
+    status: DiagnosticReportStatus;
+    subjectReference: string;
+    issuedAt: string;
+    reportCode: DiagnosticReportCoding;
+    encounterReference?: string;
+    performerReferences?: readonly string[];
+    results?: readonly FlatClaimResourceEntry[];
+    attachments?: readonly FlatClaimResourceEntry[];
+}>;
+/**
+ * Builds a claims-first DiagnosticReport graph for human, animal, or One Health
+ * laboratory reports. `DiagnosticReport.code` identifies the report/panel;
+ * atomic measurements remain independent `Observation` entries and PDF/JPEG/
+ * PNG evidence remains independent `DocumentReference` entries.
+ *
+ * `preliminary` reports can be exchanged and reviewed, but downstream ledger
+ * and secondary-use policy decides whether only `final` is eligible for those
+ * projections. This builder does not confer authority or consent.
+ */
+export declare function buildDiagnosticReportFlatGraph(input: DiagnosticReportFlatInput): readonly FlatClaimResourceEntry[];

package/dist/builders/diagnostic-report-graph.js

@@ -0,0 +1,86 @@
+// Copyright 2026 ConnectHealth.info (Connecting Solution & Applications Ltd.) under the Apache License, Version 2.0.
+import { DiagnosticReportClaim } from '../claims/diagnostic-report-claims.js';
+import { DiagnosticReportStatuses } from '../constants/clinical-statuses.js';
+import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+import { buildFlatClaimResourceEntry, linkFlatClaimResourceEntries, } from '../flat-claim-resource-graph.js';
+const DIAGNOSTIC_REPORT_STATUSES = new Set(Object.values(DiagnosticReportStatuses));
+/**
+ * Builds a claims-first DiagnosticReport graph for human, animal, or One Health
+ * laboratory reports. `DiagnosticReport.code` identifies the report/panel;
+ * atomic measurements remain independent `Observation` entries and PDF/JPEG/
+ * PNG evidence remains independent `DocumentReference` entries.
+ *
+ * `preliminary` reports can be exchanged and reviewed, but downstream ledger
+ * and secondary-use policy decides whether only `final` is eligible for those
+ * projections. This builder does not confer authority or consent.
+ */
+export function buildDiagnosticReportFlatGraph(input) {
+    const status = required(input.status, 'diagnostic_report_status_required');
+    if (!DIAGNOSTIC_REPORT_STATUSES.has(status))
+        throw new TypeError('diagnostic_report_status_invalid');
+    const claims = {
+        [DiagnosticReportClaim.Identifier]: required(input.identifier, 'diagnostic_report_identifier_required'),
+        [DiagnosticReportClaim.Status]: status,
+        [DiagnosticReportClaim.Subject]: required(input.subjectReference, 'diagnostic_report_subject_required'),
+        [DiagnosticReportClaim.Date]: isoDateTime(input.issuedAt, 'diagnostic_report_date_invalid'),
+        [DiagnosticReportClaim.Code]: codingToken(input.reportCode),
+    };
+    if (input.reportCode.display?.trim())
+        claims[DiagnosticReportClaim.CodeDisplay] = input.reportCode.display.trim();
+    if (input.reportCode.text?.trim())
+        claims[DiagnosticReportClaim.CodeText] = input.reportCode.text.trim();
+    if (input.encounterReference?.trim()) {
+        claims[DiagnosticReportClaim.Encounter] = required(input.encounterReference, 'diagnostic_report_encounter_invalid');
+    }
+    if (input.performerReferences?.length) {
+        claims[DiagnosticReportClaim.Performer] = referenceList(input.performerReferences, 'diagnostic_report_performer_invalid');
+    }
+    const results = [...(input.results ?? [])];
+    if (results.some(entry => entry.resourceType !== ResourceTypesFhirR4.Observation)) {
+        throw new TypeError('diagnostic_report_result_invalid');
+    }
+    const attachments = [...(input.attachments ?? [])];
+    if (attachments.some(entry => entry.resourceType !== ResourceTypesFhirR4.DocumentReference)) {
+        throw new TypeError('diagnostic_report_attachment_invalid');
+    }
+    if (results.length)
+        claims[DiagnosticReportClaim.Result] = results.map(entry => entry.reference).join(',');
+    const report = buildFlatClaimResourceEntry({
+        entryId: input.entryId,
+        resourceType: ResourceTypesFhirR4.DiagnosticReport,
+        claims,
+    });
+    const children = [...results, ...attachments];
+    const graph = [report, ...children];
+    return children.length
+        ? linkFlatClaimResourceEntries(graph, {
+            parentEntryId: report.entryId,
+            childEntryIds: children.map(entry => entry.entryId),
+        })
+        : graph;
+}
+function codingToken(value) {
+    const system = required(value.system, 'diagnostic_report_code_system_required');
+    const code = required(value.code, 'diagnostic_report_code_required');
+    if (system.includes('|') || code.includes('|') || system.includes(',') || code.includes(',')) {
+        throw new TypeError('diagnostic_report_code_invalid');
+    }
+    return `${system}|${code}`;
+}
+function referenceList(values, error) {
+    const normalized = [...new Set(values.map(value => required(value, error)))];
+    if (normalized.some(value => value.includes(',')))
+        throw new TypeError(error);
+    return normalized.join(',');
+}
+function isoDateTime(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/builders/index.d.ts

@@ -1,2 +1,3 @@
+export * from './diagnostic-report-graph.js';
 export * from './immunization-graph.js';
 export * from './immunization-reminders.js';

package/dist/builders/index.js

@@ -1,2 +1,3 @@
+export * from './diagnostic-report-graph.js';
 export * from './immunization-graph.js';
 export * from './immunization-reminders.js';

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/claim-helpers/claims-helpers-diagnostic-report.d.ts

@@ -8,8 +8,20 @@ export declare function getDiagnosticReportIdentifier(claims: DiagnosticReportIn
 export declare function setDiagnosticReportIdentifier(claims: DiagnosticReportInteroperableClaims, value: string): DiagnosticReportInteroperableClaims;
 export declare function getDiagnosticReportResultList(claims: DiagnosticReportInteroperableClaims): string[];
 export declare function setDiagnosticReportResultList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function addDiagnosticReportResultList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function removeDiagnosticReportResultList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function getDiagnosticReportPerformerList(claims: DiagnosticReportInteroperableClaims): string[];
+export declare function setDiagnosticReportPerformerList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function addDiagnosticReportPerformerList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function removeDiagnosticReportPerformerList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function getDiagnosticReportSpecimenList(claims: DiagnosticReportInteroperableClaims): string[];
+export declare function setDiagnosticReportSpecimenList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function addDiagnosticReportSpecimenList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function removeDiagnosticReportSpecimenList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
 export declare function getDiagnosticReportContainedResourceReferenceList(claims: DiagnosticReportInteroperableClaims): string[];
 export declare function setDiagnosticReportContainedResourceReferenceList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function addDiagnosticReportContainedResourceReferenceList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function removeDiagnosticReportContainedResourceReferenceList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
 /** @deprecated Use `getDiagnosticReportContainedResourceReferenceList`. */
 export declare function getDiagnosticReportContainedDocumentIdentifierList(claims: DiagnosticReportInteroperableClaims): string[];
 /** @deprecated Use `setDiagnosticReportContainedResourceReferenceList`. */

package/dist/claim-helpers/claims-helpers-diagnostic-report.js

@@ -24,6 +24,36 @@ export function getDiagnosticReportResultList(claims) {
 export function setDiagnosticReportResultList(claims, values) {
     return setDiagnosticReportClaimList(claims, DiagnosticReportClaim.Result, values);
 }
+export function addDiagnosticReportResultList(claims, values) {
+    return addDiagnosticReportClaimList(claims, DiagnosticReportClaim.Result, values);
+}
+export function removeDiagnosticReportResultList(claims, values) {
+    return removeDiagnosticReportClaimList(claims, DiagnosticReportClaim.Result, values);
+}
+export function getDiagnosticReportPerformerList(claims) {
+    return getDiagnosticReportClaimList(claims, DiagnosticReportClaim.Performer);
+}
+export function setDiagnosticReportPerformerList(claims, values) {
+    return setDiagnosticReportClaimList(claims, DiagnosticReportClaim.Performer, values);
+}
+export function addDiagnosticReportPerformerList(claims, values) {
+    return addDiagnosticReportClaimList(claims, DiagnosticReportClaim.Performer, values);
+}
+export function removeDiagnosticReportPerformerList(claims, values) {
+    return removeDiagnosticReportClaimList(claims, DiagnosticReportClaim.Performer, values);
+}
+export function getDiagnosticReportSpecimenList(claims) {
+    return getDiagnosticReportClaimList(claims, DiagnosticReportClaim.Specimen);
+}
+export function setDiagnosticReportSpecimenList(claims, values) {
+    return setDiagnosticReportClaimList(claims, DiagnosticReportClaim.Specimen, values);
+}
+export function addDiagnosticReportSpecimenList(claims, values) {
+    return addDiagnosticReportClaimList(claims, DiagnosticReportClaim.Specimen, values);
+}
+export function removeDiagnosticReportSpecimenList(claims, values) {
+    return removeDiagnosticReportClaimList(claims, DiagnosticReportClaim.Specimen, values);
+}
 export function getDiagnosticReportContainedResourceReferenceList(claims) {
     const canonical = getDiagnosticReportClaimList(claims, DiagnosticReportClaim.ContainedReferenceList);
     const legacy = getDiagnosticReportClaimList(claims, DiagnosticReportClaim.ContainedDocuments);
@@ -37,6 +67,16 @@ export function setDiagnosticReportContainedResourceReferenceList(claims, values
     delete cleaned[DiagnosticReportClaim.ContainedDocuments];
     return cleaned;
 }
+export function addDiagnosticReportContainedResourceReferenceList(claims, values) {
+    return setDiagnosticReportContainedResourceReferenceList(claims, [
+        ...getDiagnosticReportContainedResourceReferenceList(claims),
+        ...(Array.isArray(values) ? values : [values]),
+    ]);
+}
+export function removeDiagnosticReportContainedResourceReferenceList(claims, values) {
+    const removals = new Set(Array.isArray(values) ? values : [values]);
+    return setDiagnosticReportContainedResourceReferenceList(claims, getDiagnosticReportContainedResourceReferenceList(claims).filter(value => !removals.has(value)));
+}
 /** @deprecated Use `getDiagnosticReportContainedResourceReferenceList`. */
 export function getDiagnosticReportContainedDocumentIdentifierList(claims) {
     return getDiagnosticReportContainedResourceReferenceList(claims);

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/diagnostic-report-claims.d.ts

@@ -33,31 +33,6 @@ export declare const DiagnosticReportClaim: {
      */
     readonly ContainedDocuments: "DiagnosticReport.contained-documents";
 };
-/**
- * TODO(ips-next):
- * Add resource-level claim helpers in `src/utils/claims-helpers-diagnostic-report.ts`
- * following the same contract already used by Consent/Medication/Condition/Allergy:
- * - `getDiagnosticReportClaimList(...)`
- * - `setDiagnosticReportClaimList(...)`
- * - `addDiagnosticReportClaimList(...)`
- * - `removeDiagnosticReportClaimList(...)`
- * - focused helpers for:
- *   - `get/set/add/removeDiagnosticReportResultList`
- *   - `get/set/add/removeDiagnosticReportPerformerList`
- *   - `get/set/add/removeDiagnosticReportSpecimenList`
- *   - `get/set/add/removeDiagnosticReportContainedResourceReferences`
- *   - `get/setDiagnosticReportPresentedFormContentType`
- *   - `get/setDiagnosticReportPresentedFormData`
- *   - `get/setDiagnosticReportPresentedFormUrl`
- *
- * Keep naming aligned with canonical FHIR search parameter names
- * (lowercase with `-`) and reuse the existing `SearchParamNames` + contextualized
- * claim-key mapping pattern.
- *
- * This file is intentionally type-first only for now so GW Core and
- * `common-utils` can already exercise the rest of the bundle workflow without
- * committing to the DiagnosticReport editing surface yet.
- */
 export type DiagnosticReportClaimKey = typeof DiagnosticReportClaim[keyof typeof DiagnosticReportClaim];
 export declare const DiagnosticReportClaimSpecs: ClaimSpec[];
 export declare const DiagnosticReportSearchParamNames: {
@@ -95,15 +70,7 @@ export declare enum DiagnosticReportClaimsFhirApi {
 }
 export declare const DiagnosticReportSearchParamToClaimKey: Record<DiagnosticReportSearchParamName, DiagnosticReportClaimsFhirApi>;
 /**
- * TODO(ips-next):
- * Add `DiagnosticReportClaimsFhirApiExtended` only if/when the bundle editor
- * needs operational flat fields beyond the official search parameter surface.
- *
- * Do not invent camelCase names. Prefer official FHIR search parameter names
- * or explicit attachment aliases such as `presented-form-*` and
- * `contained-reference-list`.
- *
- * Keep `DiagnosticReport` paused at the typing/mapping layer until:
- * 1. `claims-helpers-diagnostic-report.ts` exists
- * 2. GW Core readers/tests consume the same shared claim keys
+ * Operational attachment and graph claims remain separate from the official
+ * SearchParameter catalog above. They support claims-first authoring without
+ * pretending that those aliases are searchable FHIR parameters.
  */

package/dist/claims/diagnostic-report-claims.js

@@ -54,7 +54,7 @@ export const DiagnosticReportClaimSpecs = [
     { key: DiagnosticReportClaim.PresentedFormContentType, meaning: 'FHIR presentedForm attachment content type.', example: 'application/pdf' },
     { key: DiagnosticReportClaim.PresentedFormData, meaning: 'FHIR presentedForm inline base64 payload.', example: 'JVBERi0xLjc...' },
     { key: DiagnosticReportClaim.PresentedFormUrl, meaning: 'FHIR presentedForm external URL.', example: 'https://example.org/report.pdf' },
-    { key: DiagnosticReportClaim.ContainedDocuments, meaning: 'CSV of linked DocumentReference identifiers stored in the same bundle.', example: 'docref-example-001,docref-example-002' },
+    { key: DiagnosticReportClaim.ContainedReferenceList, meaning: 'Canonical CSV of independent result and evidence resource references linked by this report.', example: 'Observation/result-1,DocumentReference/report-1' },
 ];
 export const DiagnosticReportSearchParamNames = {
     BasedOn: 'based-on',
@@ -106,15 +106,7 @@ export const DiagnosticReportSearchParamToClaimKey = {
     [DiagnosticReportSearchParamNames.Subject]: DiagnosticReportClaimsFhirApi.Subject,
 };
 /**
- * TODO(ips-next):
- * Add `DiagnosticReportClaimsFhirApiExtended` only if/when the bundle editor
- * needs operational flat fields beyond the official search parameter surface.
- *
- * Do not invent camelCase names. Prefer official FHIR search parameter names
- * or explicit attachment aliases such as `presented-form-*` and
- * `contained-reference-list`.
- *
- * Keep `DiagnosticReport` paused at the typing/mapping layer until:
- * 1. `claims-helpers-diagnostic-report.ts` exists
- * 2. GW Core readers/tests consume the same shared claim keys
+ * Operational attachment and graph claims remain separate from the official
+ * SearchParameter catalog above. They support claims-first authoring without
+ * pretending that those aliases are searchable FHIR parameters.
  */

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/flat-claim-resource-graph.js

@@ -70,16 +70,16 @@ export function normalizeLegacyContainedClaims(entry) {
  */
 export function buildDocumentReferenceFlatEntry(input) {
     const claims = {
-        'DocumentReference.identifier': requiredToken(input.identifier, 'document_reference_identifier_required'),
-        'DocumentReference.content-type': input.contentType,
-        'DocumentReference.contenthash': requiredToken(input.contentHash, 'document_reference_contenthash_required'),
+        [DocumentReferenceClaim.Identifier]: requiredToken(input.identifier, 'document_reference_identifier_required'),
+        [DocumentReferenceClaim.ContentType]: input.contentType,
+        [DocumentReferenceClaim.ContentHash]: requiredToken(input.contentHash, 'document_reference_contenthash_required'),
     };
     if (input.title?.trim())
-        claims['DocumentReference.title'] = input.title.trim();
+        claims[DocumentReferenceClaim.Description] = input.title.trim();
     if (input.url?.trim())
-        claims['DocumentReference.url'] = input.url.trim();
+        claims[DocumentReferenceClaim.Location] = input.url.trim();
     if (input.dataBase64?.trim())
-        claims['DocumentReference.data'] = input.dataBase64.trim();
+        claims[DocumentReferenceClaim.ContentData] = input.dataBase64.trim();
     return buildFlatClaimResourceEntry({ entryId: input.entryId, resourceType: 'DocumentReference', claims });
 }
 function splitCsv(value) {
@@ -106,3 +106,4 @@ function requiredResourceType(value) {
         throw new TypeError('flat_claim_resource_type_invalid');
     return normalized;
 }
+import { DocumentReferenceClaim } from './claims/document-reference-claims.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/docs/UHC_FHIR_UTILS_MIGRATION.md

@@ -83,6 +83,13 @@ one native `Observation.component[]`; it does not export three independent
 native Observations. Component entries do not use `is-contained`,
 `contained-parent-reference` or `contained-reference-list`.
 
+Diagnostic laboratory authoring is owned here by
+`buildDiagnosticReportFlatGraph(...)`: `DiagnosticReport.code` identifies the
+report/panel, independent Observation entries carry atomic results, and
+independent DocumentReference entries carry PDF/image evidence. Sector roles,
+confirmation, ledger eligibility, consent and research policy remain outside
+this package.
+
 Aligned JSON arrays and the older comma-separated `Observation.component-*`
 claims are accepted only by the migration reader. No current writer emits
 either representation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhir-data-utils-ts",
-  "version": "0.3.5",
+  "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"