fhir-data-utils-ts 0.3.7 → 0.6.0

package/dist/healthcare-service-specialty-map.js

@@ -0,0 +1,151 @@
+/**
+ * Candidate SNOMED CT C80 to LOINC specialty map supplied for review.
+ *
+ * This is not an official SNOMED or LOINC map. The declared relationship is
+ * preserved so consumers can automate only strict equivalence and present
+ * wider, related, inexact or unmatched rows for professional governance.
+ */
+export const ClinicalSpecialtyMappingEquivalence = Object.freeze({
+    Equivalent: 'equivalent',
+    Wider: 'wider',
+    RelatedTo: 'relatedto',
+    Inexact: 'inexact',
+    Unmatched: 'unmatched',
+});
+const E = ClinicalSpecialtyMappingEquivalence.Equivalent;
+const W = ClinicalSpecialtyMappingEquivalence.Wider;
+const R = ClinicalSpecialtyMappingEquivalence.RelatedTo;
+const I = ClinicalSpecialtyMappingEquivalence.Inexact;
+const U = ClinicalSpecialtyMappingEquivalence.Unmatched;
+const suppliedRows = Object.freeze([
+    ['408467006', 'Adult mental illness', 'LP172958-3', 'Mental health', W],
+    ['394577000', 'Anesthetics', 'LP172918-7', 'Anesthesiology', E],
+    ['394578005', 'Audiological medicine', 'LP172919-5', 'Audiology', I],
+    ['421661004', 'Blood banking and transfusion medicine', 'LP172920-3', 'Blood banking and transfusion medicine', E],
+    ['408462000', 'Burns care', 'LP268363-1', 'Burn management', I],
+    ['394579002', 'Cardiology', 'LA7179-0', 'Medicine.cardiology', E],
+    ['394804000', 'Clinical cytogenetics and molecular genetics', 'LP172929-4', 'Clinical genetics', W],
+    ['394580004', 'Clinical genetics', 'LP172929-4', 'Clinical genetics', E],
+    ['394803006', 'Clinical hematology', 'LP175685-9', 'Hematology', I],
+    ['408480009', 'Clinical immunology', 'LP345043-6', 'Immunology', W],
+    ['408454008', 'Clinical microbiology', 'LP208903-7', 'Pathology - Medical microbiology', I],
+    ['394809005', 'Clinical neuro-physiology', 'LP172931-0', 'Clinical neurophysiology', E],
+    ['394592004', 'Clinical oncology', 'LP172901-3', 'Oncology', I],
+    ['394600006', 'Clinical pharmacology', 'LP220238-2', 'Clinical pharmacology', E],
+    ['394601005', 'Clinical physiology', undefined, undefined, U],
+    ['394581000', 'Community medicine', 'LP204156-6', 'Community health care', I],
+    ['408478003', 'Critical care medicine', 'LP172933-6', 'Critical care medicine', E],
+    ['394812008', 'Dental medicine specialties', 'LP172934-4', 'Dentistry', W],
+    ['408444009', 'Dental-General dental practice', 'LP172934-4', 'Dentistry', W],
+    ['394582007', 'Dermatology', 'LP172935-1', 'Dermatology', E],
+    ['408475000', 'Diabetic medicine', 'LP172938-5', 'Diabetology', E],
+    ['410005002', 'Dive medicine', 'LP173035-9', 'Undersea and hyperbaric medicine', I],
+    ['394583002', 'Endocrinology', 'LP172941-9', 'Endocrinology', E],
+    ['419772000', 'Family practice', 'LP172943-5', 'Family medicine', E],
+    ['394584008', 'Gastroenterology', 'LP172945-0', 'Gastroenterology', E],
+    ['408443003', 'General medical practice', 'LP173010-2', 'Primary care', I],
+    ['394802001', 'General medicine', 'LP172946-8', 'General medicine', E],
+    ['394915009', 'General pathology', 'LP172984-9', 'Pathology', I],
+    ['394814009', 'General practice', 'LP173010-2', 'Primary care', I],
+    ['394808002', 'Genito-urinary medicine', 'LP173036-7', 'Urology', W],
+    ['394811001', 'Geriatric medicine', 'LP172947-6', 'Geriatric medicine', E],
+    ['408446006', 'Gynecological oncology', 'LP202989-2', 'Gynecologic oncology', E],
+    ['394586005', 'Gynecology', 'LP221284-5', 'Gynecology', E],
+    ['394916005', 'Hematopathology', 'LP172984-9', 'Pathology', W],
+    ['408472002', 'Hepatology', 'LP172950-0', 'Hepatology', E],
+    ['394597005', 'Histopathology', 'LP208907-8', 'Anatomic pathology', W],
+    ['394598000', 'Immunopathology', 'LP345043-6', 'Immunology', W],
+    ['394807007', 'Infectious diseases', 'LP172951-8', 'Infectious disease', E],
+    ['419192003', 'Internal medicine', 'LP172952-6', 'Internal medicine', E],
+    ['408468001', 'Learning disability', undefined, undefined, U],
+    ['394593009', 'Medical oncology', 'LP175686-7', 'Medical Oncology', E],
+    ['394813003', 'Medical ophthalmology', 'LP172974-0', 'Ophthalmology', W],
+    ['410001006', 'Military medicine', undefined, undefined, U],
+    ['394589003', 'Nephrology', 'LP172962-5', 'Nephrology', E],
+    ['394591006', 'Neurology', 'LP172964-1', 'Neurology', E],
+    ['394599008', 'Neuropathology', 'LP208907-8', 'Anatomic pathology', W],
+    ['394649004', 'Nuclear medicine', 'LP172968-2', 'Nuclear medicine', E],
+    ['408470005', 'Obstetrics', 'LP221283-7', 'Obstetrics', E],
+    ['394585009', 'Obstetrics and gynecology', 'LP172971-6', 'Obstetrics and gynecology', E],
+    ['394821009', 'Occupational medicine', 'LP172972-4', 'Occupational medicine', E],
+    ['422191005', 'Ophthalmic surgery', 'LP172974-0', 'Ophthalmology', W],
+    ['394594003', 'Ophthalmology', 'LP172974-0', 'Ophthalmology', E],
+    ['416304004', 'Osteopathic manipulative medicine', 'LP434767-2', 'Osteopathic medicine', I],
+    ['418960008', 'Otolaryngology', 'LP172980-7', 'Otolaryngology', E],
+    ['394882004', 'Pain management', 'LP172981-5', 'Pain medicine', I],
+    ['394806003', 'Palliative medicine', 'LP172982-3', 'Palliative care', I],
+    ['394588006', 'Pediatric (Child and adolescent) psychiatry', 'LP172922-9', 'Child and adolescent psychiatry', E],
+    ['408459003', 'Pediatric cardiology', 'LP172985-6', 'Pediatric cardiology', E],
+    ['394607009', 'Pediatric dentistry', 'LP172934-4', 'Dentistry', W],
+    ['419610006', 'Pediatric endocrinology', 'LP172989-8', 'Pediatric endocrinology', E],
+    ['418058008', 'Pediatric gastroenterology', 'LP172990-6', 'Pediatric gastroenterology', E],
+    ['420208008', 'Pediatric genetics', 'LP172956-7', 'Medical genetics', W],
+    ['418652005', 'Pediatric hematology', 'LP172991-4', 'Pediatric hematology-oncology', W],
+    ['418535003', 'Pediatric immunology', 'LP345043-6', 'Immunology', W],
+    ['418862001', 'Pediatric infectious diseases', 'LP172992-2', 'Pediatric infectious diseases', E],
+    ['419365004', 'Pediatric nephrology', 'LP172993-0', 'Pediatric nephrology', E],
+    ['418002000', 'Pediatric oncology', 'LP172991-4', 'Pediatric hematology-oncology', I],
+    ['419983000', 'Pediatric ophthalmology', 'LP172974-0', 'Ophthalmology', W],
+    ['419170002', 'Pediatric pulmonology', 'LP172995-5', 'Pediatric pulmonology', E],
+    ['419472004', 'Pediatric rheumatology', 'LP172998-9', 'Pediatric rheumatology', E],
+    ['394539006', 'Pediatric surgery', 'LP172999-7', 'Pediatric surgery', E],
+    ['420112009', 'Pediatric surgery-bone marrow transplantation', 'LP417851-5', 'Bone Marrow Transplant', I],
+    ['409968004', 'Preventive medicine', 'LP173009-4', 'Preventive medicine', E],
+    ['394587001', 'Psychiatry', 'LP173011-0', 'Psychiatry', E],
+    ['394913002', 'Psychotherapy', 'LP173012-8', 'Psychology', R],
+    ['408440000', 'Public health medicine', 'LP173014-4', 'Public health', I],
+    ['418112009', 'Pulmonary medicine', 'LP173015-1', 'Pulmonary disease', I],
+    ['419815003', 'Radiation oncology', 'LP173016-9', 'Radiation oncology', E],
+    ['394914008', 'Radiology', 'LP173018-5', 'Radiology', E],
+    ['408455009', 'Radiology-Interventional radiology', 'LP172896-5', 'Interventional radiology', E],
+    ['394602003', 'Rehabilitation', 'LP173004-5', 'Physical medicine and rehabilitation', I],
+    ['408447002', 'Respite care', 'LP173240-5', 'Respite', R],
+    ['394810000', 'Rheumatology', 'LP173023-5', 'Rheumatology', E],
+    ['408450004', 'Sleep studies', 'LP248728-0', 'Sleep medicine', I],
+    ['408476004', 'Surgery-Bone and marrow transplantation', 'LP417851-5', 'Bone Marrow Transplant', I],
+    ['408469009', 'Surgery-Breast surgery', 'LA7201-2', 'Surgery.breast', E],
+    ['408466002', 'Surgery-Cardiac surgery', 'LP207300-7', 'Cardiac surgery', E],
+    ['408471009', 'Surgery-Cardiothoracic transplantation', 'LP173033-4', 'Transplant surgery', W],
+    ['408464004', 'Surgery-Colorectal surgery', 'LP172932-8', 'Colon and rectal surgery', E],
+    ['408441001', 'Surgery-Dental-Endodontics', 'LP172934-4', 'Dentistry', W],
+    ['408465003', 'Surgery-Dental-Oral and maxillofacial surgery', 'LP172902-1', 'Oral and maxillofacial surgery', E],
+    ['394605001', 'Surgery-Dental-Oral surgery', 'LP172902-1', 'Oral and maxillofacial surgery', I],
+    ['394608004', 'Surgery-Dental-Orthodontics / Dentistry-surgical-Orthodontics', 'LP172934-4', 'Dentistry', W],
+    ['408461007', 'Surgery-Dental-Periodontal surgery', 'LP172934-4', 'Dentistry', W],
+    ['408460008', 'Prosthodontics / surgical-Prosthodontics', 'LP172934-4', 'Dentistry', W],
+    ['394606000', 'Surgery-Dentistry-Restorative dentistry', 'LP172934-4', 'Dentistry', W],
+    ['408449004', 'Surgery-Dentistry--surgical', 'LP172934-4', 'Dentistry', W],
+    ['418018006', 'Surgery-Dermatologic surgery', 'LP172935-1', 'Dermatology', W],
+    ['394604002', 'Surgery-Ear, nose and throat surgery', 'LP172980-7', 'Otolaryngology', I],
+    ['394609007', 'Surgery-general', 'LA7205-3', 'Surgery.general', E],
+    ['408474001', 'Surgery-Hepatobiliary and pancreatic surgery', 'LP172950-0', 'Hepatology', W],
+    ['394610002', 'Surgery-Neurosurgery', 'LP172963-3', 'Neurological surgery', E],
+    ['394611003', 'Surgery-Plastic surgery', 'LP173006-0', 'Plastic surgery', E],
+    ['408477008', 'Surgery-Transplantation surgery', 'LP173033-4', 'Transplant surgery', E],
+    ['394801008', 'Surgery-Trauma and orthopedics', 'LP434806-8', 'Orthopaedic surgery', I],
+    ['408463005', 'Surgery-Vascular', 'LP173039-1', 'Vascular surgery', E],
+    ['419321007', 'Surgical oncology', 'LP207940-0', 'Surgical oncology', E],
+    ['394576009', 'Surgical-Accident & emergency', 'LP172940-1', 'Emergency medicine', I],
+    ['394590007', 'Thoracic medicine', 'LP173031-8', 'Thoracic and cardiac surgery', R],
+    ['409967009', 'Toxicology', 'LP172957-5', 'Medical toxicology', I],
+    ['408448007', 'Tropical medicine', undefined, undefined, U],
+    ['419043006', 'Urological oncology', 'LP173036-7', 'Urology', W],
+    ['394612005', 'Urology', 'LP173036-7', 'Urology', E],
+    ['394733009', 'Medical specialty--OTHER--NOT LISTED', 'LA46-8', 'Other', I],
+    ['394732004', 'Surgical specialty--OTHER-NOT LISTED', 'LA46-8', 'Other', I],
+]);
+export const SnomedC80ToLoincSpecialtyConceptMap = Object.freeze(suppliedRows.map(([snomedCode, snomedDisplay, loincCode, loincDisplay, equivalence = U]) => Object.freeze({
+    snomedSystem: 'http://snomed.info/sct',
+    snomedCode,
+    snomedDisplay,
+    ...(loincCode ? { loincSystem: 'http://loinc.org', loincCode, loincDisplay } : {}),
+    equivalence,
+    automatic: equivalence === E,
+})));
+/** Returns a portable LOINC specialty only for a strict reviewed equivalence. */
+export function findAutomaticLoincSpecialty(snomedCode) {
+    const mapping = SnomedC80ToLoincSpecialtyConceptMap.find(item => item.snomedCode === snomedCode);
+    if (!mapping?.automatic || !mapping.loincCode || !mapping.loincDisplay)
+        return undefined;
+    return Object.freeze({ system: 'http://loinc.org', code: mapping.loincCode, display: mapping.loincDisplay });
+}

package/dist/index.d.ts

@@ -24,3 +24,5 @@ export * from './fhir-tokens.js';
 export * from './related-person.js';
 export * from './imaging-types.js';
 export * from './subscription-r5.js';
+export * from './healthcare-service-specialty-map.js';
+export * from './appointment-communication-test-data.js';

package/dist/index.js

@@ -24,3 +24,5 @@ export * from './fhir-tokens.js';
 export * from './related-person.js';
 export * from './imaging-types.js';
 export * from './subscription-r5.js';
+export * from './healthcare-service-specialty-map.js';
+export * from './appointment-communication-test-data.js';

package/dist/observation-claims.d.ts

@@ -85,6 +85,7 @@ export declare const ObservationClaim: Readonly<{
     readonly Code: "Observation.code";
     readonly Date: "Observation.date";
     readonly Device: "Observation.device";
+    readonly DerivedFrom: "Observation.derived-from";
     readonly Encounter: "Observation.encounter";
     readonly Focus: "Observation.focus";
     readonly HasMember: "Observation.has-member";
@@ -122,6 +123,8 @@ export declare const ObservationClaim: Readonly<{
     readonly ValueString: "Observation.value-string";
     readonly Note: "Observation.note";
     readonly EffectiveDateTime: "Observation.effective-datetime";
+    /** FHIR EventTiming bucket used by recurring morning/evening capture. */
+    readonly DateWhen: "Observation.date-when";
     /** @deprecated Read-only camelCase key from historical persisted rows. */
     readonly EffectiveDateTimeLegacy: "Observation.effectiveDateTime";
     /** Custom provenance flag for an explicitly entered or selected result. */

package/dist/observation-claims.js

@@ -36,6 +36,7 @@ export const ObservationClaim = Object.freeze({
     Code: 'Observation.code',
     Date: 'Observation.date',
     Device: 'Observation.device',
+    DerivedFrom: 'Observation.derived-from',
     Encounter: 'Observation.encounter',
     Focus: 'Observation.focus',
     HasMember: 'Observation.has-member',
@@ -73,6 +74,8 @@ export const ObservationClaim = Object.freeze({
     ValueString: 'Observation.value-string',
     Note: 'Observation.note',
     EffectiveDateTime: 'Observation.effective-datetime',
+    /** FHIR EventTiming bucket used by recurring morning/evening capture. */
+    DateWhen: 'Observation.date-when',
     /** @deprecated Read-only camelCase key from historical persisted rows. */
     EffectiveDateTimeLegacy: 'Observation.effectiveDateTime',
     /** Custom provenance flag for an explicitly entered or selected result. */

package/dist/vital-sign-observations.d.ts

@@ -71,6 +71,12 @@ export declare const VitalSignsUnits: Readonly<{
         display?: string;
         claim: string;
     }>;
+    readonly Fahrenheit: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
     readonly Percent: Readonly<{
         system: string;
         code: string;
@@ -83,6 +89,12 @@ export declare const VitalSignsUnits: Readonly<{
         display?: string;
         claim: string;
     }>;
+    readonly Pound: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
 }>;
 /** Governed FHIR/LOINC tokens used by every channel that captures vital signs. */
 export declare const VitalSignCode: Readonly<{
@@ -99,19 +111,24 @@ export declare const VitalSignCode: Readonly<{
 export declare const VitalSignUnit: Readonly<{
     readonly bloodPressure: string;
     readonly temperature: string;
+    readonly temperatureFahrenheit: string;
     readonly heartRate: string;
     readonly oxygenSaturation: string;
     readonly respiratoryRate: string;
     readonly bodyWeight: string;
+    readonly bodyWeightPound: string;
 }>;
+export type VitalSignQuantityUnit = typeof VitalSignUnit[keyof typeof VitalSignUnit];
 export type VitalSignKind = 'blood-pressure' | 'temperature' | 'heart-rate' | 'oxygen-saturation' | 'respiratory-rate' | 'body-weight';
-export type VitalSignObservationStatus = 'preliminary' | 'final';
+export type VitalSignObservationStatus = 'registered' | 'preliminary' | 'final';
+export type VitalSignEventTiming = 'MORN' | 'AFT' | 'EVE' | 'NIGHT';
 type CommonMeasurement = Readonly<{
     entryId: string;
     subjectReference: string;
     kind: VitalSignKind;
     measuredAt: string;
     status: VitalSignObservationStatus;
+    eventTiming?: VitalSignEventTiming;
     deviceReference?: string;
     note?: string;
     userSelected?: boolean;
@@ -123,6 +140,7 @@ export type VitalSignMeasurement = CommonMeasurement & (Readonly<{
 }> | Readonly<{
     kind: Exclude<VitalSignKind, 'blood-pressure'>;
     value: number;
+    unit?: VitalSignQuantityUnit;
 }>);
 /**
  * Canonical claims-first representation of one native FHIR Observation.
@@ -218,6 +236,7 @@ export type VitalSignDeviceReading = Readonly<{
     kind: Exclude<VitalSignKind, 'blood-pressure'>;
     measuredAt: string;
     value: number;
+    unit?: VitalSignQuantityUnit;
     note?: string;
 }>;
 /** Converts a device/API batch to independent preliminary Observations without aggregation. */
@@ -226,6 +245,61 @@ export declare function normalizeVitalSignDeviceBatch(input: Readonly<{
     deviceReference: string;
     readings: readonly VitalSignDeviceReading[];
 }>): readonly VitalSignObservationGraph[];
+export type RepeatedVitalSignReading = Readonly<{
+    entryId: string;
+    measuredAt: string;
+    systolic: number;
+    diastolic: number;
+    note?: string;
+}> | Readonly<{
+    entryId: string;
+    measuredAt: string;
+    value: number;
+    unit?: VitalSignQuantityUnit;
+    note?: string;
+}>;
+export type RepeatedVitalSignSession = Readonly<{
+    eventTiming: VitalSignEventTiming;
+    sourceGraphs: readonly VitalSignObservationGraph[];
+    averageGraph: VitalSignObservationGraph;
+    entries: readonly FlatClaimResourceEntry[];
+}>;
+/**
+ * Converts exactly three readings taken two minutes apart into registered raw
+ * evidence plus one preliminary arithmetic mean. Confirmation belongs to the
+ * daily document boundary; this helper never invents an attester.
+ */
+export declare function buildRepeatedVitalSignAverage(input: Readonly<{
+    entryId: string;
+    subjectReference: string;
+    deviceReference?: string;
+    kind: VitalSignKind;
+    eventTiming: VitalSignEventTiming;
+    readings: readonly RepeatedVitalSignReading[];
+}>): RepeatedVitalSignSession;
+export type VitalSignDailyDocument = Readonly<{
+    localDate: string;
+    timeZone: string;
+    status: 'preliminary' | 'final';
+    composition: FlatClaimResourceEntry;
+    observations: readonly VitalSignObservationGraph[];
+    entries: readonly FlatClaimResourceEntry[];
+}>;
+/** Builds one daily FHIR document graph; hashing, indexing and research remain service policy. */
+export declare function buildVitalSignDailyDocument(input: Readonly<{
+    entryId: string;
+    identifier: string;
+    subjectReference: string;
+    authorReference: string;
+    localDate: string;
+    timeZone: string;
+    observationGraphs: readonly VitalSignObservationGraph[];
+}>): VitalSignDailyDocument;
+/** Confirms a preliminary daily document and finalizes its top-level Observations atomically in memory. */
+export declare function finalizeVitalSignDailyDocument(draft: VitalSignDailyDocument, confirmation: Readonly<{
+    attesterReference: string;
+    confirmedAt: string;
+}>): VitalSignDailyDocument;
 /** Reusable neutral fixtures; consumers and tests must not duplicate wire examples. */
 export declare const VITAL_SIGN_EXAMPLES: Readonly<{
     subjectReference: "Patient/example-subject";

package/dist/vital-sign-observations.js

@@ -1,4 +1,5 @@
 import { buildFlatClaimResourceEntry } from './flat-claim-resource-graph.js';
+import { CompositionAttesterModes, CompositionClaim } from './claims/composition-claims.js';
 import { FhirCodeSystem, ObservationCategoryCodes, ObservationClaim, decodeObservationClaimList, } from './observation-claims.js';
 export { ObservationCategoryCodes, ObservationClaim } from './observation-claims.js';
 function defineCoding(system, code, display) {
@@ -20,8 +21,10 @@ export const VitalSignsUnits = Object.freeze({
     BeatsPerMinute: defineCoding(FhirCodeSystem.Ucum, '/min', 'beats/minute'),
     MillimeterOfMercury: defineCoding(FhirCodeSystem.Ucum, 'mm[Hg]', 'mmHg'),
     Celsius: defineCoding(FhirCodeSystem.Ucum, 'Cel', 'degrees Celsius'),
+    Fahrenheit: defineCoding(FhirCodeSystem.Ucum, '[degF]', 'degrees Fahrenheit'),
     Percent: defineCoding(FhirCodeSystem.Ucum, '%', 'percent'),
     Kilogram: defineCoding(FhirCodeSystem.Ucum, 'kg', 'kilogram'),
+    Pound: defineCoding(FhirCodeSystem.Ucum, '[lb_av]', 'pound'),
 });
 /** Governed FHIR/LOINC tokens used by every channel that captures vital signs. */
 export const VitalSignCode = Object.freeze({
@@ -38,10 +41,12 @@ export const VitalSignCode = Object.freeze({
 export const VitalSignUnit = Object.freeze({
     bloodPressure: VitalSignsUnits.MillimeterOfMercury.claim,
     temperature: VitalSignsUnits.Celsius.claim,
+    temperatureFahrenheit: VitalSignsUnits.Fahrenheit.claim,
     heartRate: VitalSignsUnits.BeatsPerMinute.claim,
     oxygenSaturation: VitalSignsUnits.Percent.claim,
     respiratoryRate: VitalSignsUnits.BeatsPerMinute.claim,
     bodyWeight: VitalSignsUnits.Kilogram.claim,
+    bodyWeightPound: VitalSignsUnits.Pound.claim,
 });
 /**
  * Builds one timestamped Observation. The device is retained as source; this
@@ -58,6 +63,8 @@ export function buildVitalSignObservation(input) {
     };
     if (input.deviceReference)
         claims[ObservationClaim.Device] = required(input.deviceReference, 'vital_sign_device_required');
+    if (input.eventTiming)
+        claims[ObservationClaim.DateWhen] = normalizeEventTiming(input.eventTiming);
     if (input.note?.trim())
         claims[ObservationClaim.Note] = input.note.trim();
     if (input.userSelected !== undefined)
@@ -79,7 +86,7 @@ export function buildVitalSignObservation(input) {
     else {
         if (!validPositive(input.value))
             throw new TypeError('vital_sign_value_invalid');
-        const scalar = scalarDefinition(input.kind);
+        const scalar = scalarDefinition(input.kind, input.unit);
         claims[ObservationClaim.Code] = scalar.coding.claim;
         if (scalar.coding.display)
             claims[ObservationClaim.CodeDisplay] = scalar.coding.display;
@@ -213,6 +220,123 @@ export function normalizeVitalSignDeviceBatch(input) {
         });
     }));
 }
+/**
+ * Converts exactly three readings taken two minutes apart into registered raw
+ * evidence plus one preliminary arithmetic mean. Confirmation belongs to the
+ * daily document boundary; this helper never invents an attester.
+ */
+export function buildRepeatedVitalSignAverage(input) {
+    if (input.readings.length !== 3)
+        throw new TypeError('vital_sign_repeated_reading_count_invalid');
+    const instants = input.readings.map(reading => normalizeDateTime(reading.measuredAt));
+    for (let index = 1; index < instants.length; index += 1) {
+        if (Date.parse(instants[index]) - Date.parse(instants[index - 1]) !== 120_000) {
+            throw new TypeError('vital_sign_repeated_reading_cadence_invalid');
+        }
+    }
+    const eventTiming = normalizeEventTiming(input.eventTiming);
+    const sourceGraphs = Object.freeze(input.readings.map(reading => buildVitalSignObservation({
+        ...reading,
+        subjectReference: input.subjectReference,
+        ...(input.deviceReference ? { deviceReference: input.deviceReference } : {}),
+        kind: input.kind,
+        status: 'registered',
+        eventTiming,
+    })));
+    const common = {
+        entryId: input.entryId,
+        subjectReference: input.subjectReference,
+        ...(input.deviceReference ? { deviceReference: input.deviceReference } : {}),
+        kind: input.kind,
+        measuredAt: instants[1],
+        status: 'preliminary',
+        eventTiming,
+        ...(input.kind === 'blood-pressure' ? {} : { unit: repeatedScalarUnit(input.kind, input.readings) }),
+    };
+    const average = input.kind === 'blood-pressure'
+        ? buildVitalSignObservation({
+            ...common,
+            kind: 'blood-pressure',
+            systolic: mean(input.readings.map(reading => bloodPressureValue(reading, 'systolic'))),
+            diastolic: mean(input.readings.map(reading => bloodPressureValue(reading, 'diastolic'))),
+        })
+        : buildVitalSignObservation({
+            ...common,
+            kind: input.kind,
+            value: mean(input.readings.map(scalarReadingValue)),
+        });
+    const derivedFrom = sourceGraphs.map(graph => graph.primary.reference).join(',');
+    const averageGraph = replacePrimaryClaims(average, {
+        ...average.primary.claims,
+        [ObservationClaim.DerivedFrom]: derivedFrom,
+    });
+    return Object.freeze({
+        eventTiming,
+        sourceGraphs,
+        averageGraph,
+        entries: Object.freeze([...sourceGraphs.flatMap(graph => graph.entries), ...averageGraph.entries]),
+    });
+}
+/** Builds one daily FHIR document graph; hashing, indexing and research remain service policy. */
+export function buildVitalSignDailyDocument(input) {
+    const localDate = normalizeLocalDate(input.localDate);
+    const timeZone = normalizeTimeZone(input.timeZone);
+    if (!input.observationGraphs.length)
+        throw new TypeError('vital_sign_daily_observations_required');
+    const seen = new Set();
+    for (const graph of input.observationGraphs) {
+        if (graph.primary.claims[ObservationClaim.Subject] !== input.subjectReference)
+            throw new TypeError('vital_sign_daily_subject_mismatch');
+        const measuredAt = required(graph.primary.claims[ObservationClaim.EffectiveDateTime] ?? '', 'vital_sign_measured_at_required');
+        if (localDateAt(measuredAt, timeZone) !== localDate)
+            throw new TypeError('vital_sign_daily_local_date_mismatch');
+        for (const entry of graph.entries) {
+            if (seen.has(entry.reference))
+                throw new TypeError('vital_sign_daily_entry_duplicate');
+            seen.add(entry.reference);
+        }
+    }
+    const observationReferences = input.observationGraphs.map(graph => graph.primary.reference);
+    const composition = buildFlatClaimResourceEntry({
+        entryId: input.entryId,
+        resourceType: 'Composition',
+        claims: {
+            [CompositionClaim.Identifier]: required(input.identifier, 'vital_sign_daily_identifier_required'),
+            [CompositionClaim.Status]: 'preliminary',
+            [CompositionClaim.Subject]: required(input.subjectReference, 'vital_sign_subject_required'),
+            [CompositionClaim.Author]: required(input.authorReference, 'vital_sign_daily_author_required'),
+            [CompositionClaim.Date]: latestEffectiveDateTime(input.observationGraphs),
+            [CompositionClaim.Type]: `${FhirCodeSystem.Loinc}|8716-3`,
+            [CompositionClaim.Title]: `Daily vital signs ${localDate}`,
+            [CompositionClaim.Entry]: observationReferences.join(','),
+        },
+    });
+    return freezeDailyDocument(localDate, timeZone, 'preliminary', composition, input.observationGraphs);
+}
+/** Confirms a preliminary daily document and finalizes its top-level Observations atomically in memory. */
+export function finalizeVitalSignDailyDocument(draft, confirmation) {
+    if (draft.status !== 'preliminary' || draft.composition.claims[CompositionClaim.Status] !== 'preliminary') {
+        throw new TypeError('vital_sign_daily_preliminary_required');
+    }
+    const confirmedAt = normalizeDateTime(confirmation.confirmedAt);
+    const attesterReference = required(confirmation.attesterReference, 'vital_sign_daily_attester_required');
+    const observations = Object.freeze(draft.observations.map(graph => replacePrimaryClaims(graph, {
+        ...graph.primary.claims,
+        [ObservationClaim.Status]: 'final',
+    })));
+    const composition = buildFlatClaimResourceEntry({
+        entryId: draft.composition.entryId,
+        resourceType: 'Composition',
+        claims: {
+            ...draft.composition.claims,
+            [CompositionClaim.Status]: 'final',
+            [CompositionClaim.Attester]: attesterReference,
+            [CompositionClaim.AttesterMode]: CompositionAttesterModes.Professional,
+            [CompositionClaim.AttesterTime]: confirmedAt,
+        },
+    });
+    return freezeDailyDocument(draft.localDate, draft.timeZone, 'final', composition, observations);
+}
 function buildBloodPressureComponent(input, role, value, coding) {
     const entryId = `${required(input.entryId, 'vital_sign_entry_id_required')}-${role}`;
     const claims = {
@@ -228,6 +352,8 @@ function buildBloodPressureComponent(input, role, value, coding) {
         claims[ObservationClaim.CodeDisplay] = coding.display;
     if (input.deviceReference)
         claims[ObservationClaim.Device] = required(input.deviceReference, 'vital_sign_device_required');
+    if (input.eventTiming)
+        claims[ObservationClaim.DateWhen] = normalizeEventTiming(input.eventTiming);
     return buildFlatClaimResourceEntry({ entryId, resourceType: 'Observation', claims });
 }
 function freezeObservationGraph(primary, components) {
@@ -248,14 +374,20 @@ function componentQuantityFromEntry(entry) {
     const display = entry.claims[ObservationClaim.CodeDisplay];
     return Object.freeze({ code, ...(display ? { display } : {}), value, unit });
 }
-function scalarDefinition(kind) {
-    switch (kind) {
-        case 'temperature': return { coding: VitalSignsCodes.BodyTemperature, unit: VitalSignUnit.temperature };
-        case 'heart-rate': return { coding: VitalSignsCodes.HeartRate, unit: VitalSignUnit.heartRate };
-        case 'oxygen-saturation': return { coding: VitalSignsCodes.OxygenSaturation, unit: VitalSignUnit.oxygenSaturation };
-        case 'respiratory-rate': return { coding: VitalSignsCodes.RespiratoryRate, unit: VitalSignUnit.respiratoryRate };
-        case 'body-weight': return { coding: VitalSignsCodes.BodyWeight, unit: VitalSignUnit.bodyWeight };
-    }
+function scalarDefinition(kind, requestedUnit) {
+    const definition = (() => {
+        switch (kind) {
+            case 'temperature': return { coding: VitalSignsCodes.BodyTemperature, units: [VitalSignUnit.temperature, VitalSignUnit.temperatureFahrenheit] };
+            case 'heart-rate': return { coding: VitalSignsCodes.HeartRate, units: [VitalSignUnit.heartRate] };
+            case 'oxygen-saturation': return { coding: VitalSignsCodes.OxygenSaturation, units: [VitalSignUnit.oxygenSaturation] };
+            case 'respiratory-rate': return { coding: VitalSignsCodes.RespiratoryRate, units: [VitalSignUnit.respiratoryRate] };
+            case 'body-weight': return { coding: VitalSignsCodes.BodyWeight, units: [VitalSignUnit.bodyWeight, VitalSignUnit.bodyWeightPound] };
+        }
+    })();
+    const unit = requestedUnit ?? definition.units[0];
+    if (!definition.units.includes(unit))
+        throw new TypeError('vital_sign_unit_invalid');
+    return { coding: definition.coding, unit };
 }
 function normalizeDateTime(value) {
     const date = new Date(value);
@@ -263,6 +395,90 @@ function normalizeDateTime(value) {
         throw new TypeError('vital_sign_measured_at_invalid');
     return date.toISOString();
 }
+function normalizeEventTiming(value) {
+    if (value === 'MORN' || value === 'AFT' || value === 'EVE' || value === 'NIGHT')
+        return value;
+    throw new TypeError('vital_sign_event_timing_invalid');
+}
+function mean(values) {
+    if (values.length === 0 || values.some(value => !validPositive(value)))
+        throw new TypeError('vital_sign_value_invalid');
+    return Math.round((values.reduce((total, value) => total + value, 0) / values.length) * 10) / 10;
+}
+function bloodPressureValue(reading, key) {
+    if (!('systolic' in reading) || !('diastolic' in reading))
+        throw new TypeError('blood_pressure_values_invalid');
+    const value = key === 'systolic' ? reading.systolic : reading.diastolic;
+    if (typeof value !== 'number')
+        throw new TypeError('blood_pressure_values_invalid');
+    return value;
+}
+function scalarReadingValue(reading) {
+    if (!('value' in reading) || typeof reading.value !== 'number')
+        throw new TypeError('vital_sign_value_invalid');
+    return reading.value;
+}
+function repeatedScalarUnit(kind, readings) {
+    const units = readings.map(reading => 'unit' in reading ? reading.unit : undefined);
+    const selected = units.find((unit) => Boolean(unit));
+    if (units.some(unit => unit !== undefined && unit !== selected))
+        throw new TypeError('vital_sign_repeated_unit_mismatch');
+    return scalarDefinition(kind, selected).unit;
+}
+function replacePrimaryClaims(graph, claims) {
+    const primary = buildFlatClaimResourceEntry({
+        entryId: graph.primary.entryId,
+        resourceType: 'Observation',
+        claims,
+    });
+    return freezeObservationGraph(primary, graph.components);
+}
+function freezeDailyDocument(localDate, timeZone, status, composition, observations) {
+    const frozenObservations = Object.freeze([...observations]);
+    return Object.freeze({
+        localDate,
+        timeZone,
+        status,
+        composition,
+        observations: frozenObservations,
+        entries: Object.freeze([composition, ...frozenObservations.flatMap(graph => graph.entries)]),
+    });
+}
+function normalizeLocalDate(value) {
+    const normalized = value.trim();
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(normalized))
+        throw new TypeError('vital_sign_daily_local_date_invalid');
+    const parsed = new Date(`${normalized}T00:00:00.000Z`);
+    if (Number.isNaN(parsed.valueOf()) || parsed.toISOString().slice(0, 10) !== normalized) {
+        throw new TypeError('vital_sign_daily_local_date_invalid');
+    }
+    return normalized;
+}
+function normalizeTimeZone(value) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new TypeError('vital_sign_daily_time_zone_invalid');
+    try {
+        new Intl.DateTimeFormat('en', { timeZone: normalized }).format(0);
+    }
+    catch {
+        throw new TypeError('vital_sign_daily_time_zone_invalid');
+    }
+    return normalized;
+}
+function localDateAt(dateTime, timeZone) {
+    const parts = new Intl.DateTimeFormat('en-CA', {
+        timeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    }).formatToParts(new Date(dateTime));
+    const value = Object.fromEntries(parts.map(part => [part.type, part.value]));
+    return `${value.year}-${value.month}-${value.day}`;
+}
+function latestEffectiveDateTime(graphs) {
+    return graphs.map(graph => required(graph.primary.claims[ObservationClaim.EffectiveDateTime] ?? '', 'vital_sign_measured_at_required')).sort().at(-1);
+}
 function validPositive(value) {
     return Number.isFinite(value) && value > 0;
 }