fhir-data-utils-ts 0.2.4

package/dist/flat-claim-resource-graph.js

@@ -0,0 +1,108 @@
+const LEGACY_CONTAINMENT_SUFFIXES = Object.freeze(['.is-contained', '.contained-parent-reference']);
+/** Builds one independent resource entry whose claims all belong to its resource type. */
+export function buildFlatClaimResourceEntry(input) {
+    const entryId = requiredToken(input.entryId, 'flat_claim_entry_id_required');
+    const resourceType = requiredResourceType(input.resourceType);
+    const prefix = `${resourceType}.`;
+    const claims = {};
+    for (const [claim, value] of Object.entries(input.claims)) {
+        if (!claim.startsWith(prefix))
+            throw new TypeError('flat_claim_resource_type_mismatch');
+        if (typeof value !== 'string')
+            throw new TypeError('flat_claim_value_must_be_string');
+        claims[claim] = value.trim();
+    }
+    return Object.freeze({ entryId, reference: `${resourceType}/${entryId}`, resourceType, claims: Object.freeze(claims) });
+}
+/**
+ * Links contained or referenced resources from the parent flat entry.
+ *
+ * The comma-separated `<ParentType>.contained-reference-list` is the only
+ * canonical graph edge. A child remains an independent entry and therefore
+ * never receives `is-contained` or `contained-parent-reference` claims.
+ */
+export function linkFlatClaimResourceEntries(entries, link) {
+    const byId = new Map(entries.map(entry => [entry.entryId, entry]));
+    const parent = byId.get(link.parentEntryId);
+    if (!parent)
+        throw new TypeError('flat_claim_entry_not_found');
+    const children = link.childEntryIds.map(entryId => {
+        const child = byId.get(entryId);
+        if (!child)
+            throw new TypeError('flat_claim_entry_not_found');
+        if (child.entryId === parent.entryId)
+            throw new TypeError('flat_claim_self_reference');
+        return child;
+    });
+    const claimName = `${parent.resourceType}.contained-reference-list`;
+    const references = uniqueCsv([...splitCsv(parent.claims[claimName]), ...children.map(child => child.reference)]);
+    return Object.freeze(entries.map(entry => entry.entryId === parent.entryId
+        ? buildFlatClaimResourceEntry({
+            entryId: entry.entryId,
+            resourceType: entry.resourceType,
+            claims: { ...entry.claims, [claimName]: references.join(',') },
+        })
+        : entry));
+}
+/** Adds language and XHTML narrative source without materializing native FHIR. */
+export function withFlatClaimNarrative(entry, narrative) {
+    const prefix = entry.resourceType;
+    return buildFlatClaimResourceEntry({
+        entryId: entry.entryId,
+        resourceType: entry.resourceType,
+        claims: {
+            ...entry.claims,
+            [`${prefix}.language`]: requiredToken(narrative.language, 'flat_claim_language_required'),
+            [`${prefix}.narrative-status`]: narrative.status,
+            [`${prefix}.xhtml`]: requiredText(narrative.xhtml, 'flat_claim_xhtml_required'),
+        },
+    });
+}
+/** Reads legacy graphs without perpetuating child-owned containment state. */
+export function normalizeLegacyContainedClaims(entry) {
+    const claims = Object.fromEntries(Object.entries(entry.claims).filter(([claim]) => !LEGACY_CONTAINMENT_SUFFIXES.some(suffix => claim.endsWith(suffix))));
+    return buildFlatClaimResourceEntry({ entryId: entry.entryId, resourceType: entry.resourceType, claims });
+}
+/**
+ * Builds one DocumentReference flat entry for a PDF, JPEG or PNG.
+ * Link one or many such entries from any clinical parent with
+ * `linkFlatClaimResourceEntries`; attachment bytes are not duplicated.
+ */
+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'),
+    };
+    if (input.title?.trim())
+        claims['DocumentReference.title'] = input.title.trim();
+    if (input.url?.trim())
+        claims['DocumentReference.url'] = input.url.trim();
+    if (input.dataBase64?.trim())
+        claims['DocumentReference.data'] = input.dataBase64.trim();
+    return buildFlatClaimResourceEntry({ entryId: input.entryId, resourceType: 'DocumentReference', claims });
+}
+function splitCsv(value) {
+    return value?.split(',').map(item => item.trim()).filter(Boolean) ?? [];
+}
+function uniqueCsv(values) {
+    return [...new Set(values.map(value => value.trim()).filter(Boolean))];
+}
+function requiredToken(value, error) {
+    const normalized = value.trim();
+    if (!normalized || normalized.includes(','))
+        throw new TypeError(error);
+    return normalized;
+}
+function requiredText(value, error) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new TypeError(error);
+    return normalized;
+}
+function requiredResourceType(value) {
+    const normalized = requiredToken(value, 'flat_claim_resource_type_required');
+    if (!/^[A-Z][A-Za-z0-9]+$/.test(normalized))
+        throw new TypeError('flat_claim_resource_type_invalid');
+    return normalized;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './flat-claim-resource-graph.js';
+export * from './coding-review-flat-claims.js';
+export * from './search-parameters.js';
+export * from './observation-claims.js';
+export * from './vital-sign-observations.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './flat-claim-resource-graph.js';
+export * from './coding-review-flat-claims.js';
+export * from './search-parameters.js';
+export * from './observation-claims.js';
+export * from './vital-sign-observations.js';

package/dist/observation-claims.d.ts

@@ -0,0 +1,132 @@
+/** Canonical code-system URIs used by neutral Observation contracts. */
+export declare const FhirCodeSystem: Readonly<{
+    readonly Loinc: "http://loinc.org";
+    readonly Ucum: "http://unitsofmeasure.org";
+    readonly ObservationCategory: "http://terminology.hl7.org/CodeSystem/observation-category";
+}>;
+export type CodingDescriptor = Readonly<{
+    system: string;
+    code: string;
+    display?: string;
+    claim: string;
+}>;
+/** Canonical HL7 Observation category descriptors. */
+export declare const ObservationCategoryCodes: Readonly<{
+    readonly SocialHistory: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly VitalSigns: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly Imaging: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly Laboratory: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly Procedure: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly Survey: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly Exam: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly Therapy: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly Activity: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+}>;
+/**
+ * Canonical flat claim keys for Observation authoring and projection.
+ *
+ * The `component-*` and `bp-*` keys are read-only migration inputs. They are
+ * not FHIR SearchParameters and must never be emitted by a current writer.
+ */
+export declare const ObservationClaim: Readonly<{
+    readonly BasedOn: "Observation.based-on";
+    readonly Category: "Observation.category";
+    readonly CodeSystem: "Observation.code-system";
+    readonly CodeValue: "Observation.code-value";
+    readonly CodeText: "Observation.code-text";
+    readonly CodeTextLocal: "Observation.code-text";
+    readonly CodeDisplay: "Observation.code-display";
+    readonly Code: "Observation.code";
+    readonly Date: "Observation.date";
+    readonly Device: "Observation.device";
+    readonly Encounter: "Observation.encounter";
+    readonly Focus: "Observation.focus";
+    readonly HasMember: "Observation.has-member";
+    readonly ComponentTags: "Observation.component-tags";
+    readonly ComponentCodeValues: "Observation.component-code-values";
+    readonly ComponentNames: "Observation.component-names";
+    readonly Identifier: "Observation.identifier";
+    readonly Language: "Observation.language";
+    readonly Method: "Observation.method";
+    readonly Patient: "Observation.patient";
+    readonly Performer: "Observation.performer";
+    readonly Specimen: "Observation.specimen";
+    readonly Status: "Observation.status";
+    readonly Subject: "Observation.subject";
+    readonly ValueConcept: "Observation.value-concept";
+    readonly ValueConceptSystem: "Observation.value-concept-system";
+    readonly ValueConceptValue: "Observation.value-concept-value";
+    readonly ValueConceptText: "Observation.value-concept-text";
+    readonly ValueConceptDisplay: "Observation.value-concept-display";
+    readonly ValueDate: "Observation.value-date";
+    readonly ValueQuantityComparator: "Observation.value-quantity-comparator";
+    readonly ValueQuantityNumber: "Observation.value-quantity-number";
+    readonly ValueQuantityUnit: "Observation.value-quantity-unit";
+    readonly ReferenceRangeLowNumber: "Observation.reference-range-low-number";
+    readonly ReferenceRangeHighNumber: "Observation.reference-range-high-number";
+    readonly ReferenceRangeUnit: "Observation.reference-range-unit";
+    readonly ReferenceRangeText: "Observation.reference-range-text";
+    readonly ComponentCode: "Observation.component-code";
+    readonly ComponentCodeDisplay: "Observation.component-code-display";
+    readonly ComponentValueQuantityNumber: "Observation.component-value-quantity-number";
+    readonly ComponentValueQuantityUnit: "Observation.component-value-quantity-unit";
+    readonly ScoreTotalNumber: "Observation.score-total-number";
+    readonly BloodPressureSystolicNumber: "Observation.bp-systolic-number";
+    readonly BloodPressureDiastolicNumber: "Observation.bp-diastolic-number";
+    readonly ValueString: "Observation.value-string";
+    readonly Note: "Observation.note";
+    readonly EffectiveDateTime: "Observation.effective-datetime";
+    /** Custom provenance flag for an explicitly entered or selected result. */
+    readonly UserSelected: "Observation.user-selected";
+}>;
+export type ObservationClaimKey = typeof ObservationClaim[keyof typeof ObservationClaim];
+/**
+ * Reads historical JSON-array and comma-separated component claims.
+ * Compatibility input is normalized in memory and never emitted again.
+ */
+export declare function decodeObservationClaimList(value: string | undefined): readonly unknown[];

package/dist/observation-claims.js

@@ -0,0 +1,96 @@
+/** Canonical code-system URIs used by neutral Observation contracts. */
+export const FhirCodeSystem = Object.freeze({
+    Loinc: 'http://loinc.org',
+    Ucum: 'http://unitsofmeasure.org',
+    ObservationCategory: 'http://terminology.hl7.org/CodeSystem/observation-category',
+});
+function defineCoding(system, code, display) {
+    return Object.freeze({ system, code, display, claim: `${system}|${code}` });
+}
+/** Canonical HL7 Observation category descriptors. */
+export const ObservationCategoryCodes = Object.freeze({
+    SocialHistory: defineCoding(FhirCodeSystem.ObservationCategory, 'social-history', 'Social History'),
+    VitalSigns: defineCoding(FhirCodeSystem.ObservationCategory, 'vital-signs', 'Vital Signs'),
+    Imaging: defineCoding(FhirCodeSystem.ObservationCategory, 'imaging', 'Imaging'),
+    Laboratory: defineCoding(FhirCodeSystem.ObservationCategory, 'laboratory', 'Laboratory'),
+    Procedure: defineCoding(FhirCodeSystem.ObservationCategory, 'procedure', 'Procedure'),
+    Survey: defineCoding(FhirCodeSystem.ObservationCategory, 'survey', 'Survey'),
+    Exam: defineCoding(FhirCodeSystem.ObservationCategory, 'exam', 'Exam'),
+    Therapy: defineCoding(FhirCodeSystem.ObservationCategory, 'therapy', 'Therapy'),
+    Activity: defineCoding(FhirCodeSystem.ObservationCategory, 'activity', 'Activity'),
+});
+/**
+ * Canonical flat claim keys for Observation authoring and projection.
+ *
+ * The `component-*` and `bp-*` keys are read-only migration inputs. They are
+ * not FHIR SearchParameters and must never be emitted by a current writer.
+ */
+export const ObservationClaim = Object.freeze({
+    BasedOn: 'Observation.based-on',
+    Category: 'Observation.category',
+    CodeSystem: 'Observation.code-system',
+    CodeValue: 'Observation.code-value',
+    CodeText: 'Observation.code-text',
+    CodeTextLocal: 'Observation.code-text',
+    CodeDisplay: 'Observation.code-display',
+    Code: 'Observation.code',
+    Date: 'Observation.date',
+    Device: 'Observation.device',
+    Encounter: 'Observation.encounter',
+    Focus: 'Observation.focus',
+    HasMember: 'Observation.has-member',
+    ComponentTags: 'Observation.component-tags',
+    ComponentCodeValues: 'Observation.component-code-values',
+    ComponentNames: 'Observation.component-names',
+    Identifier: 'Observation.identifier',
+    Language: 'Observation.language',
+    Method: 'Observation.method',
+    Patient: 'Observation.patient',
+    Performer: 'Observation.performer',
+    Specimen: 'Observation.specimen',
+    Status: 'Observation.status',
+    Subject: 'Observation.subject',
+    ValueConcept: 'Observation.value-concept',
+    ValueConceptSystem: 'Observation.value-concept-system',
+    ValueConceptValue: 'Observation.value-concept-value',
+    ValueConceptText: 'Observation.value-concept-text',
+    ValueConceptDisplay: 'Observation.value-concept-display',
+    ValueDate: 'Observation.value-date',
+    ValueQuantityComparator: 'Observation.value-quantity-comparator',
+    ValueQuantityNumber: 'Observation.value-quantity-number',
+    ValueQuantityUnit: 'Observation.value-quantity-unit',
+    ReferenceRangeLowNumber: 'Observation.reference-range-low-number',
+    ReferenceRangeHighNumber: 'Observation.reference-range-high-number',
+    ReferenceRangeUnit: 'Observation.reference-range-unit',
+    ReferenceRangeText: 'Observation.reference-range-text',
+    ComponentCode: 'Observation.component-code',
+    ComponentCodeDisplay: 'Observation.component-code-display',
+    ComponentValueQuantityNumber: 'Observation.component-value-quantity-number',
+    ComponentValueQuantityUnit: 'Observation.component-value-quantity-unit',
+    ScoreTotalNumber: 'Observation.score-total-number',
+    BloodPressureSystolicNumber: 'Observation.bp-systolic-number',
+    BloodPressureDiastolicNumber: 'Observation.bp-diastolic-number',
+    ValueString: 'Observation.value-string',
+    Note: 'Observation.note',
+    EffectiveDateTime: 'Observation.effective-datetime',
+    /** Custom provenance flag for an explicitly entered or selected result. */
+    UserSelected: 'Observation.user-selected',
+});
+/**
+ * Reads historical JSON-array and comma-separated component claims.
+ * Compatibility input is normalized in memory and never emitted again.
+ */
+export function decodeObservationClaimList(value) {
+    if (!value)
+        return Object.freeze([]);
+    const normalized = value.trim();
+    if (!normalized)
+        return Object.freeze([]);
+    if (normalized.startsWith('[')) {
+        const parsed = JSON.parse(normalized);
+        if (!Array.isArray(parsed))
+            throw new TypeError('observation_claim_list_invalid');
+        return Object.freeze(parsed);
+    }
+    return Object.freeze(normalized.split(',').map(item => item.trim()));
+}

package/dist/search-parameters.d.ts

@@ -0,0 +1,18 @@
+export type FlatSearchParameterType = 'token' | 'reference' | 'date' | 'string' | 'number' | 'quantity' | 'uri' | 'composite' | 'special';
+export type FlatSearchParameterDefinition = Readonly<{
+    claim: `${string}.${string}`;
+    resourceType: string;
+    elementPath: string;
+    type: FlatSearchParameterType;
+}>;
+/**
+ * Defines one canonical flat claim backed by a standard FHIR SearchParameter.
+ * Channels send `claim`; compatibility `resourceType` and `field` coordinates
+ * are derived from this governed definition and are never accepted as policy.
+ */
+export declare function defineFlatSearchParameter(input: FlatSearchParameterDefinition): FlatSearchParameterDefinition;
+/** Derives compatibility coordinates from governed policy, never from channel input. */
+export declare function legacyFieldCoordinates(definition: FlatSearchParameterDefinition): Readonly<{
+    resourceType: string;
+    field: string;
+}>;

package/dist/search-parameters.js

@@ -0,0 +1,34 @@
+/**
+ * Defines one canonical flat claim backed by a standard FHIR SearchParameter.
+ * Channels send `claim`; compatibility `resourceType` and `field` coordinates
+ * are derived from this governed definition and are never accepted as policy.
+ */
+export function defineFlatSearchParameter(input) {
+    const resourceType = requiredResourceType(input.resourceType);
+    const claim = required(input.claim, 'flat_search_parameter_claim_required');
+    const elementPath = required(input.elementPath, 'flat_search_parameter_element_path_required');
+    if (!claim.startsWith(`${resourceType}.`) || !elementPath.startsWith(`${resourceType}.`)) {
+        throw new TypeError('flat_search_parameter_resource_type_mismatch');
+    }
+    return Object.freeze({ ...input, claim, resourceType, elementPath });
+}
+/** Derives compatibility coordinates from governed policy, never from channel input. */
+export function legacyFieldCoordinates(definition) {
+    const prefix = `${definition.resourceType}.`;
+    const field = definition.elementPath.slice(prefix.length);
+    if (!field)
+        throw new TypeError('flat_search_parameter_element_path_invalid');
+    return Object.freeze({ resourceType: definition.resourceType, field });
+}
+function required(value, error) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new TypeError(error);
+    return normalized;
+}
+function requiredResourceType(value) {
+    const normalized = required(value, 'flat_search_parameter_resource_type_required');
+    if (!/^[A-Z][A-Za-z0-9]+$/.test(normalized))
+        throw new TypeError('flat_search_parameter_resource_type_invalid');
+    return normalized;
+}

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

@@ -0,0 +1,250 @@
+import { type FlatClaimResourceEntry } from './flat-claim-resource-graph.js';
+export { ObservationCategoryCodes, ObservationClaim } from './observation-claims.js';
+/** Canonical LOINC descriptors for supported vital signs. */
+export declare const VitalSignsCodes: Readonly<{
+    readonly BodyWeight: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly HeartRate: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly BloodPressure: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly SystolicBloodPressure: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly DiastolicBloodPressure: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly BodyTemperature: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly OxygenSaturation: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly RespiratoryRate: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+}>;
+/** Canonical UCUM descriptors for supported vital signs. */
+export declare const VitalSignsUnits: Readonly<{
+    readonly BeatsPerMinute: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly MillimeterOfMercury: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly Celsius: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly Percent: Readonly<{
+        system: string;
+        code: string;
+        display?: string;
+        claim: string;
+    }>;
+    readonly Kilogram: 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<{
+    readonly bloodPressure: string;
+    readonly systolic: string;
+    readonly diastolic: string;
+    readonly temperature: string;
+    readonly heartRate: string;
+    readonly oxygenSaturation: string;
+    readonly respiratoryRate: string;
+    readonly bodyWeight: string;
+}>;
+/** UCUM-compatible unit spellings persisted in flat claims. */
+export declare const VitalSignUnit: Readonly<{
+    readonly bloodPressure: string;
+    readonly temperature: string;
+    readonly heartRate: string;
+    readonly oxygenSaturation: string;
+    readonly respiratoryRate: string;
+    readonly bodyWeight: string;
+}>;
+export type VitalSignKind = 'blood-pressure' | 'temperature' | 'heart-rate' | 'oxygen-saturation' | 'respiratory-rate' | 'body-weight';
+export type VitalSignObservationStatus = 'preliminary' | 'final';
+type CommonMeasurement = Readonly<{
+    entryId: string;
+    subjectReference: string;
+    kind: VitalSignKind;
+    measuredAt: string;
+    status: VitalSignObservationStatus;
+    deviceReference?: string;
+    note?: string;
+    userSelected?: boolean;
+}>;
+export type VitalSignMeasurement = CommonMeasurement & (Readonly<{
+    kind: 'blood-pressure';
+    systolic: number;
+    diastolic: number;
+}> | Readonly<{
+    kind: Exclude<VitalSignKind, 'blood-pressure'>;
+    value: number;
+}>);
+/**
+ * Canonical claims-first representation of one native FHIR Observation.
+ *
+ * Component values are independent reduced Observation entries so each one
+ * can be indexed with the ordinary Observation claim catalog. The primary
+ * entry owns the only relationship through `Observation.has-member`.
+ */
+export type VitalSignObservationGraph = Readonly<{
+    primary: FlatClaimResourceEntry;
+    components: readonly FlatClaimResourceEntry[];
+    entries: readonly FlatClaimResourceEntry[];
+}>;
+/**
+ * Builds one timestamped Observation. The device is retained as source; this
+ * helper deliberately never creates a professional performer or attester.
+ */
+export declare function buildVitalSignObservation(input: VitalSignMeasurement): VitalSignObservationGraph;
+export type ObservationComponentQuantity = Readonly<{
+    code: string;
+    display?: string;
+    value: number;
+    unit: string;
+}>;
+/** Restores component values from the canonical graph or legacy scalar/array claims. */
+export declare function parseObservationComponents(source: VitalSignObservationGraph | Readonly<Record<string, string>>): readonly ObservationComponentQuantity[];
+export type ObservationComponentIndexEntry = Readonly<{
+    parentReference: string;
+    componentIndex: number;
+    claims: Readonly<Record<string, string>>;
+}>;
+/**
+ * Creates generic reduced rows for component-level indexes.
+ *
+ * These are internal index projections, not independent native FHIR
+ * Observations. The missing status deliberately keeps them out of normal
+ * top-level Observation results.
+ */
+export declare function materializeObservationComponentIndexEntries(entry: VitalSignObservationGraph | FlatClaimResourceEntry): readonly ObservationComponentIndexEntry[];
+type NativeCoding = Readonly<{
+    system?: string;
+    code: string;
+    display?: string;
+}>;
+type NativeVitalSignObservation = Readonly<{
+    resourceType: 'Observation';
+    id: string;
+    status: string;
+    category: readonly Readonly<{
+        coding: readonly NativeCoding[];
+    }>[];
+    code: Readonly<{
+        coding: readonly NativeCoding[];
+    }>;
+    subject: Readonly<{
+        reference: string;
+    }>;
+    effectiveDateTime: string;
+    device?: Readonly<{
+        reference: string;
+    }>;
+    component?: readonly Readonly<{
+        code: Readonly<{
+            coding: readonly NativeCoding[];
+        }>;
+        valueQuantity: Readonly<{
+            value: number;
+            unit: string;
+            system?: string;
+            code: string;
+        }>;
+    }>[];
+    valueQuantity?: Readonly<{
+        value: number;
+        unit: string;
+        system?: string;
+        code: string;
+    }>;
+}>;
+/** Projects the neutral flat contract at the explicit FHIR R4 boundary. */
+export declare function projectVitalSignObservationR4(entry: VitalSignObservationGraph | FlatClaimResourceEntry): NativeVitalSignObservation;
+/** Projects the neutral flat contract at the explicit FHIR R5 boundary. */
+export declare function projectVitalSignObservationR5(entry: VitalSignObservationGraph | FlatClaimResourceEntry): NativeVitalSignObservation;
+export type VitalSignDeviceReading = Readonly<{
+    entryId: string;
+    kind: 'blood-pressure';
+    measuredAt: string;
+    systolic: number;
+    diastolic: number;
+    note?: string;
+}> | Readonly<{
+    entryId: string;
+    kind: Exclude<VitalSignKind, 'blood-pressure'>;
+    measuredAt: string;
+    value: number;
+    note?: string;
+}>;
+/** Converts a device/API batch to independent preliminary Observations without aggregation. */
+export declare function normalizeVitalSignDeviceBatch(input: Readonly<{
+    subjectReference: string;
+    deviceReference: string;
+    readings: readonly VitalSignDeviceReading[];
+}>): readonly VitalSignObservationGraph[];
+/** Reusable neutral fixtures; consumers and tests must not duplicate wire examples. */
+export declare const VITAL_SIGN_EXAMPLES: Readonly<{
+    subjectReference: "Patient/example-subject";
+    deviceReference: "Device/example-home-monitor";
+    bloodPressure: Readonly<{
+        entryId: "bp-example-1";
+        measuredAt: "2026-09-21T08:15:00-07:00";
+        systolic: 121;
+        diastolic: 79;
+    }>;
+    heartRateBatch: readonly (Readonly<{
+        entryId: "hr-example-1";
+        kind: "heart-rate";
+        measuredAt: "2026-09-20T08:00:00Z";
+        value: 68;
+    }> | Readonly<{
+        entryId: "hr-example-2";
+        kind: "heart-rate";
+        measuredAt: "2026-09-21T08:00:00Z";
+        value: 72;
+    }>)[];
+}>;