fhir-data-utils-ts 0.3.3 → 0.3.5

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

@@ -29,6 +29,15 @@ description: Complete or audit migrations, claim catalogs, converters, builders,
   projection. Do not invent resource-specific scalar aliases for indexing.
 - Keep Group membership and ResearchStudy associated parties descriptive;
   neither is a Consent, SMART scope or authorization grant.
+- Keep native R5 SubscriptionTopic/Subscription configuration and notification
+  Bundle parsing separate from the claims-first Communication being delivered.
+  This package owns their reusable types and validation, never HTTP delivery,
+  subscriber persistence, authentication or product notification policy.
+- Keep ImagingStudy searchable metadata, clinical references and protected
+  endpoint references in neutral flat claims. DICOM parsing, pixels and object
+  storage remain in a separately versioned imaging/storage package.
+- Preserve `Encounter.appointment`; an Appointment lifecycle transition must
+  not sever the encounter from the scheduling event that originated it.
 
 ## Change with executable contracts
 

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.3.5 - 2026-09-26
+
+- Preserve the originating `Encounter.appointment` reference and expose the
+  canonical FHIR R4 Encounter lifecycle vocabulary.
+- Add product-neutral ImagingStudy flat claims, helpers and R4 projection for
+  searchable clinical metadata and protected endpoint references without
+  embedding DICOM payloads.
+- Cover Encounter and ImagingStudy with rich round-trip, catalog, helper,
+  documentation and package-surface contracts.
+
+## 0.3.4 - 2026-09-23
+
+- Add native FHIR R5 `SubscriptionTopic` and HTTPS rest-hook `Subscription`
+  builders plus the official resource-specific SearchParameter catalogs.
+- Add a strict `subscription-notification` Bundle parser that resolves each
+  advertised full-resource event focus and distinguishes handshake events.
+- Add the claims-first terminal-job `Communication` contract used by DataConv
+  and professional BFFs without introducing transport, storage or product
+  policy into the neutral package.
+
 ## 0.3.3 - 2026-09-23
 
 - Define product-neutral coding-review families and pending-proposal helpers.

package/README.md

@@ -42,6 +42,9 @@ The root export and stable subpaths provide:
   RelatedPerson/telecom helpers and type-only DICOMDIR tree contract;
 - cross-sector terminology, Immunization graphs/reminders, and FHIR R5 Group
   and ResearchStudy contracts previously located only in SOS or Vet packages.
+- native FHIR R5 SubscriptionTopic/Subscription configuration builders,
+  official search catalogs and a strict notification-Bundle parser; terminal
+  asynchronous job messages remain claims-first Communication resources.
 
 Claim catalogs and graph builders are deliberately different surfaces.
 `fhir-data-utils-ts/claims` owns canonical storage names and their specs;
@@ -50,6 +53,13 @@ those catalogs. The old `/immunization-flat-claims` and
 `/immunization-reminder-plan` paths are deprecated compatibility re-exports;
 new code imports `/builders` or `/builders/immunization`.
 
+Encounter projection preserves the originating `Appointment` reference and
+uses the canonical R4 lifecycle (`in-progress` while care is underway,
+`finished` when it ends). ImagingStudy projection stores searchable study
+metadata and protected endpoint references only. DICOM instances and pixel
+payloads remain outside this neutral package and are never embedded as flat
+claims.
+
 No consumer should copy claim paths or rebuild these structures with literals.
 Use `fhir-data-utils-ts/claims`, `/converters`, `/fhir-bundle`,
 `/fhir-search-parameters`, `/clinical-terminology`, `/group-r5` or
@@ -111,6 +121,22 @@ The package exports builders, traversal/confirmation helpers and
 `CODING_REVIEW_EXAMPLES`. Tests and consumers reuse them instead of duplicating
 claim strings, terminology identifiers, codes or UUIDs.
 
+## R5 asynchronous notifications
+
+`fhir-data-utils-ts/subscription-r5` separates three boundaries:
+
+- `SubscriptionTopic` and `Subscription` are native R5 configuration resources;
+- the job-completion `Communication` is canonical flat-claim business data;
+- `Bundle[type=subscription-notification]` is parsed only at the receiving
+  rest-hook boundary.
+
+The shared package owns types, builders, official SearchParameter metadata and
+validation. DataConv owns emitting the terminal Communication, GW owns durable
+subscription delivery, and each BFF owns authenticated inbox persistence and
+browser/email/push fan-out. Tenant-level Communication subscriptions initially
+use no server-side filter; the receiving BFF routes the minimal full resource by
+its canonical `Communication.recipient` claim.
+
 ## Verification gate
 
 `npm run check` runs strict type checking, all contract tests and built-in

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

@@ -8,3 +8,5 @@ export declare function getEncounterIdentifier(claims: EncounterInteroperableCla
 export declare function setEncounterIdentifier(claims: EncounterInteroperableClaims, value: string): EncounterInteroperableClaims;
 export declare function getEncounterParticipantList(claims: EncounterInteroperableClaims): string[];
 export declare function setEncounterParticipantList(claims: EncounterInteroperableClaims, values: string | readonly string[]): EncounterInteroperableClaims;
+export declare function getEncounterAppointmentList(claims: EncounterInteroperableClaims): string[];
+export declare function setEncounterAppointmentList(claims: EncounterInteroperableClaims, values: string | readonly string[]): EncounterInteroperableClaims;

package/dist/claim-helpers/claims-helpers-encounter.js

@@ -24,3 +24,9 @@ export function getEncounterParticipantList(claims) {
 export function setEncounterParticipantList(claims, values) {
     return setEncounterClaimList(claims, EncounterClaim.Participant, values);
 }
+export function getEncounterAppointmentList(claims) {
+    return getEncounterClaimList(claims, EncounterClaim.Appointment);
+}
+export function setEncounterAppointmentList(claims, values) {
+    return setEncounterClaimList(claims, EncounterClaim.Appointment, values);
+}

package/dist/claim-helpers/claims-helpers-imaging-study.d.ts

@@ -0,0 +1,8 @@
+import { type GenericInteroperableClaims } from './claim-list-helpers.js';
+export type ImagingStudyInteroperableClaims = GenericInteroperableClaims;
+export declare function getImagingStudyClaimList(claims: ImagingStudyInteroperableClaims, claimKey: string): string[];
+export declare function setImagingStudyClaimList(claims: ImagingStudyInteroperableClaims, claimKey: string, values: string | readonly string[]): ImagingStudyInteroperableClaims;
+export declare function addImagingStudyClaimList(claims: ImagingStudyInteroperableClaims, claimKey: string, values: string | readonly string[]): ImagingStudyInteroperableClaims;
+export declare function removeImagingStudyClaimList(claims: ImagingStudyInteroperableClaims, claimKey: string, values: string | readonly string[]): ImagingStudyInteroperableClaims;
+export declare function getImagingStudyIdentifier(claims: ImagingStudyInteroperableClaims): string;
+export declare function setImagingStudyIdentifier(claims: ImagingStudyInteroperableClaims, value: string): ImagingStudyInteroperableClaims;

package/dist/claim-helpers/claims-helpers-imaging-study.js

@@ -0,0 +1,20 @@
+import { ImagingStudyClaim } from '../claims/imaging-study-claims.js';
+import { addClaimValues, getClaimValues, normalizeClaimScalar, removeClaimValues, setClaimValues, } from './claim-list-helpers.js';
+export function getImagingStudyClaimList(claims, claimKey) {
+    return getClaimValues(claims, claimKey);
+}
+export function setImagingStudyClaimList(claims, claimKey, values) {
+    return setClaimValues(claims, claimKey, values);
+}
+export function addImagingStudyClaimList(claims, claimKey, values) {
+    return addClaimValues(claims, claimKey, values);
+}
+export function removeImagingStudyClaimList(claims, claimKey, values) {
+    return removeClaimValues(claims, claimKey, values);
+}
+export function getImagingStudyIdentifier(claims) {
+    return normalizeClaimScalar(claims[ImagingStudyClaim.Identifier]);
+}
+export function setImagingStudyIdentifier(claims, value) {
+    return { ...claims, [ImagingStudyClaim.Identifier]: normalizeClaimScalar(value) };
+}

package/dist/claim-helpers/index.d.ts

@@ -15,6 +15,7 @@ export * from './claims-helpers-document-reference.js';
 export * from './claims-helpers-encounter.js';
 export * from './claims-helpers-flag.js';
 export * from './claims-helpers-immunization.js';
+export * from './claims-helpers-imaging-study.js';
 export * from './claims-helpers-location.js';
 export * from './claims-helpers-medication-statement.js';
 export * from './claims-helpers-observation.js';

package/dist/claim-helpers/index.js

@@ -15,6 +15,7 @@ export * from './claims-helpers-document-reference.js';
 export * from './claims-helpers-encounter.js';
 export * from './claims-helpers-flag.js';
 export * from './claims-helpers-immunization.js';
+export * from './claims-helpers-imaging-study.js';
 export * from './claims-helpers-location.js';
 export * from './claims-helpers-medication-statement.js';
 export * from './claims-helpers-observation.js';

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

@@ -15,6 +15,8 @@ export declare const CommunicationClaim: {
     readonly Status: "Communication.status";
     /** Stable communication identifier. */
     readonly Identifier: "Communication.identifier";
+    /** Request or Task that initiated this Communication. */
+    readonly BasedOn: "Communication.based-on";
     /** Subject identifier (typically `did:web`). */
     readonly Subject: "Communication.subject";
     /** Recipient identifier(s); CSV allowed. */
@@ -27,6 +29,8 @@ export declare const CommunicationClaim: {
     readonly NoteText: "Communication.note-text";
     /** Communication topic code (`system|code`). */
     readonly Topic: "Communication.topic";
+    /** Resource references that provide the Communication context; CSV allowed. */
+    readonly About: "Communication.about";
     /** Narrative text (short summary or body). */
     readonly Text: "Communication.text";
     /** Related resource references; CSV allowed. */

package/dist/claims/communication-claims.js

@@ -18,6 +18,8 @@ export const CommunicationClaim = {
     Status: 'Communication.status',
     /** Stable communication identifier. */
     Identifier: 'Communication.identifier',
+    /** Request or Task that initiated this Communication. */
+    BasedOn: 'Communication.based-on',
     /** Subject identifier (typically `did:web`). */
     Subject: 'Communication.subject',
     /** Recipient identifier(s); CSV allowed. */
@@ -30,6 +32,8 @@ export const CommunicationClaim = {
     NoteText: 'Communication.note-text',
     /** Communication topic code (`system|code`). */
     Topic: 'Communication.topic',
+    /** Resource references that provide the Communication context; CSV allowed. */
+    About: 'Communication.about',
     /** Narrative text (short summary or body). */
     Text: 'Communication.text',
     /** Related resource references; CSV allowed. */

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

@@ -1,6 +1,7 @@
 import type { ClaimSpec } from './claim-types.js';
 export declare const EncounterClaim: {
     readonly Identifier: "Encounter.identifier";
+    readonly Appointment: "Encounter.appointment";
     readonly Status: "Encounter.status";
     readonly Class: "Encounter.class";
     readonly Type: "Encounter.type";
@@ -14,5 +15,17 @@ export declare const EncounterClaim: {
     readonly Diagnosis: "Encounter.diagnosis";
     readonly Location: "Encounter.location";
 };
+/** Canonical FHIR R4 Encounter lifecycle codes. */
+export declare enum EncounterStatus {
+    Planned = "planned",
+    Arrived = "arrived",
+    Triaged = "triaged",
+    InProgress = "in-progress",
+    OnLeave = "onleave",
+    Finished = "finished",
+    Cancelled = "cancelled",
+    EnteredInError = "entered-in-error",
+    Unknown = "unknown"
+}
 export type EncounterClaimKey = typeof EncounterClaim[keyof typeof EncounterClaim];
 export declare const EncounterClaimSpecs: ClaimSpec[];

package/dist/claims/encounter-claims.js

@@ -2,6 +2,7 @@
 // File: src/models/interoperable-claims/encounter-claims.ts
 export const EncounterClaim = {
     Identifier: 'Encounter.identifier',
+    Appointment: 'Encounter.appointment',
     Status: 'Encounter.status',
     Class: 'Encounter.class',
     Type: 'Encounter.type',
@@ -15,8 +16,22 @@ export const EncounterClaim = {
     Diagnosis: 'Encounter.diagnosis',
     Location: 'Encounter.location',
 };
+/** Canonical FHIR R4 Encounter lifecycle codes. */
+export var EncounterStatus;
+(function (EncounterStatus) {
+    EncounterStatus["Planned"] = "planned";
+    EncounterStatus["Arrived"] = "arrived";
+    EncounterStatus["Triaged"] = "triaged";
+    EncounterStatus["InProgress"] = "in-progress";
+    EncounterStatus["OnLeave"] = "onleave";
+    EncounterStatus["Finished"] = "finished";
+    EncounterStatus["Cancelled"] = "cancelled";
+    EncounterStatus["EnteredInError"] = "entered-in-error";
+    EncounterStatus["Unknown"] = "unknown";
+})(EncounterStatus || (EncounterStatus = {}));
 export const EncounterClaimSpecs = [
     { key: EncounterClaim.Identifier, meaning: 'Business identifier.', example: 'enc-001' },
+    { key: EncounterClaim.Appointment, meaning: 'Originating appointment references (CSV).', example: 'Appointment/appointment-1' },
     { key: EncounterClaim.Status, meaning: 'Encounter status.', example: 'finished' },
     { key: EncounterClaim.Class, meaning: 'Encounter class token.', example: 'http://terminology.hl7.org/CodeSystem/v3-ActCode|AMB' },
     { key: EncounterClaim.Type, meaning: 'Encounter type token.', example: 'http://snomed.info/sct|185349003' },

package/dist/claims/imaging-study-claims.d.ts

@@ -0,0 +1,25 @@
+import type { ClaimSpec } from './claim-types.js';
+/** Product-neutral flat claims for searchable FHIR R4 ImagingStudy metadata. */
+export declare const ImagingStudyClaim: {
+    readonly Identifier: "ImagingStudy.identifier";
+    readonly Status: "ImagingStudy.status";
+    readonly Modality: "ImagingStudy.modality";
+    readonly Subject: "ImagingStudy.subject";
+    readonly Patient: "ImagingStudy.patient";
+    readonly Encounter: "ImagingStudy.encounter";
+    readonly Started: "ImagingStudy.started";
+    readonly BasedOn: "ImagingStudy.based-on";
+    readonly Referrer: "ImagingStudy.referrer";
+    readonly Interpreter: "ImagingStudy.interpreter";
+    readonly Endpoint: "ImagingStudy.endpoint";
+    readonly ProcedureReference: "ImagingStudy.procedure-reference";
+    readonly ProcedureCode: "ImagingStudy.procedure-code";
+    readonly ReasonCode: "ImagingStudy.reason-code";
+    readonly ReasonReference: "ImagingStudy.reason-reference";
+    readonly Location: "ImagingStudy.location";
+    readonly NumberOfSeries: "ImagingStudy.number-of-series";
+    readonly NumberOfInstances: "ImagingStudy.number-of-instances";
+    readonly Description: "ImagingStudy.description";
+};
+export type ImagingStudyClaimKey = typeof ImagingStudyClaim[keyof typeof ImagingStudyClaim];
+export declare const ImagingStudyClaimSpecs: readonly ClaimSpec[];

package/dist/claims/imaging-study-claims.js

@@ -0,0 +1,43 @@
+/** Product-neutral flat claims for searchable FHIR R4 ImagingStudy metadata. */
+export const ImagingStudyClaim = {
+    Identifier: 'ImagingStudy.identifier',
+    Status: 'ImagingStudy.status',
+    Modality: 'ImagingStudy.modality',
+    Subject: 'ImagingStudy.subject',
+    Patient: 'ImagingStudy.patient',
+    Encounter: 'ImagingStudy.encounter',
+    Started: 'ImagingStudy.started',
+    BasedOn: 'ImagingStudy.based-on',
+    Referrer: 'ImagingStudy.referrer',
+    Interpreter: 'ImagingStudy.interpreter',
+    Endpoint: 'ImagingStudy.endpoint',
+    ProcedureReference: 'ImagingStudy.procedure-reference',
+    ProcedureCode: 'ImagingStudy.procedure-code',
+    ReasonCode: 'ImagingStudy.reason-code',
+    ReasonReference: 'ImagingStudy.reason-reference',
+    Location: 'ImagingStudy.location',
+    NumberOfSeries: 'ImagingStudy.number-of-series',
+    NumberOfInstances: 'ImagingStudy.number-of-instances',
+    Description: 'ImagingStudy.description',
+};
+export const ImagingStudyClaimSpecs = Object.freeze([
+    { key: ImagingStudyClaim.Identifier, meaning: 'Business or DICOM study identifier.', example: 'imaging-study-1' },
+    { key: ImagingStudyClaim.Status, meaning: 'ImagingStudy lifecycle status.', example: 'available' },
+    { key: ImagingStudyClaim.Modality, meaning: 'Repeatable DICOM modality token.', example: 'http://dicom.nema.org/resources/ontology/DCM|DX' },
+    { key: ImagingStudyClaim.Subject, meaning: 'Canonical subject reference.', example: 'did:web:subject.example' },
+    { key: ImagingStudyClaim.Patient, meaning: 'FHIR R4 patient search alias.', example: 'did:web:subject.example' },
+    { key: ImagingStudyClaim.Encounter, meaning: 'Encounter context reference.', example: 'Encounter/encounter-1' },
+    { key: ImagingStudyClaim.Started, meaning: 'Study start instant.', example: '2026-09-26T10:15:00Z' },
+    { key: ImagingStudyClaim.BasedOn, meaning: 'Originating request references (CSV).', example: 'ServiceRequest/radiography-1' },
+    { key: ImagingStudyClaim.Referrer, meaning: 'Referring practitioner reference.', example: 'PractitionerRole/veterinarian-1' },
+    { key: ImagingStudyClaim.Interpreter, meaning: 'Interpreter references (CSV).', example: 'PractitionerRole/radiologist-1' },
+    { key: ImagingStudyClaim.Endpoint, meaning: 'Protected imaging endpoint references (CSV).', example: 'Endpoint/dicomweb-1' },
+    { key: ImagingStudyClaim.ProcedureReference, meaning: 'Performed procedure reference.', example: 'Procedure/radiography-1' },
+    { key: ImagingStudyClaim.ProcedureCode, meaning: 'Performed procedure coding token.', example: 'http://snomed.info/sct|363680008' },
+    { key: ImagingStudyClaim.ReasonCode, meaning: 'Study reason coding token.', example: 'http://snomed.info/sct|125605004' },
+    { key: ImagingStudyClaim.ReasonReference, meaning: 'Study reason references (CSV).', example: 'Condition/fracture-1' },
+    { key: ImagingStudyClaim.Location, meaning: 'Acquisition location reference.', example: 'Location/imaging-1' },
+    { key: ImagingStudyClaim.NumberOfSeries, meaning: 'Declared series count.', example: '1' },
+    { key: ImagingStudyClaim.NumberOfInstances, meaning: 'Declared instance count.', example: '2' },
+    { key: ImagingStudyClaim.Description, meaning: 'Study description.', example: 'Left forelimb radiographs' },
+]);

package/dist/claims/index.d.ts

@@ -17,6 +17,7 @@ export * from './encounter-claims.js';
 export * from './flag-claims.js';
 export * from './immunization-claims.js';
 export * from './immunization-recommendation-claims.js';
+export * from './imaging-study-claims.js';
 export * from './invoice-claims.js';
 export * from './location-claims.js';
 export * from './medication-statement-claims.js';

package/dist/claims/index.js

@@ -17,6 +17,7 @@ export * from './encounter-claims.js';
 export * from './flag-claims.js';
 export * from './immunization-claims.js';
 export * from './immunization-recommendation-claims.js';
+export * from './imaging-study-claims.js';
 export * from './invoice-claims.js';
 export * from './location-claims.js';
 export * from './medication-statement-claims.js';

package/dist/constants/fhir-code-systems.d.ts

@@ -9,6 +9,8 @@ export declare const FhirCodeSystems: Readonly<{
     readonly SnomedCt: "http://snomed.info/sct";
     readonly Ucum: "http://unitsofmeasure.org";
     readonly CommunicationCategory: "http://terminology.hl7.org/CodeSystem/communication-category";
+    readonly SubscriptionChannelType: "http://terminology.hl7.org/CodeSystem/subscription-channel-type";
+    readonly TaskStatus: "http://hl7.org/fhir/task-status";
     readonly ActReason: "http://terminology.hl7.org/CodeSystem/v3-ActReason";
     readonly ObservationCategory: "http://terminology.hl7.org/CodeSystem/observation-category";
     readonly EventTiming: "http://hl7.org/fhir/event-timing";

package/dist/constants/fhir-code-systems.js

@@ -9,6 +9,8 @@ export const FhirCodeSystems = Object.freeze({
     SnomedCt: 'http://snomed.info/sct',
     Ucum: 'http://unitsofmeasure.org',
     CommunicationCategory: 'http://terminology.hl7.org/CodeSystem/communication-category',
+    SubscriptionChannelType: 'http://terminology.hl7.org/CodeSystem/subscription-channel-type',
+    TaskStatus: 'http://hl7.org/fhir/task-status',
     ActReason: 'http://terminology.hl7.org/CodeSystem/v3-ActReason',
     ObservationCategory: 'http://terminology.hl7.org/CodeSystem/observation-category',
     EventTiming: 'http://hl7.org/fhir/event-timing',

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

@@ -108,6 +108,8 @@ export declare const FhirResourceTypes: Readonly<{
 }>;
 /** FHIR R5-only resources currently emitted by shared subscription contracts. */
 export declare const ResourceTypesFhirR5: Readonly<{
+    readonly Subscription: "Subscription";
+    readonly SubscriptionTopic: "SubscriptionTopic";
     readonly SubscriptionStatus: "SubscriptionStatus";
     readonly AdverseEvent: "AdverseEvent";
     readonly AllergyIntolerance: "AllergyIntolerance";

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

@@ -61,6 +61,8 @@ export const FhirResourceTypes = ResourceTypesFhirR4;
 /** FHIR R5-only resources currently emitted by shared subscription contracts. */
 export const ResourceTypesFhirR5 = Object.freeze({
     ...ResourceTypesFhirR4,
+    Subscription: 'Subscription',
+    SubscriptionTopic: 'SubscriptionTopic',
     SubscriptionStatus: 'SubscriptionStatus',
 });
 /** FHIR complex datatypes used as discriminators inside claims-first payloads. */

package/dist/converters/convert-encounter.js

@@ -1,12 +1,15 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // File: src/utils/convert-encounter.ts
 import { EncounterClaim } from '../claims/encounter-claims.js';
-import { codingFromValue, codingToValue, referenceToValue } from './convert-shared.js';
+import { codingFromValue, codingToValue, referenceListToCsv, referenceToValue } from './convert-shared.js';
 export function encounterFlatToFhirR4(claims) {
     const subject = claims[EncounterClaim.Subject] ?? claims[EncounterClaim.Patient];
     return {
         resourceType: 'Encounter',
         identifier: claims[EncounterClaim.Identifier] ? [{ value: claims[EncounterClaim.Identifier] }] : undefined,
+        appointment: claims[EncounterClaim.Appointment]
+            ? claims[EncounterClaim.Appointment].split(',').map((reference) => ({ reference: reference.trim() }))
+            : undefined,
         status: claims[EncounterClaim.Status],
         class: claims[EncounterClaim.Class]
             ? (() => {
@@ -37,6 +40,7 @@ export function encounterFhirR4ToFlat(resource) {
     const klass = resource.class;
     return {
         [EncounterClaim.Identifier]: resource.identifier?.[0]?.value,
+        [EncounterClaim.Appointment]: referenceListToCsv(resource.appointment),
         [EncounterClaim.Status]: resource.status,
         [EncounterClaim.Class]: klass?.code ? (klass.system ? `${klass.system}|${klass.code}` : klass.code) : undefined,
         [EncounterClaim.Type]: codingToValue(resource.type?.[0]?.coding?.[0]),

package/dist/converters/convert-imaging-study.d.ts

@@ -0,0 +1,4 @@
+import type { FhirResource, FlatClaims } from './convert-shared.js';
+/** Projects searchable ImagingStudy metadata; DICOM bytes remain in protected imaging storage. */
+export declare function imagingStudyFlatToFhirR4(claims: FlatClaims): FhirResource;
+export declare function imagingStudyFhirR4ToFlat(resource: FhirResource): FlatClaims;

package/dist/converters/convert-imaging-study.js

@@ -0,0 +1,82 @@
+import { ImagingStudyClaim } from '../claims/imaging-study-claims.js';
+import { codingFromValue, codingToValue, referenceListToCsv, referenceToValue } from './convert-shared.js';
+function csv(values) {
+    if (!Array.isArray(values))
+        return undefined;
+    const normalized = values.map((value) => String(value || '').trim()).filter(Boolean);
+    return normalized.length ? normalized.join(',') : undefined;
+}
+function codingCsv(values) {
+    if (!Array.isArray(values))
+        return undefined;
+    return csv(values.map((value) => codingToValue(value)));
+}
+function codingList(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return undefined;
+    const codings = value.split(',').flatMap((token) => codingFromValue(token.trim()) || []);
+    return codings.length ? codings : undefined;
+}
+/** Projects searchable ImagingStudy metadata; DICOM bytes remain in protected imaging storage. */
+export function imagingStudyFlatToFhirR4(claims) {
+    const subject = claims[ImagingStudyClaim.Subject] ?? claims[ImagingStudyClaim.Patient];
+    return {
+        resourceType: 'ImagingStudy',
+        identifier: claims[ImagingStudyClaim.Identifier] ? [{ value: claims[ImagingStudyClaim.Identifier] }] : undefined,
+        status: claims[ImagingStudyClaim.Status],
+        modality: codingList(claims[ImagingStudyClaim.Modality]),
+        subject: subject ? { reference: subject } : undefined,
+        encounter: claims[ImagingStudyClaim.Encounter] ? { reference: claims[ImagingStudyClaim.Encounter] } : undefined,
+        started: claims[ImagingStudyClaim.Started],
+        basedOn: references(claims[ImagingStudyClaim.BasedOn]),
+        referrer: claims[ImagingStudyClaim.Referrer] ? { reference: claims[ImagingStudyClaim.Referrer] } : undefined,
+        interpreter: references(claims[ImagingStudyClaim.Interpreter]),
+        endpoint: references(claims[ImagingStudyClaim.Endpoint]),
+        procedureReference: claims[ImagingStudyClaim.ProcedureReference] ? { reference: claims[ImagingStudyClaim.ProcedureReference] } : undefined,
+        procedureCode: claims[ImagingStudyClaim.ProcedureCode] ? [{ coding: codingFromValue(claims[ImagingStudyClaim.ProcedureCode]) }] : undefined,
+        reasonCode: claims[ImagingStudyClaim.ReasonCode] ? [{ coding: codingFromValue(claims[ImagingStudyClaim.ReasonCode]) }] : undefined,
+        reasonReference: references(claims[ImagingStudyClaim.ReasonReference]),
+        location: claims[ImagingStudyClaim.Location] ? { reference: claims[ImagingStudyClaim.Location] } : undefined,
+        numberOfSeries: numberValue(claims[ImagingStudyClaim.NumberOfSeries]),
+        numberOfInstances: numberValue(claims[ImagingStudyClaim.NumberOfInstances]),
+        description: claims[ImagingStudyClaim.Description],
+    };
+}
+export function imagingStudyFhirR4ToFlat(resource) {
+    return {
+        [ImagingStudyClaim.Identifier]: resource.identifier?.[0]?.value,
+        [ImagingStudyClaim.Status]: resource.status,
+        [ImagingStudyClaim.Modality]: codingCsv(resource.modality),
+        [ImagingStudyClaim.Subject]: referenceToValue(resource.subject),
+        [ImagingStudyClaim.Patient]: referenceToValue(resource.subject),
+        [ImagingStudyClaim.Encounter]: referenceToValue(resource.encounter),
+        [ImagingStudyClaim.Started]: resource.started,
+        [ImagingStudyClaim.BasedOn]: referenceListToCsv(resource.basedOn),
+        [ImagingStudyClaim.Referrer]: referenceToValue(resource.referrer),
+        [ImagingStudyClaim.Interpreter]: referenceListToCsv(resource.interpreter),
+        [ImagingStudyClaim.Endpoint]: referenceListToCsv(resource.endpoint),
+        [ImagingStudyClaim.ProcedureReference]: referenceToValue(resource.procedureReference),
+        [ImagingStudyClaim.ProcedureCode]: codingToValue(resource.procedureCode?.[0]?.coding?.[0]),
+        [ImagingStudyClaim.ReasonCode]: codingToValue(resource.reasonCode?.[0]?.coding?.[0]),
+        [ImagingStudyClaim.ReasonReference]: referenceListToCsv(resource.reasonReference),
+        [ImagingStudyClaim.Location]: referenceToValue(resource.location),
+        [ImagingStudyClaim.NumberOfSeries]: scalarNumber(resource.numberOfSeries),
+        [ImagingStudyClaim.NumberOfInstances]: scalarNumber(resource.numberOfInstances),
+        [ImagingStudyClaim.Description]: resource.description,
+    };
+}
+function references(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return undefined;
+    const output = value.split(',').map((reference) => reference.trim()).filter(Boolean).map((reference) => ({ reference }));
+    return output.length ? output : undefined;
+}
+function scalarNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? String(value) : undefined;
+}
+function numberValue(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return undefined;
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
+}

package/dist/converters/index.d.ts

@@ -15,6 +15,7 @@ export * from './convert-document-reference.js';
 export * from './convert-encounter.js';
 export * from './convert-flag.js';
 export * from './convert-immunization.js';
+export * from './convert-imaging-study.js';
 export * from './convert-location.js';
 export * from './convert-medication-statement.js';
 export * from './convert-observation.js';

package/dist/converters/index.js

@@ -15,6 +15,7 @@ export * from './convert-document-reference.js';
 export * from './convert-encounter.js';
 export * from './convert-flag.js';
 export * from './convert-immunization.js';
+export * from './convert-imaging-study.js';
 export * from './convert-location.js';
 export * from './convert-medication-statement.js';
 export * from './convert-observation.js';

package/dist/index.d.ts

@@ -22,3 +22,4 @@ export * from './research-study-r5.js';
 export * from './fhir-tokens.js';
 export * from './related-person.js';
 export * from './imaging-types.js';
+export * from './subscription-r5.js';

package/dist/index.js

@@ -22,3 +22,4 @@ export * from './research-study-r5.js';
 export * from './fhir-tokens.js';
 export * from './related-person.js';
 export * from './imaging-types.js';
+export * from './subscription-r5.js';

package/dist/subscription-r5.d.ts

@@ -0,0 +1,150 @@
+import type { FhirResource } from './fhir-types.js';
+/** FHIR R5 version implemented by this native subscription boundary. */
+export declare const SubscriptionR5Version: "5.0.0";
+export declare const SubscriptionR5ChannelType: Readonly<{
+    readonly RestHook: "rest-hook";
+}>;
+export declare const SubscriptionR5Content: Readonly<{
+    readonly Empty: "empty";
+    readonly IdOnly: "id-only";
+    readonly FullResource: "full-resource";
+}>;
+export declare const SubscriptionR5Status: Readonly<{
+    readonly Requested: "requested";
+    readonly Active: "active";
+    readonly Error: "error";
+    readonly Off: "off";
+    readonly EnteredInError: "entered-in-error";
+}>;
+export declare const SubscriptionTopicR5Status: Readonly<{
+    readonly Draft: "draft";
+    readonly Active: "active";
+    readonly Retired: "retired";
+    readonly Unknown: "unknown";
+}>;
+export declare const SubscriptionR5NotificationType: Readonly<{
+    readonly Handshake: "handshake";
+    readonly Heartbeat: "heartbeat";
+    readonly EventNotification: "event-notification";
+    readonly QueryStatus: "query-status";
+}>;
+export declare const SubscriptionR5BundleType: Readonly<{
+    readonly Notification: "subscription-notification";
+}>;
+export declare const SubscriptionR5MediaType: "application/fhir+json";
+export declare const FhirFlatClaimContext: Readonly<{
+    readonly Api: "org.hl7.fhir.api";
+}>;
+export declare const CommunicationStatus: Readonly<{
+    readonly Completed: "completed";
+}>;
+export declare const CommunicationCategoryCode: Readonly<{
+    readonly Notification: "notification";
+}>;
+export declare const TaskStatusCode: Readonly<{
+    readonly Completed: "completed";
+    readonly Failed: "failed";
+}>;
+type SearchParameterType = 'date' | 'reference' | 'string' | 'token' | 'uri';
+export type R5SearchParameterDefinition = Readonly<{
+    code: string;
+    type: SearchParameterType;
+    expression: string;
+}>;
+/** Exact Subscription-specific SearchParameters published by FHIR R5 5.0.0. */
+export declare const SubscriptionR5SearchParameterCatalog: readonly R5SearchParameterDefinition[];
+/** Exact SubscriptionTopic-specific SearchParameters published by FHIR R5 5.0.0. */
+export declare const SubscriptionTopicR5SearchParameterCatalog: readonly R5SearchParameterDefinition[];
+export type SubscriptionR5Filter = Readonly<{
+    resourceType?: string;
+    filterParameter: string;
+    comparator?: 'eq' | 'ne';
+    modifier?: string;
+    value: string;
+}>;
+export type SubscriptionR5Parameter = Readonly<{
+    name: string;
+    value: string;
+}>;
+export type SubscriptionR5 = Readonly<{
+    resourceType: 'Subscription';
+    id: string;
+    status: (typeof SubscriptionR5Status)[keyof typeof SubscriptionR5Status];
+    topic: string;
+    reason?: string;
+    filterBy?: readonly SubscriptionR5Filter[];
+    channelType: Readonly<{
+        system: string;
+        code: 'rest-hook';
+    }>;
+    endpoint: string;
+    parameter?: readonly SubscriptionR5Parameter[];
+    contentType: typeof SubscriptionR5MediaType;
+    content: (typeof SubscriptionR5Content)[keyof typeof SubscriptionR5Content];
+}>;
+export type SubscriptionTopicR5 = Readonly<{
+    resourceType: 'SubscriptionTopic';
+    id: string;
+    url: string;
+    status: (typeof SubscriptionTopicR5Status)[keyof typeof SubscriptionTopicR5Status];
+    resourceTrigger: readonly Readonly<{
+        resource: string;
+    }>[];
+    canFilterBy: readonly Readonly<{
+        resource: string;
+        filterParameter: string;
+        comparator: readonly ('eq' | 'ne')[];
+    }>[];
+}>;
+/** Builds the native R5 topic used to notify subscribers about Communication writes. */
+export declare function buildCommunicationSubscriptionTopicR5(input: Readonly<{
+    id: string;
+    url: string;
+}>): SubscriptionTopicR5;
+/** Builds one native R5 rest-hook Subscription. This resource is configuration, not flat clinical state. */
+export declare function buildRestHookSubscriptionR5(input: Readonly<{
+    id: string;
+    topic: string;
+    endpoint: string;
+    filters?: readonly SubscriptionR5Filter[];
+    parameters?: readonly SubscriptionR5Parameter[];
+    content?: SubscriptionR5['content'];
+    reason?: string;
+}>): SubscriptionR5;
+export type TerminalJobStatusCode = (typeof TaskStatusCode)[keyof typeof TaskStatusCode];
+/**
+ * Builds the canonical claims-first Communication emitted when an asynchronous
+ * Task reaches a terminal state. `Communication.status=completed` describes
+ * the sent message; `Communication.content-code` carries the linked Task state.
+ */
+export declare function buildTerminalJobCommunication(input: Readonly<{
+    id: string;
+    threadId: string;
+    jobId: string;
+    jobStatus: TerminalJobStatusCode;
+    recipient: string;
+    sender: string;
+    researchStudyReference: string;
+    sent: string;
+}>): FhirResource & Readonly<{
+    resourceType: 'Communication';
+    id: string;
+    meta: Readonly<{
+        claims: Readonly<Record<string, string>>;
+    }>;
+}>;
+export type ParsedSubscriptionNotificationEventR5 = Readonly<{
+    eventNumber: string;
+    timestamp?: string;
+    focusReference: string;
+    focusResource: FhirResource;
+}>;
+export type ParsedSubscriptionNotificationR5 = Readonly<{
+    type: (typeof SubscriptionR5NotificationType)[keyof typeof SubscriptionR5NotificationType];
+    subscriptionReference: string;
+    topic?: string;
+    events: readonly ParsedSubscriptionNotificationEventR5[];
+}>;
+/** Validates a standard R5 notification Bundle and resolves every advertised full-resource focus. */
+export declare function parseSubscriptionNotificationR5(input: unknown): ParsedSubscriptionNotificationR5;
+export {};

package/dist/subscription-r5.js

@@ -0,0 +1,202 @@
+import { CommunicationClaim } from './claims/communication-claims.js';
+import { FhirCodeSystems } from './constants/fhir-code-systems.js';
+import { ResourceTypesFhirR5 } from './constants/fhir-resource-types.js';
+/** FHIR R5 version implemented by this native subscription boundary. */
+export const SubscriptionR5Version = '5.0.0';
+export const SubscriptionR5ChannelType = Object.freeze({ RestHook: 'rest-hook' });
+export const SubscriptionR5Content = Object.freeze({
+    Empty: 'empty',
+    IdOnly: 'id-only',
+    FullResource: 'full-resource',
+});
+export const SubscriptionR5Status = Object.freeze({
+    Requested: 'requested',
+    Active: 'active',
+    Error: 'error',
+    Off: 'off',
+    EnteredInError: 'entered-in-error',
+});
+export const SubscriptionTopicR5Status = Object.freeze({
+    Draft: 'draft',
+    Active: 'active',
+    Retired: 'retired',
+    Unknown: 'unknown',
+});
+export const SubscriptionR5NotificationType = Object.freeze({
+    Handshake: 'handshake',
+    Heartbeat: 'heartbeat',
+    EventNotification: 'event-notification',
+    QueryStatus: 'query-status',
+});
+export const SubscriptionR5BundleType = Object.freeze({ Notification: 'subscription-notification' });
+export const SubscriptionR5MediaType = 'application/fhir+json';
+export const FhirFlatClaimContext = Object.freeze({ Api: 'org.hl7.fhir.api' });
+export const CommunicationStatus = Object.freeze({ Completed: 'completed' });
+export const CommunicationCategoryCode = Object.freeze({ Notification: 'notification' });
+export const TaskStatusCode = Object.freeze({ Completed: 'completed', Failed: 'failed' });
+const searchParameter = (code, type, expression) => Object.freeze({ code, type, expression });
+/** Exact Subscription-specific SearchParameters published by FHIR R5 5.0.0. */
+export const SubscriptionR5SearchParameterCatalog = Object.freeze([
+    searchParameter('contact', 'token', 'Subscription.contact'),
+    searchParameter('content-level', 'token', 'Subscription.content'),
+    searchParameter('filter-value', 'string', 'Subscription.filterBy.value'),
+    searchParameter('identifier', 'token', 'Subscription.identifier'),
+    searchParameter('name', 'string', 'Subscription.name'),
+    searchParameter('owner', 'reference', 'Subscription.managingEntity'),
+    searchParameter('payload', 'token', 'Subscription.contentType'),
+    searchParameter('status', 'token', 'Subscription.status'),
+    searchParameter('topic', 'uri', 'Subscription.topic'),
+    searchParameter('type', 'token', 'Subscription.channelType'),
+    searchParameter('url', 'uri', 'Subscription.endpoint'),
+]);
+/** Exact SubscriptionTopic-specific SearchParameters published by FHIR R5 5.0.0. */
+export const SubscriptionTopicR5SearchParameterCatalog = Object.freeze([
+    searchParameter('date', 'date', 'SubscriptionTopic.date'),
+    searchParameter('derived-or-self', 'uri', 'SubscriptionTopic.url | SubscriptionTopic.derivedFrom'),
+    searchParameter('effective', 'date', 'SubscriptionTopic.effectivePeriod'),
+    searchParameter('event', 'token', 'SubscriptionTopic.eventTrigger.event'),
+    searchParameter('identifier', 'token', 'SubscriptionTopic.identifier'),
+    searchParameter('resource', 'uri', 'SubscriptionTopic.resourceTrigger.resource | SubscriptionTopic.eventTrigger.resource | SubscriptionTopic.canFilterBy.resource | SubscriptionTopic.notificationShape.resource'),
+    searchParameter('status', 'token', 'SubscriptionTopic.status'),
+    searchParameter('title', 'string', 'SubscriptionTopic.title'),
+    searchParameter('trigger-description', 'string', 'SubscriptionTopic.resourceTrigger.description'),
+    searchParameter('url', 'uri', 'SubscriptionTopic.url'),
+    searchParameter('version', 'token', 'SubscriptionTopic.version'),
+]);
+/** Builds the native R5 topic used to notify subscribers about Communication writes. */
+export function buildCommunicationSubscriptionTopicR5(input) {
+    return Object.freeze({
+        resourceType: ResourceTypesFhirR5.SubscriptionTopic,
+        id: required(input.id, 'subscription_topic_id_required'),
+        url: absoluteHttpsUrl(input.url, 'subscription_topic_url_invalid'),
+        status: SubscriptionTopicR5Status.Active,
+        resourceTrigger: Object.freeze([{ resource: ResourceTypesFhirR5.Communication }]),
+        canFilterBy: Object.freeze([
+            Object.freeze({ resource: ResourceTypesFhirR5.Communication, filterParameter: 'identifier', comparator: Object.freeze(['eq', 'ne']) }),
+            Object.freeze({ resource: ResourceTypesFhirR5.Communication, filterParameter: 'recipient', comparator: Object.freeze(['eq', 'ne']) }),
+            Object.freeze({ resource: ResourceTypesFhirR5.Communication, filterParameter: 'status', comparator: Object.freeze(['eq', 'ne']) }),
+        ]),
+    });
+}
+/** Builds one native R5 rest-hook Subscription. This resource is configuration, not flat clinical state. */
+export function buildRestHookSubscriptionR5(input) {
+    const filters = Object.freeze((input.filters ?? []).map(filter => Object.freeze({
+        ...(filter.resourceType ? { resourceType: required(filter.resourceType, 'subscription_filter_resource_required') } : {}),
+        filterParameter: required(filter.filterParameter, 'subscription_filter_parameter_required'),
+        ...(filter.comparator ? { comparator: filter.comparator } : {}),
+        ...(filter.modifier ? { modifier: filter.modifier } : {}),
+        value: required(filter.value, 'subscription_filter_value_required'),
+    })));
+    const parameters = Object.freeze((input.parameters ?? []).map(parameter => Object.freeze({
+        name: required(parameter.name, 'subscription_parameter_name_required'),
+        value: required(parameter.value, 'subscription_parameter_value_required'),
+    })));
+    return Object.freeze({
+        resourceType: ResourceTypesFhirR5.Subscription,
+        id: required(input.id, 'subscription_id_required'),
+        status: SubscriptionR5Status.Requested,
+        topic: absoluteHttpsUrl(input.topic, 'subscription_topic_url_invalid'),
+        ...(input.reason?.trim() ? { reason: input.reason.trim() } : {}),
+        ...(filters.length ? { filterBy: filters } : {}),
+        channelType: Object.freeze({
+            system: FhirCodeSystems.SubscriptionChannelType,
+            code: SubscriptionR5ChannelType.RestHook,
+        }),
+        endpoint: absoluteHttpsUrl(input.endpoint, 'subscription_endpoint_invalid'),
+        ...(parameters.length ? { parameter: parameters } : {}),
+        contentType: SubscriptionR5MediaType,
+        content: input.content ?? SubscriptionR5Content.FullResource,
+    });
+}
+/**
+ * Builds the canonical claims-first Communication emitted when an asynchronous
+ * Task reaches a terminal state. `Communication.status=completed` describes
+ * the sent message; `Communication.content-code` carries the linked Task state.
+ */
+export function buildTerminalJobCommunication(input) {
+    if (!Object.values(TaskStatusCode).includes(input.jobStatus))
+        throw new TypeError('terminal_job_status_invalid');
+    const sent = required(input.sent, 'terminal_job_sent_required');
+    if (Number.isNaN(Date.parse(sent)))
+        throw new TypeError('terminal_job_sent_invalid');
+    return Object.freeze({
+        resourceType: ResourceTypesFhirR5.Communication,
+        id: required(input.id, 'terminal_job_communication_id_required'),
+        meta: Object.freeze({ claims: Object.freeze({
+                '@context': FhirFlatClaimContext.Api,
+                [CommunicationClaim.Identifier]: required(input.threadId, 'terminal_job_thread_required'),
+                [CommunicationClaim.Status]: CommunicationStatus.Completed,
+                [CommunicationClaim.Category]: `${FhirCodeSystems.CommunicationCategory}|${CommunicationCategoryCode.Notification}`,
+                [CommunicationClaim.Recipient]: required(input.recipient, 'terminal_job_recipient_required'),
+                [CommunicationClaim.Sender]: required(input.sender, 'terminal_job_sender_required'),
+                [CommunicationClaim.Sent]: sent,
+                [CommunicationClaim.Subject]: required(input.researchStudyReference, 'terminal_job_study_required'),
+                [CommunicationClaim.ContentReference]: `${ResourceTypesFhirR5.Task}/${required(input.jobId, 'terminal_job_id_required')}`,
+                [CommunicationClaim.ContentCode]: `${FhirCodeSystems.TaskStatus}|${input.jobStatus}`,
+            }) }),
+    });
+}
+/** Validates a standard R5 notification Bundle and resolves every advertised full-resource focus. */
+export function parseSubscriptionNotificationR5(input) {
+    const bundle = record(input);
+    if (bundle.resourceType !== ResourceTypesFhirR5.Bundle || bundle.type !== SubscriptionR5BundleType.Notification) {
+        throw new TypeError('subscription_notification_bundle_invalid');
+    }
+    const entries = Array.isArray(bundle.entry) ? bundle.entry : [];
+    if (entries.length < 1 || entries.length > 101)
+        throw new TypeError('subscription_notification_entries_invalid');
+    const resources = entries.map(entry => record(record(entry).resource)).filter(resource => resource.resourceType);
+    const status = resources.find(resource => resource.resourceType === ResourceTypesFhirR5.SubscriptionStatus);
+    if (!status)
+        throw new TypeError('subscription_notification_status_missing');
+    const notificationType = required(String(status.type ?? ''), 'subscription_notification_type_missing');
+    if (!Object.values(SubscriptionR5NotificationType).includes(notificationType)) {
+        throw new TypeError('subscription_notification_type_invalid');
+    }
+    const subscriptionReference = required(String(record(status.subscription).reference ?? ''), 'subscription_notification_subscription_missing');
+    const rawEvents = Array.isArray(status.notificationEvent) ? status.notificationEvent : [];
+    if (notificationType === SubscriptionR5NotificationType.EventNotification && rawEvents.length < 1) {
+        throw new TypeError('subscription_notification_event_missing');
+    }
+    const events = rawEvents.map(rawEvent => {
+        const event = record(rawEvent);
+        const focusReference = required(String(record(event.focus).reference ?? ''), 'subscription_notification_focus_missing');
+        const focusResource = resources.find(resource => `${resource.resourceType}/${resource.id ?? ''}` === focusReference);
+        if (!focusResource)
+            throw new TypeError('subscription_notification_focus_missing');
+        return Object.freeze({
+            eventNumber: required(String(event.eventNumber ?? ''), 'subscription_notification_event_number_missing'),
+            ...(event.timestamp ? { timestamp: String(event.timestamp) } : {}),
+            focusReference,
+            focusResource: focusResource,
+        });
+    });
+    return Object.freeze({
+        type: notificationType,
+        subscriptionReference,
+        ...(status.topic ? { topic: String(status.topic) } : {}),
+        events: Object.freeze(events),
+    });
+}
+function absoluteHttpsUrl(value, error) {
+    const text = required(value, error);
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        throw new TypeError(error);
+    }
+    if (url.protocol !== 'https:')
+        throw new TypeError(error);
+    return url.href;
+}
+function required(value, error) {
+    const text = String(value ?? '').trim();
+    if (!text)
+        throw new TypeError(error);
+    return text;
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}

package/docs/UHC_FHIR_UTILS_MIGRATION.md

@@ -28,6 +28,7 @@ and transport assumptions must not be copied.
 | Anonymization field inventory | Test input only | A separately reviewed policy contract; old field lists do not become policy automatically |
 | ATC, LOINC, SNOMED and EMA JSON | Validate before reuse | Terminology service fixtures, never authoritative embedded catalogs |
 | DICOM parsing | Extract later | Separate imaging package; do not add `dicom-parser` to the neutral core |
+| ImagingStudy metadata | Rewrite | Neutral flat claims and R4 projection for subject, encounter, modality, procedure and protected endpoint references; DICOM bytes remain outside |
 | SHA-1 attachment hashing | Retire | No compatibility writer; historical read/verification belongs in a versioned adapter |
 | `MessageHeader` transport conventions | Retire | Transport is outside the FHIR data contract |
 | UHC-branded templates and defaults | Retire or move downstream | Product policy belongs in UHC packages, not here |
@@ -51,6 +52,8 @@ The migration surface is executable rather than documentary only:
 - every migrated claim family has a named catalog and shared list helpers;
 - every migrated product-neutral converter participates in the converter
   round-trip matrix, with rich optional-field fixtures for complex resources;
+- Encounter retains its originating Appointment and ImagingStudy retains
+  searchable metadata without embedding DICOM object bytes;
 - FHIR primitives, typed searches, Bundle traversal and fallback conversion
   have strict success and rejection tests;
 - Immunization graphs and reminders live once under `src/builders/`; the former
@@ -109,7 +112,22 @@ family for every assessment scale.
 | Preserve an obsolete input | Explicit read-only compatibility adapter |
 | Add transport, SMART or persistence behavior | Owning SDK/service, never this package |
 | Add sector terminology or policy | SOS, Vet or UHC data package |
+| Configure an R5 SubscriptionTopic/Subscription | Native builder and official search catalog in `subscription-r5`; registration remains in the owning service |
+| Persist or deliver a subscription event | GW/BFF transport and storage, never this package |
 
 Converters and builders import catalog symbols. Tests may spell native FHIR
 wire fields, but do not duplicate flat-claim paths except when proving that a
 malformed or invented path is rejected.
+
+## Subscription notification boundary
+
+FHIR R5 `SubscriptionTopic` and `Subscription` are native configuration
+resources, not flat clinical persistence. This package owns their strict typed
+builders, the official R5 resource-specific SearchParameter catalogs and the
+parser for `Bundle[type=subscription-notification]`. It also owns the minimal
+claims-first terminal Task `Communication` shape so producers and receivers do
+not duplicate claim paths.
+
+HTTP delivery, authentication, durable outbox/inbox storage and browser or
+email/push fan-out remain in GW, DataConv and the product BFFs. The neutral
+package contains no HTTP client and no gateway policy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhir-data-utils-ts",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "FHIR-version-neutral flat-claim and SearchParameter data utilities",
   "license": "Apache-2.0",
   "type": "module",
@@ -107,6 +107,10 @@
       "types": "./dist/imaging-types.d.ts",
       "default": "./dist/imaging-types.js"
     },
+    "./subscription-r5": {
+      "types": "./dist/subscription-r5.d.ts",
+      "default": "./dist/subscription-r5.js"
+    },
     "./constants": {
       "types": "./dist/constants/index.d.ts",
       "default": "./dist/constants/index.js"