fhir-data-utils-ts 0.3.2 → 0.3.4

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

@@ -29,6 +29,10 @@ 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.
 
 ## Change with executable contracts
 

package/.codex/skills/preserve-fhir-flat-coding-review/SKILL.md

@@ -19,6 +19,12 @@ redeclare governed claim paths, code systems, UUIDs or example values.
 - Each proposal `field` names the coded target claim. Confirmation writes
   `system|code` to that target and the terminology display to `-display`; it
   must preserve the imported `-text` value.
+- Review state comes only from `meta.codingProposals[].status`. An accepted
+  professional decision sets that proposal's `userSelected=true`; never use
+  `userSelected` as a draft or promotion flag.
+- Group review UI with the package-owned clinical families: allergies and
+  intolerances, procedures, diagnostics and immunizations. Do not duplicate
+  resource-type lists in Vet, UHC or DataConv consumers.
 - A localized generated label may use a language-qualified `-text_<BCP47>`
   companion. It must not overwrite the imported local text before explicit
   review.
@@ -28,6 +34,12 @@ redeclare governed claim paths, code systems, UUIDs or example values.
   `entry[].data[]`.
 - Multiple imported rows may resolve to one stable UUID ResearchSubject. Keep
   every proposal on the clinical resource generated from its source row.
+- Complete each ResearchSubject independently when all of its own mandatory
+  proposals are resolved. Other subjects in the same import thread never block
+  it, and review always resumes from persisted resources without re-upload.
+- Text supplied by an individual, a source table or an automated/device flow
+  may create proposals, but does not mark an inferred code professionally
+  reviewed. Preserve origin/provenance separately from the review decision.
 
 ## Workflow
 

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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.
+- Keep review workflow in `meta.codingProposals[].status`; reserve
+  `userSelected=true` for a code explicitly selected by a reviewer.
+
 ## 0.3.2 - 2026-09-23
 
 - Preserve every coding identity from repeatable AllergyIntolerance and

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;
@@ -111,9 +114,37 @@ 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
 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.
+# Coding-review workflow
+
+Imported wording remains in the resource's canonical `*-text` flat claim. Each
+unconfirmed terminology suggestion lives beside `meta.claims` in the owning
+contained resource's `meta.codingProposals[]`; it is never moved to
+`ResearchSubject.meta`.
+
+Review state comes only from `codingProposals[].status`. A Coding
+`userSelected=true` flat claim records that a human selected the accepted code;
+it is not a draft, publication or promotion flag. Consumers can use the shared
+review families `allergies-intolerances`, `procedures`, `diagnostics` and
+`immunizations` without product-specific literals.

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/coding-review-flat-claims.d.ts

@@ -13,6 +13,7 @@ export type FlatClaimCodingProposal = Readonly<{
     language: string;
     candidates: readonly FlatClaimCodingCandidate[];
     selectedCandidateId?: string;
+    userSelected?: boolean;
 }>;
 export type FlatClaimCodingReviewResource = Readonly<{
     resourceType: string;
@@ -43,6 +44,18 @@ export type ContainedCodingReviewItem = Readonly<{
     resource: FlatClaimCodingReviewResource;
     proposal: FlatClaimCodingProposal;
 }>;
+export declare const CODING_REVIEW_CATEGORIES: Readonly<{
+    readonly AllergiesIntolerances: "allergies-intolerances";
+    readonly Procedures: "procedures";
+    readonly Diagnostics: "diagnostics";
+    readonly Immunizations: "immunizations";
+    readonly Other: "other";
+}>;
+export type CodingReviewCategory = typeof CODING_REVIEW_CATEGORIES[keyof typeof CODING_REVIEW_CATEGORIES];
+/** Map a FHIR resource type to its stable, product-neutral coding-review family. */
+export declare function codingReviewCategoryForResourceType(resourceType: string): CodingReviewCategory;
+/** A proposal remains reviewable until a reviewer accepts, rejects or defers it. */
+export declare function isCodingProposalPending(proposal: FlatClaimCodingProposal): boolean;
 /** Return the canonical local-text companion for a code-like flat claim. */
 export declare function deriveCodingLocalTextClaim(targetClaim: string): string;
 /** Return the official-display companion for a code-like flat claim. */
@@ -66,6 +79,8 @@ export declare function buildFlatClaimCodingReviewResource(input: Readonly<{
 }>): FlatClaimCodingReviewResource;
 /** Traverse every ResearchSubject entry and return resource-scoped proposals. */
 export declare function collectBatchCodingReviewItems(batch: FhirLikeCodingReviewBatch): readonly ContainedCodingReviewItem[];
+/** Return only unresolved contained-resource proposals; resource userSelected is not workflow state. */
+export declare function collectPendingBatchCodingReviewItems(batch: FhirLikeCodingReviewBatch): readonly ContainedCodingReviewItem[];
 /**
  * Confirm one terminology candidate on the resource that owns the proposal.
  * The coded claim and official display are added while the imported local

package/dist/coding-review-flat-claims.js

@@ -1,4 +1,27 @@
 import { buildFlatClaimResourceEntry } from './flat-claim-resource-graph.js';
+export const CODING_REVIEW_CATEGORIES = Object.freeze({
+    AllergiesIntolerances: 'allergies-intolerances',
+    Procedures: 'procedures',
+    Diagnostics: 'diagnostics',
+    Immunizations: 'immunizations',
+    Other: 'other',
+});
+const CODING_REVIEW_RESOURCE_CATEGORIES = Object.freeze({
+    AllergyIntolerance: CODING_REVIEW_CATEGORIES.AllergiesIntolerances,
+    Procedure: CODING_REVIEW_CATEGORIES.Procedures,
+    Condition: CODING_REVIEW_CATEGORIES.Diagnostics,
+    DiagnosticReport: CODING_REVIEW_CATEGORIES.Diagnostics,
+    Observation: CODING_REVIEW_CATEGORIES.Diagnostics,
+    Immunization: CODING_REVIEW_CATEGORIES.Immunizations,
+});
+/** Map a FHIR resource type to its stable, product-neutral coding-review family. */
+export function codingReviewCategoryForResourceType(resourceType) {
+    return CODING_REVIEW_RESOURCE_CATEGORIES[resourceType] ?? CODING_REVIEW_CATEGORIES.Other;
+}
+/** A proposal remains reviewable until a reviewer accepts, rejects or defers it. */
+export function isCodingProposalPending(proposal) {
+    return proposal.status === 'proposed';
+}
 /** Return the canonical local-text companion for a code-like flat claim. */
 export function deriveCodingLocalTextClaim(targetClaim) {
     return `${requiredCodingTarget(targetClaim)}-text`;
@@ -54,6 +77,10 @@ export function collectBatchCodingReviewItems(batch) {
     }
     return Object.freeze(items);
 }
+/** Return only unresolved contained-resource proposals; resource userSelected is not workflow state. */
+export function collectPendingBatchCodingReviewItems(batch) {
+    return Object.freeze(collectBatchCodingReviewItems(batch).filter(item => isCodingProposalPending(item.proposal)));
+}
 /**
  * Confirm one terminology candidate on the resource that owns the proposal.
  * The coded claim and official display are added while the imported local
@@ -72,6 +99,7 @@ export function applyFlatClaimCodingSelection(resource, proposalId, candidateId)
         ...proposal,
         status: 'accepted',
         selectedCandidateId: candidate.id,
+        userSelected: true,
     });
     const updatedProposals = proposals.map((item, index) => (index === proposalIndex ? updatedProposal : item));
     return Object.freeze({
@@ -81,6 +109,7 @@ export function applyFlatClaimCodingSelection(resource, proposalId, candidateId)
                 ...resource.meta.claims,
                 [proposal.field]: `${candidate.system}|${candidate.code}`,
                 [deriveCodingDisplayClaim(proposal.field)]: candidate.display,
+                [`${resource.resourceType}.userSelected`]: 'true',
             }),
             codingProposals: Object.freeze(updatedProposals),
         }),
@@ -116,6 +145,7 @@ const CONDITION_EXPECTED_ACCEPTED_CLAIMS = Object.freeze({
     ...CONDITION_EXAMPLE_RESOURCE.meta.claims,
     [CONDITION_EXAMPLE_INPUT.targetClaim]: `${CONDITION_EXAMPLE_CANDIDATE.system}|${CONDITION_EXAMPLE_CANDIDATE.code}`,
     [deriveCodingDisplayClaim(CONDITION_EXAMPLE_INPUT.targetClaim)]: CONDITION_EXAMPLE_CANDIDATE.display,
+    [`${CONDITION_EXAMPLE_RESOURCE.resourceType}.userSelected`]: 'true',
 });
 /** Package-owned reusable fixture; tests and consumer examples must import it. */
 export const CODING_REVIEW_EXAMPLES = Object.freeze({

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/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

@@ -109,7 +109,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.2",
+  "version": "0.3.4",
   "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"