fhir-data-utils-ts 0.6.7 → 0.6.9

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+- Preserve locally entered `Observation.code.text` when a terminology code has
+  not yet been confirmed, so profile-aware authoring remains visible and can be
+  coded later without inventing a code.
+
+- Add section-specific Observation authoring profiles for vital signs,
+  laboratory results, social history and pregnancy history. Each profile owns
+  its IPS section, HL7 Observation category and initial claims.
+- Add a reusable synthetic document directory in which every document starts
+  with Composition, points to its Encounter context and shares a chronological
+  parent/child Encounter journey. ResearchSubject is deliberately absent.
+
 - Export data-only, coverage-excluded authoring schemas for the six minimum IPS
   resource families used by shared Personal and Professional forms:
   AllergyIntolerance, MedicationStatement, Immunization, Condition, Procedure

package/README.md

@@ -209,6 +209,19 @@ journeys, emergency ServiceRequest plus triage Task, and cohort
 CommunicationRequest against a frozen Group snapshot. See
 [the contract guide](docs/CARE_EMERGENCY_ALERT_CONTRACTS.md). Product policy,
 access, encryption and delivery do not belong in these builders.
+
+## Clinical documents and Encounter journeys
+
+A FHIR document always starts with `Composition`; `Encounter` is its optional
+care context through `Composition.encounter`, not the document root. The same
+section viewer can therefore render an IPS, emergency note, progress note or
+diagnostic report by reading the Composition title/type and section graph.
+
+Encounter navigation is a separate journey graph. Child service encounters
+use `Encounter.partOf` for the strict care hierarchy and their periods provide
+chronological previous/next navigation. The individual remains the clinical
+subject. `ResearchSubject` is not used for care delivery or document browsing.
+See [Clinical documents and Encounter exploration](docs/CLINICAL_DOCUMENT_ENCOUNTER_EXPLORATION.md).
 # Coding-review workflow
 
 Imported wording remains in the resource's canonical `*-text` flat claim. Each

package/dist/converters/convert-observation.js

@@ -44,9 +44,9 @@ export function observationFromFlatToFhirR4(claims) {
         identifier: claims[ObservationClaim.Identifier] ? [{ value: claims[ObservationClaim.Identifier] }] : undefined,
         status: claims[ObservationClaim.Status],
         category: claims[ObservationClaim.Category] ? claims[ObservationClaim.Category].split(',').map((value) => ({ coding: codingFromValue(value.trim()) })) : undefined,
-        code: codeToken
+        code: codeToken || claims[ObservationClaim.CodeText]
             ? {
-                coding: codeCoding,
+                ...(codeCoding ? { coding: codeCoding } : {}),
                 ...(claims[ObservationClaim.CodeText] ? { text: claims[ObservationClaim.CodeText] } : {}),
             }
             : undefined,

package/dist/data/clinical-document-encounter-journey.data.d.ts

@@ -0,0 +1,172 @@
+/** Product-neutral synthetic document directory linked to a chronological Encounter hierarchy. */
+export declare const FHIR_CLINICAL_DOCUMENT_ENCOUNTER_JOURNEY_TEST_DATA: Readonly<{
+    subject: Readonly<{
+        reference: "Patient/jane-doe-demo";
+        displayName: "Jane Doe";
+    }>;
+    encounterCount: number;
+    documentCount: 3;
+    encounters: readonly (Readonly<{
+        resourceType: "Encounter";
+        id: "admission-demo";
+        status: "in-progress";
+        class: Readonly<{
+            code: "IMP";
+            display: "Inpatient encounter";
+        }>;
+        subject: Readonly<{
+            reference: "Patient/jane-doe-demo";
+        }>;
+        serviceProvider: Readonly<{
+            reference: "Organization/demo-hospital";
+        }>;
+        actualPeriod: Readonly<{
+            start: "2026-10-03T08:00:00Z";
+        }>;
+    }> | Readonly<{
+        resourceType: "Encounter";
+        id: string;
+        status: "completed" | "in-progress";
+        class: Readonly<{
+            code: "IMP";
+            display: "Inpatient encounter";
+        }>;
+        subject: Readonly<{
+            reference: "Patient/jane-doe-demo";
+        }>;
+        serviceType: readonly {
+            concept: Readonly<{
+                text: string;
+            }>;
+        }[];
+        serviceProvider: Readonly<{
+            reference: "Organization/demo-hospital";
+        }>;
+        actualPeriod: Readonly<{
+            end?: string | undefined;
+            start: string;
+        }>;
+        location: readonly {
+            location: Readonly<{
+                reference: `Location/${string}`;
+                display: string;
+            }>;
+        }[];
+        partOf: Readonly<{
+            reference: "Encounter/admission-demo";
+        }>;
+    }>)[];
+    documents: readonly Readonly<{
+        resourceType: "Bundle";
+        id: `bundle-${string}`;
+        identifier: Readonly<{
+            system: "urn:ietf:rfc:3986";
+            value: `urn:uuid:${string}`;
+        }>;
+        type: "document";
+        timestamp: string;
+        entry: readonly (Readonly<{
+            fullUrl: string;
+            resource: Readonly<{
+                resourceType: "Composition";
+                id: string;
+                status: "final";
+                type: Readonly<{
+                    text: string;
+                }>;
+                subject: readonly {
+                    reference: "Patient/jane-doe-demo";
+                }[];
+                encounter: Readonly<{
+                    reference: string;
+                }>;
+                date: string;
+                author: readonly {
+                    reference: string;
+                }[];
+                title: string;
+                section: readonly {
+                    title: string;
+                    entry: readonly {
+                        reference: string;
+                    }[];
+                }[];
+            }>;
+        }> | Readonly<{
+            fullUrl: "Patient/jane-doe-demo";
+            resource: Readonly<{
+                resourceType: "Patient";
+                id: "jane-doe-demo";
+                name: readonly {
+                    given: readonly string[];
+                    family: string;
+                }[];
+            }>;
+        }> | Readonly<{
+            fullUrl: "Organization/demo-hospital";
+            resource: Readonly<{
+                resourceType: "Organization";
+                id: "demo-hospital";
+                name: "Demo Hospital";
+            }>;
+        }> | Readonly<{
+            fullUrl: "Encounter/admission-demo";
+            resource: Readonly<{
+                resourceType: "Encounter";
+                id: "admission-demo";
+                status: "in-progress";
+                class: Readonly<{
+                    code: "IMP";
+                    display: "Inpatient encounter";
+                }>;
+                subject: Readonly<{
+                    reference: "Patient/jane-doe-demo";
+                }>;
+                serviceProvider: Readonly<{
+                    reference: "Organization/demo-hospital";
+                }>;
+                actualPeriod: Readonly<{
+                    start: "2026-10-03T08:00:00Z";
+                }>;
+            }>;
+        }> | Readonly<{
+            fullUrl: string;
+            resource: Readonly<{
+                resourceType: "Encounter";
+                id: string;
+                status: "completed" | "in-progress";
+                class: Readonly<{
+                    code: "IMP";
+                    display: "Inpatient encounter";
+                }>;
+                subject: Readonly<{
+                    reference: "Patient/jane-doe-demo";
+                }>;
+                serviceType: readonly {
+                    concept: Readonly<{
+                        text: string;
+                    }>;
+                }[];
+                serviceProvider: Readonly<{
+                    reference: "Organization/demo-hospital";
+                }>;
+                actualPeriod: Readonly<{
+                    end?: string | undefined;
+                    start: string;
+                }>;
+                location: readonly {
+                    location: Readonly<{
+                        reference: `Location/${string}`;
+                        display: string;
+                    }>;
+                }[];
+                partOf: Readonly<{
+                    reference: "Encounter/admission-demo";
+                }>;
+            }>;
+        }> | Readonly<{
+            fullUrl: string;
+            resource: Readonly<Record<string, unknown>>;
+        }>)[];
+    }>[];
+}>;

package/dist/data/clinical-document-encounter-journey.data.js

@@ -0,0 +1,152 @@
+/** Product-neutral synthetic document directory linked to a chronological Encounter hierarchy. */
+const subject = Object.freeze({
+    reference: 'Patient/jane-doe-demo',
+    displayName: 'Jane Doe',
+});
+const organizationReference = 'Organization/demo-hospital';
+const parentEncounterReference = 'Encounter/admission-demo';
+const parentEncounter = Object.freeze({
+    resourceType: 'Encounter',
+    id: 'admission-demo',
+    status: 'in-progress',
+    class: Object.freeze({ code: 'IMP', display: 'Inpatient encounter' }),
+    subject: Object.freeze({ reference: subject.reference }),
+    serviceProvider: Object.freeze({ reference: organizationReference }),
+    actualPeriod: Object.freeze({ start: '2026-10-03T08:00:00Z' }),
+});
+function stage(input) {
+    return Object.freeze({
+        resourceType: 'Encounter',
+        id: input.id,
+        status: input.status,
+        class: Object.freeze({ code: 'IMP', display: 'Inpatient encounter' }),
+        subject: Object.freeze({ reference: subject.reference }),
+        serviceType: Object.freeze([{ concept: Object.freeze({ text: input.serviceDisplay }) }]),
+        serviceProvider: Object.freeze({ reference: organizationReference }),
+        actualPeriod: Object.freeze({ start: input.start, ...(input.end ? { end: input.end } : {}) }),
+        location: Object.freeze([{ location: Object.freeze({ reference: `Location/${input.id}`, display: input.locationDisplay }) }]),
+        partOf: Object.freeze({ reference: parentEncounterReference }),
+    });
+}
+const emergencyEncounter = stage({
+    id: 'emergency-demo',
+    status: 'completed',
+    serviceDisplay: 'Emergency department',
+    locationDisplay: 'Emergency bay',
+    start: '2026-10-03T08:05:00Z',
+    end: '2026-10-03T10:10:00Z',
+});
+const imagingEncounter = stage({
+    id: 'imaging-demo',
+    status: 'completed',
+    serviceDisplay: 'Diagnostic imaging',
+    locationDisplay: 'Imaging department',
+    start: '2026-10-03T10:10:00Z',
+    end: '2026-10-03T11:00:00Z',
+});
+const intensiveCareEncounter = stage({
+    id: 'intensive-care-demo',
+    status: 'in-progress',
+    serviceDisplay: 'Intensive care',
+    locationDisplay: 'Intensive care unit',
+    start: '2026-10-03T11:00:00Z',
+});
+const encounters = Object.freeze([
+    parentEncounter,
+    emergencyEncounter,
+    imagingEncounter,
+    intensiveCareEncounter,
+]);
+function documentBundle(input) {
+    const compositionReference = `Composition/${input.id}`;
+    const clinicalReference = `${input.clinicalResource.resourceType}/${input.clinicalResource.id}`;
+    const encounterReference = `Encounter/${input.encounter.id}`;
+    const composition = Object.freeze({
+        resourceType: 'Composition',
+        id: input.id,
+        status: 'final',
+        type: Object.freeze({ text: input.type }),
+        subject: Object.freeze([{ reference: subject.reference }]),
+        encounter: Object.freeze({ reference: encounterReference }),
+        date: input.timestamp,
+        author: Object.freeze([{ reference: organizationReference }]),
+        title: input.title,
+        section: Object.freeze([{
+                title: input.sectionTitle,
+                entry: Object.freeze([{ reference: clinicalReference }]),
+            }]),
+    });
+    return Object.freeze({
+        resourceType: 'Bundle',
+        id: `bundle-${input.id}`,
+        identifier: Object.freeze({ system: 'urn:ietf:rfc:3986', value: `urn:uuid:${input.id}` }),
+        type: 'document',
+        timestamp: input.timestamp,
+        entry: Object.freeze([
+            Object.freeze({ fullUrl: compositionReference, resource: composition }),
+            Object.freeze({ fullUrl: subject.reference, resource: Object.freeze({ resourceType: 'Patient', id: 'jane-doe-demo', name: Object.freeze([{ given: Object.freeze(['Jane']), family: 'Doe' }]) }) }),
+            Object.freeze({ fullUrl: organizationReference, resource: Object.freeze({ resourceType: 'Organization', id: 'demo-hospital', name: 'Demo Hospital' }) }),
+            Object.freeze({ fullUrl: parentEncounterReference, resource: parentEncounter }),
+            Object.freeze({ fullUrl: encounterReference, resource: input.encounter }),
+            Object.freeze({ fullUrl: clinicalReference, resource: input.clinicalResource }),
+        ]),
+    });
+}
+const emergencyNote = documentBundle({
+    id: 'emergency-note-demo',
+    title: 'Emergency assessment',
+    type: 'Emergency department note',
+    encounter: emergencyEncounter,
+    sectionTitle: 'Emergency assessment',
+    timestamp: '2026-10-03T10:00:00Z',
+    clinicalResource: Object.freeze({
+        resourceType: 'ClinicalImpression',
+        id: 'emergency-assessment-demo',
+        status: 'completed',
+        subject: Object.freeze({ reference: subject.reference }),
+        encounter: Object.freeze({ reference: `Encounter/${emergencyEncounter.id}` }),
+        summary: 'Initial emergency assessment completed',
+    }),
+});
+const imagingReport = documentBundle({
+    id: 'imaging-report-demo',
+    title: 'Diagnostic imaging report',
+    type: 'Diagnostic imaging report',
+    encounter: imagingEncounter,
+    sectionTitle: 'Imaging result',
+    timestamp: '2026-10-03T10:55:00Z',
+    clinicalResource: Object.freeze({
+        resourceType: 'DiagnosticReport',
+        id: 'imaging-result-demo',
+        status: 'final',
+        subject: Object.freeze({ reference: subject.reference }),
+        encounter: Object.freeze({ reference: `Encounter/${imagingEncounter.id}` }),
+        code: Object.freeze({ text: 'Diagnostic imaging assessment' }),
+        conclusion: 'No acute finding requiring intervention',
+    }),
+});
+const intensiveCareNote = documentBundle({
+    id: 'intensive-care-note-demo',
+    title: 'Intensive care progress note',
+    type: 'Progress note',
+    encounter: intensiveCareEncounter,
+    sectionTitle: 'Current assessment',
+    timestamp: '2026-10-03T11:30:00Z',
+    clinicalResource: Object.freeze({
+        resourceType: 'Observation',
+        id: 'intensive-care-observation-demo',
+        status: 'final',
+        subject: Object.freeze({ reference: subject.reference }),
+        encounter: Object.freeze({ reference: `Encounter/${intensiveCareEncounter.id}` }),
+        code: Object.freeze({ text: 'Current clinical status' }),
+        valueString: 'Stable under continuous monitoring',
+        effectiveDateTime: '2026-10-03T11:25:00Z',
+    }),
+});
+export const FHIR_CLINICAL_DOCUMENT_ENCOUNTER_JOURNEY_TEST_DATA = Object.freeze({
+    subject,
+    encounterCount: encounters.length,
+    documentCount: 3,
+    encounters,
+    documents: Object.freeze([emergencyNote, imagingReport, intensiveCareNote]),
+});

package/dist/data/index.d.ts

@@ -4,3 +4,4 @@ export * from './encounter-transfer.data.js';
 export * from './ips-all-sections.data.js';
 export * from './health-credential-qr.data.js';
 export * from './ips-clinical-artifact-schemas.data.js';
+export * from './clinical-document-encounter-journey.data.js';

package/dist/data/index.js

@@ -4,3 +4,4 @@ export * from './encounter-transfer.data.js';
 export * from './ips-all-sections.data.js';
 export * from './health-credential-qr.data.js';
 export * from './ips-clinical-artifact-schemas.data.js';
+export * from './clinical-document-encounter-journey.data.js';

package/dist/data/ips-all-sections.data.d.ts

@@ -1,4 +1,23 @@
 /** Repository-safe synthetic IPS document used by portal demos and visual tests. */
+/** Canonical LOINC section codes used by the reusable IPS reader and editors. */
+export declare const FHIR_IPS_SECTION_CODES: Readonly<{
+    readonly Problems: "11450-4";
+    readonly Allergies: "48765-2";
+    readonly Medications: "10160-0";
+    readonly Immunizations: "11369-6";
+    readonly DiagnosticResults: "30954-2";
+    readonly Procedures: "47519-4";
+    readonly MedicalDevices: "46264-8";
+    readonly VitalSigns: "8716-3";
+    readonly SocialHistory: "29762-2";
+    readonly Alerts: "104605-1";
+    readonly Goals: "81338-6";
+    readonly AdvanceDirectives: "42348-3";
+    readonly FunctionalStatus: "47420-5";
+    readonly PastIllness: "11348-0";
+    readonly PregnancyHistory: "10162-6";
+    readonly PlanOfCare: "18776-5";
+}>;
 /** Primary IPS section placement for the minimum shared clinical authoring forms. */
 export declare const FHIR_IPS_PRIMARY_AUTHORING_SECTION_CODE_BY_RESOURCE_TYPE: Readonly<{
     readonly Condition: "11450-4";

package/dist/data/ips-all-sections.data.js

@@ -20,14 +20,33 @@ const sectionDefinitions = Object.freeze([
     ['10162-6', 'Pregnancy history', 'Observation', 'Not pregnant'],
     ['18776-5', 'Plan of care', 'CarePlan', 'Emergency follow-up plan'],
 ]);
+/** Canonical LOINC section codes used by the reusable IPS reader and editors. */
+export const FHIR_IPS_SECTION_CODES = Object.freeze({
+    Problems: sectionDefinitions[0][0],
+    Allergies: sectionDefinitions[1][0],
+    Medications: sectionDefinitions[2][0],
+    Immunizations: sectionDefinitions[3][0],
+    DiagnosticResults: sectionDefinitions[4][0],
+    Procedures: sectionDefinitions[5][0],
+    MedicalDevices: sectionDefinitions[6][0],
+    VitalSigns: sectionDefinitions[7][0],
+    SocialHistory: sectionDefinitions[8][0],
+    Alerts: sectionDefinitions[9][0],
+    Goals: sectionDefinitions[10][0],
+    AdvanceDirectives: sectionDefinitions[11][0],
+    FunctionalStatus: sectionDefinitions[12][0],
+    PastIllness: sectionDefinitions[13][0],
+    PregnancyHistory: sectionDefinitions[14][0],
+    PlanOfCare: sectionDefinitions[15][0],
+});
 /** Primary IPS section placement for the minimum shared clinical authoring forms. */
 export const FHIR_IPS_PRIMARY_AUTHORING_SECTION_CODE_BY_RESOURCE_TYPE = Object.freeze({
-    Condition: sectionDefinitions[0][0],
-    AllergyIntolerance: sectionDefinitions[1][0],
-    MedicationStatement: sectionDefinitions[2][0],
-    Immunization: sectionDefinitions[3][0],
-    Procedure: sectionDefinitions[5][0],
-    Observation: sectionDefinitions[7][0],
+    Condition: FHIR_IPS_SECTION_CODES.Problems,
+    AllergyIntolerance: FHIR_IPS_SECTION_CODES.Allergies,
+    MedicationStatement: FHIR_IPS_SECTION_CODES.Medications,
+    Immunization: FHIR_IPS_SECTION_CODES.Immunizations,
+    Procedure: FHIR_IPS_SECTION_CODES.Procedures,
+    Observation: FHIR_IPS_SECTION_CODES.VitalSigns,
 });
 function concept(text, code) {
     return { text, coding: [{ system: SNOMED_SYSTEM, code, display: text }] };

package/dist/data/ips-clinical-artifact-schemas.data.d.ts

@@ -15,6 +15,19 @@ export type FhirIpsClinicalArtifactSchema = Readonly<{
     /** Source-text claims for which a user may explicitly confirm a terminology candidate. */
     terminologyTextClaims: readonly string[];
 }>;
+export declare const FhirIpsObservationArtifactKinds: Readonly<{
+    readonly VitalSigns: "vital-signs";
+    readonly Laboratory: "laboratory";
+    readonly SocialHistory: "social-history";
+    readonly PregnancyHistory: "pregnancy-history";
+}>;
+export type FhirIpsObservationArtifactKind = typeof FhirIpsObservationArtifactKinds[keyof typeof FhirIpsObservationArtifactKinds];
+export type FhirIpsObservationArtifactSchema = FhirIpsClinicalArtifactSchema & Readonly<{
+    kind: FhirIpsObservationArtifactKind;
+    initialClaims: Readonly<Record<string, string>>;
+}>;
+/** Section-specific Observation authoring contracts; a resource type alone is not a sufficient selector. */
+export declare const FHIR_IPS_OBSERVATION_ARTIFACT_SCHEMAS: Readonly<Record<FhirIpsObservationArtifactKind, FhirIpsObservationArtifactSchema>>;
 /**
  * Minimum reusable IPS authoring surface for Personal and Professional portals.
  *

package/dist/data/ips-clinical-artifact-schemas.data.js

@@ -4,8 +4,8 @@ import { ConditionClaim } from '../claims/condition-claims.js';
 import { ImmunizationClaim } from '../claims/immunization-claims.js';
 import { MedicationStatementClaim } from '../claims/medication-statement-claims.js';
 import { ProcedureClaim } from '../claims/procedure-claims.js';
-import { ObservationClaim } from '../observation-claims.js';
-import { FHIR_IPS_PRIMARY_AUTHORING_SECTION_CODE_BY_RESOURCE_TYPE } from './ips-all-sections.data.js';
+import { ObservationCategoryCodes, ObservationClaim } from '../observation-claims.js';
+import { FHIR_IPS_PRIMARY_AUTHORING_SECTION_CODE_BY_RESOURCE_TYPE, FHIR_IPS_SECTION_CODES } from './ips-all-sections.data.js';
 export const FhirIpsClinicalArtifactTypes = Object.freeze({
     AllergyIntolerance: 'AllergyIntolerance',
     MedicationStatement: 'MedicationStatement',
@@ -14,6 +14,60 @@ export const FhirIpsClinicalArtifactTypes = Object.freeze({
     Procedure: 'Procedure',
     Observation: 'Observation',
 });
+export const FhirIpsObservationArtifactKinds = Object.freeze({
+    VitalSigns: 'vital-signs',
+    Laboratory: 'laboratory',
+    SocialHistory: 'social-history',
+    PregnancyHistory: 'pregnancy-history',
+});
+const observationRequiredClaims = Object.freeze([
+    ObservationClaim.Category,
+    ObservationClaim.CodeText,
+    ObservationClaim.Status,
+]);
+const observationOptionalClaims = Object.freeze([
+    ObservationClaim.Code,
+    ObservationClaim.CodeDisplay,
+    ObservationClaim.Date,
+    ObservationClaim.EffectiveDateTime,
+    ObservationClaim.Encounter,
+    ObservationClaim.Performer,
+    ObservationClaim.Method,
+    ObservationClaim.Specimen,
+    ObservationClaim.Device,
+    ObservationClaim.ValueQuantityNumber,
+    ObservationClaim.ValueQuantityUnit,
+    ObservationClaim.ValueString,
+    ObservationClaim.ValueConcept,
+    ObservationClaim.ValueConceptText,
+    ObservationClaim.ValueConceptDisplay,
+    ObservationClaim.ReferenceRangeLowNumber,
+    ObservationClaim.ReferenceRangeHighNumber,
+    ObservationClaim.ReferenceRangeUnit,
+    ObservationClaim.ReferenceRangeText,
+    ObservationClaim.Note,
+]);
+function observationSchema(kind, sectionCode, category) {
+    return Object.freeze({
+        kind,
+        resourceType: FhirIpsClinicalArtifactTypes.Observation,
+        sectionCode,
+        requiredClaims: observationRequiredClaims,
+        optionalClaims: observationOptionalClaims,
+        terminologyTextClaims: Object.freeze([ObservationClaim.CodeText]),
+        initialClaims: Object.freeze({
+            [ObservationClaim.Category]: category,
+            [ObservationClaim.Status]: 'final',
+        }),
+    });
+}
+/** Section-specific Observation authoring contracts; a resource type alone is not a sufficient selector. */
+export const FHIR_IPS_OBSERVATION_ARTIFACT_SCHEMAS = Object.freeze({
+    [FhirIpsObservationArtifactKinds.VitalSigns]: observationSchema(FhirIpsObservationArtifactKinds.VitalSigns, FHIR_IPS_SECTION_CODES.VitalSigns, ObservationCategoryCodes.VitalSigns.claim),
+    [FhirIpsObservationArtifactKinds.Laboratory]: observationSchema(FhirIpsObservationArtifactKinds.Laboratory, FHIR_IPS_SECTION_CODES.DiagnosticResults, ObservationCategoryCodes.Laboratory.claim),
+    [FhirIpsObservationArtifactKinds.SocialHistory]: observationSchema(FhirIpsObservationArtifactKinds.SocialHistory, FHIR_IPS_SECTION_CODES.SocialHistory, ObservationCategoryCodes.SocialHistory.claim),
+    [FhirIpsObservationArtifactKinds.PregnancyHistory]: observationSchema(FhirIpsObservationArtifactKinds.PregnancyHistory, FHIR_IPS_SECTION_CODES.PregnancyHistory, ObservationCategoryCodes.Survey.claim),
+});
 /**
  * Minimum reusable IPS authoring surface for Personal and Professional portals.
  *
@@ -59,10 +113,6 @@ export const FHIR_IPS_CLINICAL_ARTIFACT_SCHEMAS = Object.freeze({
         terminologyTextClaims: Object.freeze([ProcedureClaim.CodeText]),
     }),
     [FhirIpsClinicalArtifactTypes.Observation]: Object.freeze({
-        resourceType: FhirIpsClinicalArtifactTypes.Observation,
-        sectionCode: FHIR_IPS_PRIMARY_AUTHORING_SECTION_CODE_BY_RESOURCE_TYPE.Observation,
-        requiredClaims: Object.freeze([ObservationClaim.Category, ObservationClaim.CodeText, ObservationClaim.Status]),
-        optionalClaims: Object.freeze([ObservationClaim.Code, ObservationClaim.CodeDisplay, ObservationClaim.Date, ObservationClaim.EffectiveDateTime, ObservationClaim.Performer, ObservationClaim.Method, ObservationClaim.Specimen, ObservationClaim.Device, ObservationClaim.ValueQuantityNumber, ObservationClaim.ValueQuantityUnit, ObservationClaim.ValueString, ObservationClaim.ValueConcept, ObservationClaim.ReferenceRangeLowNumber, ObservationClaim.ReferenceRangeHighNumber, ObservationClaim.ReferenceRangeUnit, ObservationClaim.ReferenceRangeText, ObservationClaim.Note]),
-        terminologyTextClaims: Object.freeze([ObservationClaim.CodeText]),
+        ...FHIR_IPS_OBSERVATION_ARTIFACT_SCHEMAS[FhirIpsObservationArtifactKinds.VitalSigns],
     }),
 });

package/docs/CLINICAL_DOCUMENT_ENCOUNTER_EXPLORATION.md

@@ -0,0 +1,41 @@
+# Clinical documents and Encounter exploration
+
+## The two connected graphs
+
+A clinical document is a `Bundle` with `type=document`. Its first resource is
+always a `Composition`. The Composition gives the document its human title,
+type, authorship, subject and sections. IPS is one document profile; an
+emergency note, progress note or diagnostic report uses the same document
+shape with a different Composition type and section set.
+
+The care journey is an Encounter graph, not a ResearchSubject graph. The
+individual remains the subject of each Encounter. A document associates with
+the care step it describes through `Composition.encounter`, and clinical
+entries such as Observation or DiagnosticReport may repeat that Encounter
+reference when their own FHIR definition provides it.
+
+## Navigation
+
+One parent Encounter can represent the admission or overall episode represented
+inside the current provider. Emergency, imaging, surgery, ward and intensive
+care steps can be independent child Encounters linked with `Encounter.partOf`.
+Their actual periods provide a deterministic chronological order for previous
+and next navigation. `EncounterHistory` records status/class/location
+milestones for one Encounter; it does not replace the Encounter hierarchy.
+
+The reusable viewer receives authorized documents and Encounters. Selecting an
+Encounter shows documents whose `Composition.encounter` references it. Opening
+one of those documents renders its Composition sections with the same reader
+used for IPS. Missing permissions remain missing data; the browser must not
+infer or fetch another subject merely because two Encounter references are
+related.
+
+## Write boundaries
+
+- A multi-section attested clinical document is Composition-first.
+- A single-section native update may be sent independently and carries its
+  section at the Communication boundary.
+- Encounter, EncounterHistory, Composition and each clinical entry remain
+  independently persisted claims-first resources.
+- Authorization, audit and provider persistence belong to the BFF/GW; the
+  shared fixture and viewer grant no access.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhir-data-utils-ts",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "FHIR-version-neutral flat-claim and SearchParameter data utilities",
   "license": "Apache-2.0",
   "type": "module",