fhir-data-utils-ts 0.3.4 → 0.3.6

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

@@ -33,6 +33,16 @@ description: Complete or audit migrations, claim catalogs, converters, builders,
   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.
+- 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,24 @@
 # Changelog
 
+## 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
+  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`

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:
@@ -53,6 +60,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

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

@@ -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/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/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/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
@@ -80,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.4",
+  "version": "0.3.6",
   "description": "FHIR-version-neutral flat-claim and SearchParameter data utilities",
   "license": "Apache-2.0",
   "type": "module",