fhir-runtime 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,4224 @@
+/**
+ * `@medxai/fhir-core` — Public API (Frozen at v0.1.0)
+ *
+ * Re-exports all public types and functions from the six core modules:
+ *   model → parser → context → profile → validator (+ fhirpath internal)
+ *
+ * This file defines the frozen public API surface for @medxai/fhir-core v0.1.
+ * Any symbol exported here is subject to the v0.1 compatibility contract.
+ * See: docs/specs/engine-capability-contract-v0.1.md
+ *      docs/api/fhir-core-api-v0.1.md
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Brand symbol used to distinguish FHIR primitive types at compile time.
+ * This provides nominal typing over TypeScript's structural type system,
+ * preventing accidental assignment between semantically different types
+ * (e.g., assigning a FhirUri to a FhirCode) while maintaining zero runtime overhead.
+ */
+declare const __brand: unique symbol;
+
+/**
+ * How resource references can be aggregated.
+ * @see https://hl7.org/fhir/R4/valueset-resource-aggregation-mode.html
+ */
+export declare type AggregationMode = 'contained' | 'referenced' | 'bundled';
+
+/**
+ * All core definition filenames in dependency order:
+ * base → primitives → complex types → resources.
+ */
+export declare const ALL_CORE_DEFINITIONS: readonly string[];
+
+/**
+ * Interface for all AST nodes in the FHIRPath expression tree.
+ * Each node can evaluate itself given a context and input collection.
+ */
+declare interface Atom {
+    /**
+     * Evaluate this atom against the given input collection.
+     * @param context - The evaluation context (variables, parent scope).
+     * @param input - The input collection of typed values.
+     * @returns The result collection.
+     */
+    eval(context: AtomContext, input: TypedValue[]): TypedValue[];
+    /** Returns a string representation of this atom (for debugging). */
+    toString(): string;
+}
+
+/**
+ * Evaluation context for FHIRPath expressions.
+ * Supports nested scoping via the `parent` chain, used by functions
+ * like `where()` and `select()` that introduce `$this`.
+ */
+declare interface AtomContext {
+    readonly parent?: AtomContext;
+    readonly variables: Record<string, TypedValue>;
+}
+
+/**
+ * Base definition for all elements that are defined inside a resource,
+ * but not those in a data type.
+ * @see https://hl7.org/fhir/R4/backboneelement.html
+ */
+export declare interface BackboneElement extends Element {
+    /** Extensions that cannot be ignored even if unrecognized (0..*) */
+    modifierExtension?: Extension[];
+}
+
+/**
+ * Base resource types — the foundation of the FHIR type hierarchy.
+ * These MUST be loaded first as other definitions depend on them.
+ */
+export declare const BASE_RESOURCES: readonly ["Resource", "DomainResource", "Element", "BackboneElement", "Extension"];
+
+/**
+ * Thrown when the base StructureDefinition required for snapshot generation
+ * cannot be loaded from any source.
+ *
+ * This is a fatal error — snapshot generation cannot proceed without the
+ * base profile's snapshot to merge against.
+ *
+ * @example
+ * ```typescript
+ * throw new BaseNotFoundError(
+ *   'http://hl7.org/fhir/StructureDefinition/Patient',
+ *   'http://hl7.org/fhir/StructureDefinition/UnknownBase'
+ * );
+ * ```
+ */
+export declare class BaseNotFoundError extends ProfileError {
+    readonly name = "BaseNotFoundError";
+    /** The canonical URL of the derived profile being generated. */
+    readonly derivedUrl: string;
+    /** The canonical URL of the base that could not be found. */
+    readonly baseUrl: string;
+    constructor(derivedUrl: string, baseUrl: string, cause?: Error);
+}
+
+/**
+ * A resolved value set binding on a canonical element.
+ *
+ * Corresponds to a simplified version of `ElementDefinition.binding`.
+ */
+export declare interface BindingConstraint {
+    /**
+     * required | extensible | preferred | example
+     *
+     * Indicates the degree of conformance expectation.
+     * @see https://hl7.org/fhir/R4/valueset-binding-strength.html
+     */
+    strength: BindingStrength;
+    /**
+     * Canonical URL of the bound value set.
+     *
+     * Resolved from `ElementDefinitionBinding.valueSet`.
+     */
+    valueSetUrl?: string;
+    /** Human-readable description of the binding. */
+    description?: string;
+}
+
+/**
+ * Indication of the degree of conformance expectations associated with a binding.
+ * @see https://hl7.org/fhir/R4/valueset-binding-strength.html
+ */
+export declare type BindingStrength = 'required' | 'extensible' | 'preferred' | 'example';
+
+/**
+ * Generic branded type. Intersects a base type with a unique brand tag.
+ * @typeParam Base - The underlying TypeScript type (string, number, boolean)
+ * @typeParam Brand - A unique string literal identifying the FHIR type
+ */
+declare type Branded<Base, Brand extends string> = Base & {
+    readonly [__brand]: Brand;
+};
+
+/**
+ * Convert ElementDefinitionBinding to BindingConstraint.
+ *
+ * Returns undefined if binding is undefined or has no strength.
+ *
+ * @param binding - The FHIR binding from an ElementDefinition.
+ * @returns Normalized BindingConstraint or undefined.
+ */
+export declare function buildBindingConstraint(binding: ElementDefinitionBinding | undefined): BindingConstraint | undefined;
+
+/**
+ * Convert a single ElementDefinition to a CanonicalElement.
+ *
+ * Applies the following normalizations:
+ * - `max: "*"` → `max: 'unbounded'`; numeric strings → numbers
+ * - `mustSupport/isModifier/isSummary: undefined` → `false`
+ * - `constraint: undefined` → `[]`
+ * - `type: undefined` → `[]`
+ *
+ * @param ed - The ElementDefinition from a snapshot.
+ * @returns The normalized CanonicalElement.
+ */
+export declare function buildCanonicalElement(ed: ElementDefinition): CanonicalElement;
+
+/**
+ * Convert a StructureDefinition (with snapshot) to a CanonicalProfile.
+ *
+ * Precondition: `sd.snapshot` must exist (generated by SnapshotGenerator).
+ * If snapshot is missing, throws an error.
+ *
+ * @param sd - The StructureDefinition with populated snapshot.
+ * @returns The internal CanonicalProfile representation.
+ * @throws Error if sd.snapshot is missing.
+ */
+export declare function buildCanonicalProfile(sd: StructureDefinition): CanonicalProfile;
+
+/**
+ * Convert ElementDefinitionConstraint[] to Invariant[].
+ *
+ * Returns an empty array if constraints is undefined or empty.
+ *
+ * @param constraints - The FHIR constraint array from an ElementDefinition.
+ * @returns Normalized Invariant array.
+ */
+export declare function buildInvariants(constraints: readonly ElementDefinitionConstraint[] | undefined): Invariant[];
+
+/**
+ * Convert ElementDefinitionSlicing to SlicingDefinition.
+ *
+ * Returns undefined if slicing is undefined.
+ * Normalizes `ordered` to boolean (default false).
+ *
+ * @param slicing - The FHIR slicing from an ElementDefinition.
+ * @returns Normalized SlicingDefinition or undefined.
+ */
+export declare function buildSlicingDefinition(slicing: ElementDefinitionSlicing | undefined): SlicingDefinition | undefined;
+
+/**
+ * Convert ElementDefinitionType[] to TypeConstraint[].
+ *
+ * Returns an empty array if types is undefined or empty.
+ *
+ * @param types - The FHIR type array from an ElementDefinition.
+ * @returns Normalized TypeConstraint array.
+ */
+export declare function buildTypeConstraints(types: readonly ElementDefinitionType[] | undefined): TypeConstraint[];
+
+/**
+ * Build a PascalCase type name from path segments.
+ *
+ * @param components - Path segments (e.g., `['Patient', 'contact']`)
+ * @returns PascalCase type name (e.g., `'PatientContact'`)
+ *
+ * @example
+ * ```typescript
+ * buildTypeName(['Patient', 'contact'])  // → 'PatientContact'
+ * buildTypeName(['Bundle', 'entry', 'request'])  // → 'BundleEntryRequest'
+ * buildTypeName(['Patient'])  // → 'Patient'
+ * ```
+ */
+export declare function buildTypeName(components: string[]): string;
+
+/**
+ * Describes a single error encountered while loading a StructureDefinition.
+ */
+export declare interface BundleLoadError {
+    /** The name of the StructureDefinition that failed. */
+    name: string;
+    /** The canonical URL of the StructureDefinition that failed. */
+    url: string;
+    /** The error that occurred. */
+    error: Error;
+    /** Parse issues, if the failure was during parsing. */
+    parseIssues?: readonly ParseIssue[];
+}
+
+/**
+ * Options for filtering which StructureDefinitions to load from a bundle.
+ */
+export declare interface BundleLoadOptions {
+    /** Only include entries where kind matches. Default: all kinds. */
+    filterKind?: StructureDefinitionKind | StructureDefinitionKind[];
+    /** Exclude abstract definitions. Default: false (include abstract). */
+    excludeAbstract?: boolean;
+    /** Only include entries where type matches one of these. */
+    filterTypes?: string[];
+}
+
+/**
+ * Result of loading one or more bundles.
+ */
+export declare interface BundleLoadResult {
+    /** Successfully loaded CanonicalProfiles. */
+    profiles: CanonicalProfile[];
+    /** Errors encountered during loading (partial failures). */
+    errors: BundleLoadError[];
+    /** Summary statistics. */
+    stats: {
+        /** Total StructureDefinition entries found in bundle(s). */
+        total: number;
+        /** Successfully parsed and converted to CanonicalProfile. */
+        loaded: number;
+        /** Filtered out by options (kind, abstract, type). */
+        skipped: number;
+        /** Failed to parse or convert. */
+        failed: number;
+    };
+}
+
+/**
+ * Minimal Bundle shape for type-safe access.
+ */
+declare interface BundleShape {
+    resourceType: string;
+    entry?: Array<{
+        resource?: Record<string, unknown>;
+    }>;
+}
+
+/**
+ * A single resolved element within a CanonicalProfile.
+ *
+ * This is the internal, pre-resolved representation of an
+ * `ElementDefinition` from a StructureDefinition snapshot.
+ * All values are resolved and normalized for efficient downstream use.
+ *
+ * ## Key differences from ElementDefinition
+ *
+ * | Aspect | ElementDefinition (FHIR) | CanonicalElement (internal) |
+ * |--------|--------------------------|----------------------------|
+ * | `max` | `string` (`"1"`, `"*"`) | `number \| 'unbounded'` |
+ * | `mustSupport` | `boolean \| undefined` | `boolean` (always present) |
+ * | `isModifier` | `boolean \| undefined` | `boolean` (always present) |
+ * | `isSummary` | `boolean \| undefined` | `boolean` (always present) |
+ * | `constraints` | `array \| undefined` | `array` (always present, may be empty) |
+ * | `types` | `array \| undefined` | `array` (always present, may be empty) |
+ */
+export declare interface CanonicalElement {
+    /** Element path (e.g., `Patient.name.given`). */
+    path: string;
+    /**
+     * Element id (e.g., `Patient.name.given`).
+     *
+     * In most cases identical to `path`, but may differ for sliced elements
+     * (e.g., `Patient.identifier:MRN`).
+     */
+    id: string;
+    /**
+     * Minimum cardinality.
+     *
+     * Resolved from `ElementDefinition.min`. Always a non-negative integer.
+     */
+    min: number;
+    /**
+     * Maximum cardinality.
+     *
+     * **Design decision:** Uses `number | 'unbounded'` instead of FHIR's
+     * `string` representation. The `"*"` from FHIR is converted to
+     * `'unbounded'` during snapshot resolution, eliminating the need for
+     * downstream code to repeatedly parse the string.
+     */
+    max: number | 'unbounded';
+    /**
+     * Allowed types for this element.
+     *
+     * Always an array (possibly empty). Empty means the element is a
+     * backbone element whose children define its structure.
+     */
+    types: TypeConstraint[];
+    /**
+     * Value set binding, if this element is coded.
+     */
+    binding?: BindingConstraint;
+    /**
+     * Formal constraints (invariants) on this element.
+     *
+     * **Design decision:** Always an array (possibly empty), never
+     * `undefined`. This simplifies downstream iteration — no need to
+     * check for `undefined` before looping.
+     */
+    constraints: Invariant[];
+    /**
+     * Slicing definition, if this element is a slicing root.
+     */
+    slicing?: SlicingDefinition;
+    /**
+     * Whether implementations must meaningfully support this element.
+     *
+     * **Design decision:** Always `boolean`, never `undefined`.
+     * Defaults to `false` during snapshot resolution.
+     */
+    mustSupport: boolean;
+    /**
+     * Whether this element can modify the meaning of other elements.
+     *
+     * **Design decision:** Always `boolean`, never `undefined`.
+     * Defaults to `false` during snapshot resolution.
+     */
+    isModifier: boolean;
+    /**
+     * Whether this element is included in summary views.
+     *
+     * **Design decision:** Always `boolean`, never `undefined`.
+     * Defaults to `false` during snapshot resolution.
+     */
+    isSummary: boolean;
+    /**
+     * Slice name for this element, if it is a named slice.
+     *
+     * Corresponds to `ElementDefinition.sliceName`. Only present on
+     * elements that represent a specific slice within a sliced array.
+     *
+     * @example `'MRN'` for `Patient.identifier:MRN`
+     */
+    sliceName?: string;
+    /**
+     * Fixed value constraint for this element.
+     *
+     * When present, the element value MUST exactly equal this value.
+     * Corresponds to `ElementDefinition.fixed[x]` in the FHIR spec.
+     *
+     * **Design decision:** Stored as `unknown` because fixed values can
+     * be any FHIR type (primitive or complex). The validator performs
+     * deep equality comparison at runtime.
+     */
+    fixed?: unknown;
+    /**
+     * Pattern value constraint for this element.
+     *
+     * When present, the element value must be a superset of this pattern —
+     * all fields in the pattern must exist in the value with matching values,
+     * but the value may contain additional fields.
+     * Corresponds to `ElementDefinition.pattern[x]` in the FHIR spec.
+     *
+     * **Design decision:** Stored as `unknown` for the same reason as `fixed`.
+     */
+    pattern?: unknown;
+}
+
+/**
+ * The internal, resolved representation of a FHIR StructureDefinition.
+ *
+ * A CanonicalProfile is produced by the snapshot generation algorithm
+ * (fhir-profile module) from a StructureDefinition. It flattens the
+ * inheritance chain and resolves all element constraints into a single,
+ * self-contained structure optimized for validation and runtime use.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * // Produced by fhir-profile (Phase 4):
+ * const profile: CanonicalProfile = snapshotGenerator.generate(structureDef);
+ *
+ * // O(1) element lookup:
+ * const nameElement = profile.elements.get('Patient.name');
+ *
+ * // Iteration in definition order (Map preserves insertion order):
+ * for (const [path, element] of profile.elements) { ... }
+ * ```
+ *
+ * ## Design note on `elements` ordering
+ *
+ * JavaScript `Map` preserves insertion order (ES2015+). The fhir-profile
+ * module MUST insert elements in the same order as the snapshot element
+ * array, so that iteration over `elements` yields elements in definition
+ * order. This is important for rendering and for algorithms that depend
+ * on element ordering (e.g., slicing evaluation).
+ */
+export declare interface CanonicalProfile {
+    /**
+     * Canonical URL of this profile.
+     *
+     * Corresponds to `StructureDefinition.url`.
+     */
+    url: string;
+    /**
+     * Business version of this profile.
+     *
+     * Corresponds to `StructureDefinition.version`.
+     */
+    version?: string;
+    /**
+     * Computer-readable name.
+     *
+     * Corresponds to `StructureDefinition.name`.
+     */
+    name: string;
+    /**
+     * The kind of structure: primitive-type | complex-type | resource | logical.
+     *
+     * Corresponds to `StructureDefinition.kind`.
+     */
+    kind: StructureDefinitionKind;
+    /**
+     * The type defined or constrained (e.g., `Patient`, `Observation`).
+     *
+     * Corresponds to `StructureDefinition.type`.
+     */
+    type: string;
+    /**
+     * Canonical URL of the base profile, if any.
+     *
+     * Corresponds to `StructureDefinition.baseDefinition`.
+     */
+    baseProfile?: string;
+    /**
+     * Whether this type is abstract.
+     *
+     * Corresponds to `StructureDefinition.abstract`.
+     */
+    abstract: boolean;
+    /**
+     * specialization | constraint
+     *
+     * Corresponds to `StructureDefinition.derivation`.
+     */
+    derivation?: TypeDerivationRule;
+    /**
+     * All resolved elements, keyed by element path.
+     *
+     * **Design decision:** Uses `Map<string, CanonicalElement>` instead of
+     * an array for O(1) path lookup. `Map` preserves insertion order
+     * (ES2015+), so iteration yields elements in definition order matching
+     * the original snapshot element array.
+     *
+     * The fhir-profile module is responsible for populating this Map in
+     * the correct order during snapshot generation.
+     */
+    elements: Map<string, CanonicalElement>;
+    /**
+     * Inner types extracted from BackboneElement elements.
+     *
+     * Keyed by generated type name (e.g., `'PatientContact'`).
+     * Each inner type is itself a `CanonicalProfile` containing only
+     * the direct child elements of the BackboneElement.
+     *
+     * Populated by {@link extractInnerTypes} after snapshot generation.
+     * Inspired by Medplum's `InternalTypeSchema.innerTypes`.
+     *
+     * @example
+     * ```typescript
+     * const patientProfile = ...;
+     * const contactType = patientProfile.innerTypes?.get('PatientContact');
+     * // contactType.elements has: Patient.contact.relationship, Patient.contact.name, ...
+     * ```
+     */
+    innerTypes?: Map<string, CanonicalProfile>;
+    /**
+     * If this profile is an inner type, the generated type name of its parent.
+     *
+     * For example, `PatientContact` has `parentType: 'Patient'`.
+     * Top-level profiles have `parentType` as `undefined`.
+     */
+    parentType?: string;
+}
+
+/**
+ * Definition of a choice type [x] field.
+ *
+ * Each choice type field has a base name and a set of allowed type suffixes.
+ * The actual JSON property name is `baseName` + one of `allowedTypes`.
+ *
+ * @example
+ * ```typescript
+ * const field: ChoiceTypeField = {
+ *   baseName: 'value',
+ *   allowedTypes: ['String', 'Boolean', 'Integer', 'Quantity', ...],
+ * };
+ * // Matches: valueString, valueBoolean, valueInteger, valueQuantity, ...
+ * ```
+ */
+export declare interface ChoiceTypeField {
+    /** Base property name (e.g., "value", "defaultValue", "fixed") */
+    readonly baseName: string;
+    /** Allowed type suffixes (e.g., ["String", "Boolean", "Quantity"]) */
+    readonly allowedTypes: readonly string[];
+}
+
+/**
+ * Parsed choice type value.
+ *
+ * Preserves the original JSON property name for round-trip serialization.
+ */
+export declare interface ChoiceValue {
+    /** Type suffix (e.g., "String", "Quantity") */
+    readonly typeName: string;
+    /** The actual value from JSON */
+    readonly value: unknown;
+    /** Original JSON property name (e.g., "valueString") — for serialization */
+    readonly propertyName: string;
+    /** _element companion data, if present */
+    readonly elementExtension?: unknown;
+}
+
+/**
+ * Thrown when a circular `baseDefinition` chain is detected during
+ * inheritance resolution.
+ *
+ * @example
+ * ```typescript
+ * throw new CircularDependencyError([
+ *   'http://example.org/A',
+ *   'http://example.org/B',
+ *   'http://example.org/A',  // cycle back to A
+ * ]);
+ * ```
+ */
+export declare class CircularDependencyError extends ContextError {
+    readonly name = "CircularDependencyError";
+    /** The full chain of URLs that forms the cycle */
+    readonly chain: readonly string[];
+    constructor(chain: string[]);
+}
+
+/**
+ * A concept that may be defined by a formal reference to a terminology
+ * or ontology, or may be provided by text.
+ * @see https://hl7.org/fhir/R4/datatypes.html#CodeableConcept
+ */
+export declare interface CodeableConcept extends Element {
+    /** Code defined by a terminology system (0..*) */
+    coding?: Coding[];
+    /** Plain text representation of the concept (0..1) */
+    text?: FhirString;
+}
+
+/**
+ * A reference to a code defined by a terminology system.
+ * @see https://hl7.org/fhir/R4/datatypes.html#Coding
+ */
+export declare interface Coding extends Element {
+    /** Identity of the terminology system (0..1) */
+    system?: FhirUri;
+    /** Version of the system (0..1) */
+    version?: FhirString;
+    /** Symbol in syntax defined by the system (0..1) */
+    code?: FhirCode;
+    /** Representation defined by the system (0..1) */
+    display?: FhirString;
+    /** If this coding was chosen directly by the user (0..1) */
+    userSelected?: FhirBoolean;
+}
+
+/**
+ * Complex types — FHIR complex data types (non-resource).
+ */
+export declare const COMPLEX_TYPES: readonly ["Address", "Age", "Annotation", "Attachment", "CodeableConcept", "Coding", "ContactDetail", "ContactPoint", "Count", "Distance", "Dosage", "Duration", "HumanName", "Identifier", "Meta", "Money", "Narrative", "Period", "Quantity", "Range", "Ratio", "Reference", "SampledData", "Signature", "Timing"];
+
+/**
+ * A loader that delegates to an ordered list of child loaders.
+ *
+ * Resolution stops at the first loader that returns a non-null result.
+ * If a loader throws an error, the error is collected and the next
+ * loader is tried. If all loaders fail or return null, the first
+ * collected error (if any) is thrown.
+ *
+ * This follows the HAPI `ValidationSupportChain` pattern: record
+ * errors from individual loaders but continue trying remaining loaders.
+ *
+ * @example
+ * ```typescript
+ * const composite = new CompositeLoader([memoryLoader, fileLoader]);
+ * const sd = await composite.load(url);
+ * // Tries memoryLoader first, then fileLoader
+ * ```
+ */
+export declare class CompositeLoader implements StructureDefinitionLoader {
+    private readonly _loaders;
+    /**
+     * @param loaders - Ordered list of loaders to try. First match wins.
+     * @throws Error if loaders array is empty
+     */
+    constructor(loaders: StructureDefinitionLoader[]);
+    load(url: string): Promise<StructureDefinition | null>;
+    canLoad(url: string): boolean;
+    getSourceType(): string;
+    /**
+     * Number of child loaders in the chain.
+     */
+    get loaderCount(): number;
+}
+
+/**
+ * The severity of a constraint violation.
+ * @see https://hl7.org/fhir/R4/valueset-constraint-severity.html
+ */
+export declare type ConstraintSeverity = 'error' | 'warning';
+
+/**
+ * Thrown when constraint merging detects an illegal tightening or
+ * incompatible constraint.
+ *
+ * This covers violations such as:
+ * - Cardinality loosening (`derived.min < base.min`)
+ * - Cardinality widening (`derived.max > base.max`)
+ * - Type expansion (derived types not a subset of base types)
+ * - Binding relaxation (relaxing a REQUIRED binding)
+ *
+ * Only thrown when {@link SnapshotGeneratorOptions.throwOnError} is `true`.
+ * Otherwise, violations are recorded as issues in the result.
+ *
+ * @example
+ * ```typescript
+ * throw new ConstraintViolationError(
+ *   'CARDINALITY_VIOLATION',
+ *   'Patient.identifier',
+ *   'Derived min (0) is less than base min (1)'
+ * );
+ * ```
+ */
+export declare class ConstraintViolationError extends ProfileError {
+    readonly name = "ConstraintViolationError";
+    /** The type of constraint violation. */
+    readonly violationType: string;
+    /** The element path where the violation occurred. */
+    readonly path: string;
+    constructor(violationType: string, path: string, message: string);
+}
+
+/**
+ * Contact information for a person or organization.
+ * @see https://hl7.org/fhir/R4/metadatatypes.html#ContactDetail
+ */
+export declare interface ContactDetail extends Element {
+    /** Name of an individual to contact (0..1) */
+    name?: FhirString;
+    /** Contact details for individual or organization (0..*) */
+    telecom?: ContactPoint[];
+}
+
+/**
+ * Details for all kinds of technology-mediated contact points.
+ * @see https://hl7.org/fhir/R4/datatypes.html#ContactPoint
+ */
+export declare interface ContactPoint extends Element {
+    /** phone | fax | email | pager | url | sms | other (0..1) */
+    system?: FhirCode;
+    /** The actual contact point details (0..1) */
+    value?: FhirString;
+    /** home | work | temp | old | mobile (0..1) */
+    use?: FhirCode;
+    /** Specify preferred order of use (0..1) */
+    rank?: FhirPositiveInt;
+    /** Time period when the contact point was/is in use (0..1) */
+    period?: Period;
+}
+
+/**
+ * fhir-context — Error Types
+ *
+ * Structured error hierarchy for the FHIR context module.
+ * All errors extend {@link ContextError} so consumers can catch
+ * context-related failures with a single `catch` clause.
+ *
+ * Error hierarchy:
+ * ```
+ * ContextError (base)
+ * ├── ResourceNotFoundError
+ * ├── CircularDependencyError
+ * ├── LoaderError
+ * └── InvalidStructureDefinitionError
+ * ```
+ *
+ * @module fhir-context
+ */
+/**
+ * Base error class for all fhir-context failures.
+ *
+ * Provides a stable `name` property and preserves the original `cause`
+ * when wrapping lower-level errors.
+ */
+export declare class ContextError extends Error {
+    readonly name: string;
+    constructor(message: string, options?: ErrorOptions);
+}
+
+/**
+ * Runtime metrics for the {@link FhirContext}.
+ *
+ * Useful for monitoring cache effectiveness and diagnosing
+ * performance issues.
+ */
+export declare interface ContextStatistics {
+    /** Total number of StructureDefinitions in the registry */
+    totalLoaded: number;
+    /** Number of `loadStructureDefinition` calls resolved from cache */
+    cacheHits: number;
+    /** Number of `loadStructureDefinition` calls that required loader delegation */
+    cacheMisses: number;
+    /** Total number of loader invocations across all loaders */
+    loaderCalls: number;
+    /** Number of inheritance chains resolved */
+    chainsResolved: number;
+    /** Number of `registerStructureDefinition` calls */
+    registrations: number;
+}
+
+/**
+ * Core clinical resources — commonly used FHIR resource types.
+ */
+export declare const CORE_RESOURCES: readonly ["AllergyIntolerance", "Binary", "Bundle", "CarePlan", "Claim", "CodeSystem", "Condition", "DiagnosticReport", "DocumentReference", "Encounter", "Immunization", "Location", "Medication", "MedicationRequest", "Observation", "Organization", "Patient", "Practitioner", "Procedure", "Questionnaire", "ServiceRequest", "StructureDefinition", "ValueSet"];
+
+/**
+ * Create a {@link DiffElementTracker} for a differential element.
+ *
+ * @param element - The differential ElementDefinition to track.
+ * @returns A tracker with `consumed` set to `false`.
+ */
+export declare function createDiffTracker(element: ElementDefinition): DiffElementTracker;
+
+/**
+ * Create a fresh statistics object with all counters at zero.
+ */
+export declare function createEmptyStatistics(): ContextStatistics;
+
+/**
+ * Create a single parse issue.
+ *
+ * Convenience factory to reduce boilerplate when constructing issues.
+ *
+ * @param severity - Error or warning
+ * @param code - Machine-readable error code
+ * @param message - Human-readable description
+ * @param path - JSON path where the issue was detected
+ */
+export declare function createIssue(severity: ParseSeverity, code: ParseErrorCode, message: string, path: string): ParseIssue;
+
+/**
+ * Create a default MergeContext.
+ */
+export declare function createMergeContext(profileUrl: string, options?: {
+    fhirContext?: FhirContext;
+    maxDepth?: number;
+}): MergeContext;
+
+/**
+ * Create a {@link SnapshotIssue} with the given parameters.
+ *
+ * Convenience factory to reduce boilerplate when recording issues.
+ */
+export declare function createSnapshotIssue(severity: SnapshotIssue['severity'], code: SnapshotIssueCode, message: string, path?: string, details?: string): SnapshotIssue;
+
+/**
+ * Create a {@link ValidationIssue} with the given parameters.
+ *
+ * Convenience factory to reduce boilerplate when recording issues.
+ *
+ * @param severity - Issue severity level.
+ * @param code - Machine-readable issue code.
+ * @param message - Human-readable description.
+ * @param options - Optional path, expression, and diagnostics.
+ * @returns A frozen ValidationIssue object.
+ */
+export declare function createValidationIssue(severity: ValidationIssue['severity'], code: ValidationIssueCode, message: string, options?: {
+    path?: string;
+    expression?: string;
+    diagnostics?: string;
+}): ValidationIssue;
+
+/**
+ * Minimal interface for loading a StructureDefinition by canonical URL.
+ *
+ * This decouples the resolver from the full {@link FhirContext} interface,
+ * making it independently testable. The `FhirContextImpl` class (Task 3.6)
+ * will satisfy this interface.
+ */
+declare interface DefinitionProvider {
+    /**
+     * Load a StructureDefinition by canonical URL.
+     *
+     * Must throw {@link ResourceNotFoundError} if the URL cannot be resolved.
+     */
+    loadStructureDefinition(url: string): Promise<StructureDefinition>;
+}
+
+/**
+ * Tracks a differential element during snapshot generation.
+ *
+ * Implements the HAPI marker pattern where each differential element
+ * is tagged with `userData(GENERATED_IN_SNAPSHOT)` after being consumed
+ * by the merge algorithm. At the end of generation, any tracker with
+ * `consumed === false` indicates an unmatched differential element.
+ *
+ * @internal Used by {@link ElementMerger} and {@link SnapshotGenerator}.
+ */
+export declare interface DiffElementTracker {
+    /** The original differential ElementDefinition. */
+    readonly element: ElementDefinition;
+    /**
+     * Whether this element has been consumed (matched and merged)
+     * during snapshot generation.
+     *
+     * Set to `true` by the merge algorithm when the element is
+     * successfully applied to the snapshot. Checked post-generation
+     * to detect unmatched differential elements.
+     */
+    consumed: boolean;
+}
+
+/**
+ * Detect whether diff matches constitute type slicing.
+ *
+ * Corresponds to HAPI's `diffsConstrainTypes()`. Type slicing is detected when:
+ * - Multiple diff matches exist
+ * - All diff matches constrain different types, OR
+ * - The base is a choice type `[x]` and diffs use concrete type paths
+ *
+ * @param diffMatches - The differential element trackers that matched a base path.
+ * @param basePath - The base element path.
+ * @param baseTypes - The base element's type list (optional).
+ * @returns `true` if the diffs represent type slicing.
+ */
+export declare function diffsConstrainTypes(diffMatches: readonly DiffElementTracker[], basePath: string, baseTypes: readonly ElementDefinitionType[] | undefined): boolean;
+
+/**
+ * How an element value is interpreted when discrimination is evaluated.
+ * @see https://hl7.org/fhir/R4/valueset-discriminator-type.html
+ */
+export declare type DiscriminatorType = 'value' | 'exists' | 'pattern' | 'type' | 'profile';
+
+/**
+ * A resource that includes narrative, extensions, and contained resources.
+ * Most FHIR resources inherit from DomainResource.
+ * @see https://hl7.org/fhir/R4/domainresource.html
+ */
+export declare interface DomainResource extends Resource {
+    /** Text summary of the resource, for human interpretation (0..1) */
+    text?: Narrative;
+    /** Contained, inline Resources (0..*) */
+    contained?: Resource[];
+    /** Additional content defined by implementations (0..*) */
+    extension?: Extension[];
+    /** Extensions that cannot be ignored (0..*) */
+    modifierExtension?: Extension[];
+}
+
+/**
+ * Base definition for all elements in a resource.
+ * Every element in FHIR inherits from Element.
+ * @see https://hl7.org/fhir/R4/element.html
+ */
+export declare interface Element {
+    /** Unique id for inter-element referencing (0..1) */
+    id?: FhirString;
+    /** Additional content defined by implementations (0..*) */
+    extension?: Extension[];
+}
+
+/**
+ * Captures constraints on each element within a resource, data type,
+ * or extension.
+ *
+ * ElementDefinition is the most complex data type in FHIR. Each instance
+ * describes a single element path (e.g., `Patient.name`, `Patient.name.given`)
+ * and carries all constraint information: cardinality, types, bindings,
+ * invariants, slicing, flags, and documentation.
+ *
+ * ElementDefinition appears in:
+ * - `StructureDefinition.snapshot.element` (complete, flattened)
+ * - `StructureDefinition.differential.element` (delta only)
+ *
+ * This interface extends BackboneElement (has `id`, `extension`,
+ * `modifierExtension`).
+ *
+ * @see https://hl7.org/fhir/R4/elementdefinition.html
+ */
+export declare interface ElementDefinition extends BackboneElement {
+    /**
+     * Path of the element in the hierarchy of elements (1..1)
+     *
+     * The path is dot-separated, e.g., `Patient.name.given`.
+     * The first element in a snapshot always has a path equal to the
+     * resource/type name (e.g., `Patient`).
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.path
+     */
+    path: FhirString;
+    /**
+     * How this element is represented in instances (0..*)
+     *
+     * Controls serialization format (mainly relevant for XML).
+     * @see https://hl7.org/fhir/R4/valueset-property-representation.html
+     */
+    representation?: PropertyRepresentation[];
+    /**
+     * Name for this particular element (in a set of slices) (0..1)
+     *
+     * Unique within the context of the containing element. Used to
+     * identify slices in a slicing definition.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.sliceName
+     */
+    sliceName?: FhirString;
+    /**
+     * If this slice definition constrains an inherited slice definition
+     * (or not) (0..1)
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.sliceIsConstraining
+     */
+    sliceIsConstraining?: FhirBoolean;
+    /**
+     * Name for element to display with or prompt for element (0..1)
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.label
+     */
+    label?: FhirString;
+    /**
+     * Corresponding codes in terminologies (0..*)
+     *
+     * Codes that define the meaning of this element, e.g., LOINC or
+     * SNOMED CT codes. Used for mapping and search.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.code
+     */
+    code?: Coding[];
+    /**
+     * This element is sliced — slices follow (0..1)
+     *
+     * Defines how this element can be divided into a set of slices.
+     * Only appears on the "slicing root" element; individual slices
+     * are identified by `sliceName`.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.slicing
+     */
+    slicing?: ElementDefinitionSlicing;
+    /**
+     * Concise definition for space-constrained presentations (0..1)
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.short
+     */
+    short?: FhirString;
+    /**
+     * Full formal definition of the element (0..1)
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.definition
+     */
+    definition?: FhirMarkdown;
+    /**
+     * Comments about the use of this element (0..1)
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.comment
+     */
+    comment?: FhirMarkdown;
+    /**
+     * Why this resource has been created (0..1)
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.requirements
+     */
+    requirements?: FhirMarkdown;
+    /**
+     * Other names (0..*)
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.alias
+     */
+    alias?: FhirString[];
+    /**
+     * Minimum cardinality (0..1)
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.min
+     */
+    min?: FhirUnsignedInt;
+    /**
+     * Maximum cardinality (number or "*") (0..1)
+     *
+     * A string value: either a non-negative integer or `"*"` for unbounded.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.max
+     */
+    max?: FhirString;
+    /**
+     * Base definition information for tools (0..1)
+     *
+     * Records the cardinality and path from the base StructureDefinition,
+     * so tools can show what has changed in a derived profile without
+     * needing to trace the full inheritance chain.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.base
+     */
+    base?: ElementDefinitionBase;
+    /**
+     * Reference to definition of content for the element (0..1)
+     *
+     * A URI that points to another element within the same
+     * StructureDefinition, in the form `#<elementId>`. Indicates that
+     * this element has the same meaning and constraints as the
+     * referenced element.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.contentReference
+     */
+    contentReference?: FhirUri;
+    /**
+     * Data type and profile for this element (0..*)
+     *
+     * Defines the allowed types for this element. Multiple entries
+     * indicate a choice type (e.g., value[x] can be valueString,
+     * valueInteger, etc.).
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.type
+     */
+    type?: ElementDefinitionType[];
+    /**
+     * Specified value if missing from instance (0..1)
+     *
+     * Choice type [x] — the actual JSON property will be
+     * `defaultValueString`, `defaultValueBoolean`, etc.
+     * Can be any FHIR data type.
+     *
+     * Stage-1: represented as `unknown`; fhir-parser will handle
+     * concrete dispatch in Phase 2.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.defaultValue_x_
+     */
+    defaultValue?: unknown;
+    /**
+     * Implicit meaning when this element is missing (0..1)
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.meaningWhenMissing
+     */
+    meaningWhenMissing?: FhirMarkdown;
+    /**
+     * What the order of the elements means (0..1)
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.orderMeaning
+     */
+    orderMeaning?: FhirString;
+    /**
+     * Value must be exactly this (0..1)
+     *
+     * Choice type [x] — `fixedString`, `fixedCoding`, etc.
+     * If present, the element value in instances MUST match exactly.
+     *
+     * Stage-1: represented as `unknown`; fhir-parser will handle
+     * concrete dispatch in Phase 2.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.fixed_x_
+     */
+    fixed?: unknown;
+    /**
+     * Value must have at least these property values (0..1)
+     *
+     * Choice type [x] — `patternCodeableConcept`, `patternString`, etc.
+     * More lenient than `fixed`: the instance value must contain at least
+     * the properties and values specified by the pattern.
+     *
+     * Stage-1: represented as `unknown`; fhir-parser will handle
+     * concrete dispatch in Phase 2.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.pattern_x_
+     */
+    pattern?: unknown;
+    /**
+     * Example value (as defined for type) (0..*)
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.example
+     */
+    example?: ElementDefinitionExample[];
+    /**
+     * Minimum allowed value (for some types) (0..1)
+     *
+     * Choice type [x] — `minValueDate`, `minValueInteger`, etc.
+     * Only applicable to: date, dateTime, instant, time, decimal,
+     * integer, positiveInt, unsignedInt, Quantity.
+     *
+     * Stage-1: represented as `unknown`; fhir-parser will handle
+     * concrete dispatch in Phase 2.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.minValue_x_
+     */
+    minValue?: unknown;
+    /**
+     * Maximum allowed value (for some types) (0..1)
+     *
+     * Choice type [x] — `maxValueDate`, `maxValueInteger`, etc.
+     * Same type restrictions as `minValue`.
+     *
+     * Stage-1: represented as `unknown`; fhir-parser will handle
+     * concrete dispatch in Phase 2.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.maxValue_x_
+     */
+    maxValue?: unknown;
+    /**
+     * Max length for strings (0..1)
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.maxLength
+     */
+    maxLength?: FhirInteger;
+    /**
+     * Reference to invariant about presence (0..*)
+     *
+     * A list of constraint keys (`ElementDefinitionConstraint.key`) that
+     * are conditions on this element. When a constraint evaluates to false,
+     * the element is not valid.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.condition
+     */
+    condition?: FhirId[];
+    /**
+     * Condition that must evaluate to true (0..*)
+     *
+     * Formal constraints (invariants) that must be met for the element
+     * to be valid. Expressed as FHIRPath expressions.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.constraint
+     */
+    constraint?: ElementDefinitionConstraint[];
+    /**
+     * If the element must be supported (0..1)
+     *
+     * When `true`, implementations claiming conformance to this profile
+     * MUST "meaningfully support" this element. The exact meaning of
+     * mustSupport is defined per implementation guide.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.mustSupport
+     */
+    mustSupport?: FhirBoolean;
+    /**
+     * If this modifies the meaning of other elements (0..1)
+     *
+     * Modifier elements can change the interpretation of the containing
+     * resource or element. Implementations MUST understand modifier elements.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.isModifier
+     */
+    isModifier?: FhirBoolean;
+    /**
+     * Reason that this element is marked as a modifier (0..1)
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.isModifierReason
+     */
+    isModifierReason?: FhirString;
+    /**
+     * Include when _summary = true? (0..1)
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.isSummary
+     */
+    isSummary?: FhirBoolean;
+    /**
+     * ValueSet details if this is coded (0..1)
+     *
+     * Binds this element to a specific value set. The `strength`
+     * determines how strictly the binding applies.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.binding
+     */
+    binding?: ElementDefinitionBinding;
+    /**
+     * Map element to another set of definitions (0..*)
+     *
+     * Identifies a concept from an external specification (e.g., v2,
+     * CDA, or a custom mapping) that corresponds to this element.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.mapping
+     */
+    mapping?: ElementDefinitionMapping[];
+}
+
+/**
+ * Information about the base definition of the element, provided to
+ * make it unnecessary for tools to trace the deviation of the element
+ * through the derived and related profiles.
+ * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.base
+ */
+export declare interface ElementDefinitionBase extends Element {
+    /** Path that identifies the base element (1..1) */
+    path: FhirString;
+    /** Min cardinality of the base element (1..1) */
+    min: FhirUnsignedInt;
+    /**
+     * Max cardinality of the base element (1..1)
+     *
+     * A string value, either a number or "*" for unbounded.
+     */
+    max: FhirString;
+}
+
+/**
+ * Binds an element to a specific value set, indicating the degree of
+ * conformance expectation.
+ * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.binding
+ */
+export declare interface ElementDefinitionBinding extends Element {
+    /**
+     * required | extensible | preferred | example (1..1)
+     *
+     * Indicates the degree of conformance expectations associated with
+     * this binding. Only `required` means mandatory in FHIR.
+     * @see https://hl7.org/fhir/R4/valueset-binding-strength.html
+     */
+    strength: BindingStrength;
+    /** Human explanation of the value set (0..1) */
+    description?: FhirString;
+    /**
+     * Source of value set (0..1)
+     *
+     * Canonical URL reference to the value set bound to this element.
+     */
+    valueSet?: FhirCanonical;
+}
+
+/**
+ * Formal constraints (invariants) on the element that must be satisfied
+ * for the element to be valid.
+ * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.constraint
+ */
+export declare interface ElementDefinitionConstraint extends Element {
+    /**
+     * Target of 'condition' reference (1..1)
+     *
+     * Unique identifier for the constraint, used by `condition` fields
+     * to reference which constraints apply.
+     */
+    key: FhirId;
+    /** Why this constraint is necessary or appropriate (0..1) */
+    requirements?: FhirString;
+    /**
+     * error | warning (1..1)
+     * @see https://hl7.org/fhir/R4/valueset-constraint-severity.html
+     */
+    severity: ConstraintSeverity;
+    /** Human description of constraint (1..1) */
+    human: FhirString;
+    /**
+     * FHIRPath expression of constraint (0..1)
+     *
+     * A FHIRPath expression that must evaluate to `true` when
+     * tested against the element and its children.
+     */
+    expression?: FhirString;
+    /**
+     * XPath expression of constraint (0..1)
+     *
+     * Deprecated in favor of `expression` (FHIRPath), but retained
+     * for backward compatibility with older profiles.
+     */
+    xpath?: FhirString;
+    /**
+     * Reference to original source of constraint (0..1)
+     *
+     * Canonical URL of the StructureDefinition where this constraint
+     * was originally defined.
+     */
+    source?: FhirCanonical;
+}
+
+/**
+ * A sample value for the element, providing an example for implementers.
+ * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.example
+ */
+export declare interface ElementDefinitionExample extends Element {
+    /** Describes the purpose of this example (1..1) */
+    label: FhirString;
+    /**
+     * Value of Example (1..1)
+     *
+     * Choice type [x] — the actual property name in JSON will be
+     * `valueString`, `valueBoolean`, `valueCoding`, etc.
+     * Can be any FHIR data type.
+     *
+     * Stage-1: represented as `unknown`; fhir-parser will handle
+     * concrete dispatch in Phase 2.
+     */
+    value: unknown;
+}
+
+/**
+ * Identifies a concept from an external specification that roughly
+ * corresponds to this element.
+ * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.mapping
+ */
+export declare interface ElementDefinitionMapping extends Element {
+    /**
+     * Reference to mapping declaration (1..1)
+     *
+     * An internal reference to the StructureDefinition.mapping.identity
+     * that this element mapping refers to.
+     */
+    identity: FhirId;
+    /** Computable language of mapping (0..1) */
+    language?: FhirCode;
+    /** Details of the mapping (1..1) */
+    map: FhirString;
+    /** Comments about the mapping (0..1) */
+    comment?: FhirString;
+}
+
+/**
+ * How an element is sliced — defines the discriminator(s) and rules
+ * for matching slices in an instance.
+ * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.slicing
+ */
+export declare interface ElementDefinitionSlicing extends Element {
+    /**
+     * Element values that are used to distinguish the slices (0..*)
+     *
+     * Each discriminator specifies a path and a type that together
+     * identify which slice a given element instance belongs to.
+     */
+    discriminator?: SlicingDiscriminator[];
+    /** Text description of how slicing works (or in profile determine how slicing is used) (0..1) */
+    description?: FhirString;
+    /** If elements must be in same order as slices (0..1) */
+    ordered?: FhirBoolean;
+    /**
+     * closed | open | openAtEnd (1..1)
+     *
+     * - `closed`: no additional content allowed beyond the defined slices
+     * - `open`: additional content allowed anywhere
+     * - `openAtEnd`: additional content allowed, but only at the end
+     * @see https://hl7.org/fhir/R4/valueset-resource-slicing-rules.html
+     */
+    rules: SlicingRules;
+}
+
+/**
+ * The data type or resource that is a permitted type for the element.
+ * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.type
+ */
+export declare interface ElementDefinitionType extends Element {
+    /**
+     * Data type or Resource (name) (1..1)
+     *
+     * The URI of the data type or resource, e.g., `http://hl7.org/fhirpath/System.String`
+     * for primitives or a simple name like `string`, `Patient`, `Reference`.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.type.code
+     */
+    code: FhirUri;
+    /**
+     * Profiles (StructureDefinition or IG) — one of which this type must
+     * conform to (0..*)
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.type.profile
+     */
+    profile?: FhirCanonical[];
+    /**
+     * Profile (StructureDefinition or IG) on the Reference target —
+     * one of which the reference must conform to (0..*)
+     *
+     * Only meaningful when `code` is `Reference` or `canonical`.
+     * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.type.targetProfile
+     */
+    targetProfile?: FhirCanonical[];
+    /**
+     * contained | referenced | bundled (0..*)
+     *
+     * How resource references are aggregated. Only meaningful when
+     * `code` is `Reference`.
+     * @see https://hl7.org/fhir/R4/valueset-resource-aggregation-mode.html
+     */
+    aggregation?: AggregationMode[];
+    /**
+     * either | independent | specific (0..1)
+     *
+     * Whether references need to be version-specific.
+     * @see https://hl7.org/fhir/R4/valueset-reference-version-rules.html
+     */
+    versioning?: ReferenceVersionRules;
+}
+
+/**
+ * Ensure all elements have an `id` property.
+ *
+ * If an element lacks an `id`, generates one from its path and sliceName.
+ * This follows the FHIR convention:
+ * - Unsliced: `id = path` (e.g., `"Patient.name"`)
+ * - Sliced: `id = path:sliceName` (e.g., `"Patient.identifier:MRN"`)
+ *
+ * Corresponds to HAPI's `setIds()`.
+ *
+ * @param elements - The elements to process (mutated in place).
+ * @param resourceType - The resource type name (used for the root element).
+ */
+export declare function ensureElementIds(elements: ElementDefinition[], resourceType?: string): void;
+
+/**
+ * Evaluate a FHIRPath expression against a resource or other object.
+ * Accepts raw values (auto-wrapped in TypedValue) or pre-wrapped TypedValue arrays.
+ *
+ * @param expression - The FHIRPath expression string or pre-parsed AST.
+ * @param input - The resource or object to evaluate against.
+ * @returns Array of result values (unwrapped from TypedValue).
+ */
+export declare function evalFhirPath(expression: string | FhirPathAtom, input: unknown): unknown[];
+
+/**
+ * Evaluate a FHIRPath expression and return a boolean result.
+ *
+ * Useful for invariant validation where the expression must evaluate to `true`.
+ * Uses FHIRPath boolean semantics: empty → false, single truthy → true.
+ *
+ * @param expression - FHIRPath expression string or pre-parsed AST.
+ * @param input - The resource or typed values to evaluate against.
+ * @param variables - Optional variable bindings.
+ * @returns Boolean result of the expression.
+ */
+export declare function evalFhirPathBoolean(expression: string | FhirPathAtom, input: unknown, variables?: Record<string, TypedValue>): boolean;
+
+/**
+ * Evaluate a FHIRPath expression and return the first result as a string.
+ *
+ * Useful for extracting display values, identifiers, etc.
+ *
+ * @param expression - FHIRPath expression string or pre-parsed AST.
+ * @param input - The resource or typed values to evaluate against.
+ * @param variables - Optional variable bindings.
+ * @returns The first result value as a string, or `undefined` if empty.
+ */
+export declare function evalFhirPathString(expression: string | FhirPathAtom, input: unknown, variables?: Record<string, TypedValue>): string | undefined;
+
+/**
+ * Evaluate a FHIRPath expression against typed input values.
+ *
+ * @param expression - The FHIRPath expression string or pre-parsed AST.
+ * @param input - Array of TypedValue inputs.
+ * @param variables - Optional variable bindings.
+ * @returns Array of TypedValue results.
+ */
+export declare function evalFhirPathTyped(expression: string | FhirPathAtom, input: TypedValue[], variables?: Record<string, TypedValue>): TypedValue[];
+
+/**
+ * An Extension: additional information that is not part of the basic
+ * definition of the resource.
+ * @see https://hl7.org/fhir/R4/extensibility.html#Extension
+ */
+export declare interface Extension extends Element {
+    /** Identifies the meaning of the extension (1..1) */
+    url: FhirUri;
+    /**
+     * Value of extension (0..1).
+     *
+     * Choice type [x] — the actual property name in JSON will be
+     * `valueString`, `valueCode`, `valueBoolean`, `valueCoding`, etc.
+     * Allows **all** FHIR data types (~50+ types).
+     *
+     * Stage-1: represented as `unknown`; fhir-parser will handle
+     * concrete dispatch in Phase 2.
+     * @see https://hl7.org/fhir/R4/extensibility-definitions.html#Extension.value_x_
+     */
+    value?: unknown;
+}
+
+/**
+ * The context type for an extension definition.
+ * @see https://hl7.org/fhir/R4/valueset-extension-context-type.html
+ */
+export declare type ExtensionContextType = 'fhirpath' | 'element' | 'extension';
+
+/**
+ * Extract the type name from a concrete choice path given the choice base.
+ *
+ * @example
+ * extractChoiceTypeName('Observation.value[x]', 'Observation.valueString')    // 'String'
+ * extractChoiceTypeName('Observation.value[x]', 'Observation.valueQuantity')  // 'Quantity'
+ * extractChoiceTypeName('Observation.value[x]', 'Observation.code')           // undefined
+ */
+export declare function extractChoiceTypeName(choicePath: string, concretePath: string): string | undefined;
+
+/**
+ * Extract inner types from a CanonicalProfile.
+ *
+ * Scans the profile's elements for BackboneElement/Element types and creates
+ * independent `CanonicalProfile` instances for each, containing only their
+ * direct child elements.
+ *
+ * The returned Map is keyed by the generated type name (e.g., `'PatientContact'`).
+ * Each inner type has its `parentType` set to the profile's type name.
+ *
+ * **Note:** This function also handles nested BackboneElements. For example,
+ * if `Bundle.entry` is a BackboneElement containing `Bundle.entry.request`
+ * (also a BackboneElement), both `BundleEntry` and `BundleEntryRequest` will
+ * be extracted. `BundleEntryRequest` will have `parentType: 'BundleEntry'`.
+ *
+ * @param profile - The CanonicalProfile to extract inner types from
+ * @returns Map of inner type name → CanonicalProfile
+ *
+ * @example
+ * ```typescript
+ * const innerTypes = extractInnerTypes(patientProfile);
+ * // innerTypes.get('PatientContact')  → CanonicalProfile for Patient.contact
+ * // innerTypes.get('PatientCommunication')  → CanonicalProfile for Patient.communication
+ * // innerTypes.get('PatientLink')  → CanonicalProfile for Patient.link
+ * ```
+ */
+export declare function extractInnerTypes(profile: CanonicalProfile): Map<string, CanonicalProfile>;
+
+/**
+ * Extract the first slice name from an element id.
+ *
+ * @example
+ * extractSliceName('Patient.identifier:MRN')         // 'MRN'
+ * extractSliceName('Patient.identifier:MRN.system')   // 'MRN'
+ * extractSliceName('Patient.identifier')              // undefined
+ */
+export declare function extractSliceName(elementId: string): string | undefined;
+
+/**
+ * fhir-validator — Path Extractor
+ *
+ * Extracts values from FHIR resource instances using element paths.
+ * Handles nested objects, arrays, and choice type (`[x]`) paths.
+ *
+ * This is the core utility that bridges CanonicalProfile element paths
+ * (e.g., `Patient.name.family`) to actual values in a resource JSON object.
+ *
+ * @module fhir-validator
+ */
+/**
+ * Extract values from a resource instance using an element path.
+ *
+ * Navigates the resource object following the dot-separated path segments.
+ * Arrays are automatically expanded — if an intermediate node is an array,
+ * extraction continues into each element.
+ *
+ * @param resource - The resource object to extract from.
+ * @param path - Element path (e.g., `'Patient.name.family'`).
+ * @returns Array of extracted values (empty if path not found).
+ *
+ * @example
+ * ```typescript
+ * const patient = {
+ *   resourceType: 'Patient',
+ *   name: [
+ *     { family: 'Smith', given: ['John', 'James'] },
+ *     { family: 'Doe' },
+ *   ],
+ * };
+ *
+ * extractValues(patient, 'Patient.name')
+ * // → [{ family: 'Smith', given: ['John', 'James'] }, { family: 'Doe' }]
+ *
+ * extractValues(patient, 'Patient.name.family')
+ * // → ['Smith', 'Doe']
+ *
+ * extractValues(patient, 'Patient.name.given')
+ * // → ['John', 'James']
+ * ```
+ */
+export declare function extractValues(resource: Record<string, unknown>, path: string): unknown[];
+
+/**
+ * FHIR base64Binary: base64 encoded content (RFC 4648).
+ * Regex: `(\s*([0-9a-zA-Z\+\/\=]){4}\s*)+`
+ * @see https://hl7.org/fhir/R4/datatypes.html#base64Binary
+ */
+export declare type FhirBase64Binary = Branded<string, 'FhirBase64Binary'>;
+
+/**
+ * FHIR boolean: true | false
+ * @see https://hl7.org/fhir/R4/datatypes.html#boolean
+ */
+export declare type FhirBoolean = Branded<boolean, 'FhirBoolean'>;
+
+/**
+ * FHIR canonical: a URI that refers to a resource by its canonical URL,
+ * optionally with a version suffix `|version`.
+ * @see https://hl7.org/fhir/R4/datatypes.html#canonical
+ */
+export declare type FhirCanonical = Branded<string, 'FhirCanonical'>;
+
+/**
+ * FHIR code: a string that is constrained to the set of allowed values
+ * from a controlled vocabulary (value set).
+ * Regex: `[^\s]+(\s[^\s]+)*`
+ * @see https://hl7.org/fhir/R4/datatypes.html#code
+ */
+export declare type FhirCode = Branded<string, 'FhirCode'>;
+
+/**
+ * Central registry and lifecycle manager for FHIR StructureDefinitions.
+ *
+ * `FhirContext` is the primary entry point for accessing FHIR definitions
+ * at runtime. It manages loading, caching, and resolution of
+ * StructureDefinitions from one or more sources.
+ *
+ * Conceptual mapping:
+ * - HAPI `FhirContext` → registry + lifecycle
+ * - HAPI `IValidationSupport` → loader delegation
+ *
+ * Phase 4 (`fhir-profile`) will use this interface to load base definitions
+ * during snapshot generation.
+ *
+ * @example
+ * ```typescript
+ * const context = new FhirContextImpl({ loaders: [memoryLoader, fileLoader] });
+ * await context.preloadCoreDefinitions();
+ *
+ * const patient = await context.loadStructureDefinition(
+ *   'http://hl7.org/fhir/StructureDefinition/Patient'
+ * );
+ * const chain = await context.resolveInheritanceChain(patient.url!);
+ * // → ['http://hl7.org/fhir/StructureDefinition/Patient',
+ * //    'http://hl7.org/fhir/StructureDefinition/DomainResource',
+ * //    'http://hl7.org/fhir/StructureDefinition/Resource']
+ * ```
+ */
+export declare interface FhirContext {
+    /**
+     * Load a StructureDefinition by canonical URL.
+     *
+     * Resolution order:
+     * 1. Check internal registry (cache hit)
+     * 2. Delegate to configured loaders (cache miss)
+     * 3. Parse, validate, and register the result
+     *
+     * Supports versioned URLs in `url|version` format
+     * (e.g., `"http://example.org/Profile|1.0.0"`).
+     *
+     * @param url - Canonical URL, optionally with `|version` suffix
+     * @returns Resolved StructureDefinition
+     * @throws {@link ResourceNotFoundError} if no loader can resolve the URL
+         * @throws {@link LoaderError} if a loader fails during loading
+             * @throws {@link InvalidStructureDefinitionError} if the loaded resource is malformed
+                 */
+             loadStructureDefinition(url: string): Promise<StructureDefinition>;
+             /**
+              * Synchronously retrieve a StructureDefinition from the registry.
+              *
+              * Does **not** trigger any loader — only checks the in-memory registry.
+              * Use {@link loadStructureDefinition} if you need on-demand loading.
+              *
+              * @param url - Canonical URL (with optional `|version`)
+              * @returns The cached StructureDefinition, or `undefined` if not loaded
+              */
+             getStructureDefinition(url: string): StructureDefinition | undefined;
+             /**
+              * Check whether a StructureDefinition is present in the registry.
+              *
+              * @param url - Canonical URL (with optional `|version`)
+              */
+             hasStructureDefinition(url: string): boolean;
+             /**
+              * Resolve the full inheritance chain for a profile.
+              *
+              * Walks the `baseDefinition` links from the given URL up to the root
+              * resource type (e.g., `Resource`). Each base is loaded on demand if
+              * not already in the registry.
+              *
+              * @param url - Canonical URL of the starting profile
+              * @returns Array of canonical URLs from child to root
+              *          (e.g., `[ChinesePatient, Patient, DomainResource, Resource]`)
+              * @throws {@link CircularDependencyError} if a cycle is detected
+                  * @throws {@link ResourceNotFoundError} if a base definition cannot be found
+                      */
+                  resolveInheritanceChain(url: string): Promise<string[]>;
+                  /**
+                   * Register a StructureDefinition in the registry.
+                   *
+                   * This is used for:
+                   * - Manually adding definitions (e.g., custom profiles)
+                   * - Phase 4: caching generated snapshots back into the context
+                   *
+                   * If a definition with the same URL (and version) already exists,
+                   * it will be replaced and any cached inheritance chains invalidated.
+                   *
+                   * @param sd - The StructureDefinition to register
+                   * @throws {@link InvalidStructureDefinitionError} if `sd.url` is missing
+                       */
+                   registerStructureDefinition(sd: StructureDefinition): void;
+                   /**
+                    * Preload FHIR R4 core StructureDefinitions.
+                    *
+                    * Loads base resource types (Resource, DomainResource, Patient,
+                    * Observation, etc.) into the registry so they are available
+                    * synchronously via {@link getStructureDefinition}.
+                    *
+                    * Should be called once during application initialization.
+                    */
+                   preloadCoreDefinitions(): Promise<void>;
+                   /**
+                    * Return runtime statistics for monitoring and diagnostics.
+                    */
+                   getStatistics(): ContextStatistics;
+                   /**
+                    * Register a CanonicalProfile and its extracted InnerTypes.
+                    *
+                    * This is the primary method for making InnerTypes available for
+                    * downstream consumption (UI forms, recursive validation, etc.).
+                    * Typically called after snapshot generation + `extractInnerTypes()`.
+                    *
+                    * @param profile - The CanonicalProfile (with innerTypes populated)
+                    */
+                   registerCanonicalProfile(profile: CanonicalProfile): void;
+                   /**
+                    * Retrieve an InnerType schema by its generated type name.
+                    *
+                    * @param typeName - Generated type name (e.g., `'PatientContact'`)
+                    * @returns The InnerType CanonicalProfile, or `undefined` if not registered
+                    */
+                   getInnerType(typeName: string): CanonicalProfile | undefined;
+                   /**
+                    * Check whether an InnerType is registered.
+                    *
+                    * @param typeName - Generated type name (e.g., `'PatientContact'`)
+                    */
+                   hasInnerType(typeName: string): boolean;
+                   /**
+                    * Release all cached data and reset internal state.
+                    *
+                    * After calling `dispose()`, the context must be re-initialized
+                    * (e.g., by calling {@link preloadCoreDefinitions} again).
+                    */
+                   dispose(): void;
+                  }
+
+                  /**
+                   * Concrete implementation of {@link FhirContext}.
+                   *
+                   * @example
+                   * ```typescript
+                   * const ctx = new FhirContextImpl({
+                   *   loaders: [memoryLoader, fileLoader],
+                   * });
+                   * await ctx.preloadCoreDefinitions();
+                   *
+                   * const patient = await ctx.loadStructureDefinition(
+                   *   'http://hl7.org/fhir/StructureDefinition/Patient'
+                   * );
+                   * ```
+                   */
+                  export declare class FhirContextImpl implements FhirContext {
+                      private readonly _registry;
+                      private readonly _resolver;
+                      private readonly _loader;
+                      private readonly _options;
+                      private readonly _stats;
+                      private readonly _innerTypes;
+                      private readonly _canonicalProfiles;
+                      private _disposed;
+                      constructor(options: FhirContextOptions);
+                      loadStructureDefinition(url: string): Promise<StructureDefinition>;
+                      getStructureDefinition(url: string): StructureDefinition | undefined;
+                      hasStructureDefinition(url: string): boolean;
+                      resolveInheritanceChain(url: string): Promise<string[]>;
+                      registerStructureDefinition(sd: StructureDefinition): void;
+                      preloadCoreDefinitions(): Promise<void>;
+                      getStatistics(): ContextStatistics;
+                      registerCanonicalProfile(profile: CanonicalProfile): void;
+                      getInnerType(typeName: string): CanonicalProfile | undefined;
+                      hasInnerType(typeName: string): boolean;
+                      dispose(): void;
+                      /**
+                       * Validate that a StructureDefinition has the minimum required fields.
+                       */
+                      private _validateStructureDefinition;
+                      /**
+                       * Guard against use after dispose.
+                       */
+                      private _ensureNotDisposed;
+                      /**
+                       * Direct access to the internal registry (for diagnostics).
+                       */
+                      get registry(): StructureDefinitionRegistry;
+                      /**
+                       * Direct access to the internal resolver (for diagnostics).
+                       */
+                      get resolver(): InheritanceChainResolver;
+                  }
+
+                  /**
+                   * Configuration options for creating a {@link FhirContext}.
+                   */
+                  export declare interface FhirContextOptions {
+                      /**
+                       * One or more loaders to use for resolving StructureDefinitions.
+                       *
+                       * When multiple loaders are provided, they are tried in order
+                       * (first match wins — chain of responsibility pattern).
+                       */
+                      loaders: StructureDefinitionLoader[];
+                      /**
+                       * Whether to automatically call {@link FhirContext.preloadCoreDefinitions}
+                       * during initialization.
+                       *
+                       * @defaultValue `true`
+                       */
+                      preloadCore?: boolean;
+                      /**
+                       * Path to the FHIR R4 specification directory.
+                       *
+                       * Used by the core definition preloader to locate `profiles-resources.json`
+                       * and `profiles-types.json`.
+                       *
+                       * @defaultValue `undefined` (uses bundled definitions)
+                       */
+                      specDirectory?: string;
+                  }
+
+                  /**
+                   * FHIR date: a date or partial date (year, year-month, or year-month-day).
+                   * No timezone. No time.
+                   * Format: `YYYY(-MM(-DD)?)?`
+                   * Regex: `([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-9]000)(-(0[1-9]|1[0-2])(-(0[1-9]|[1-2][0-9]|3[0-1]))?)?`
+                   * @see https://hl7.org/fhir/R4/datatypes.html#date
+                   */
+                  export declare type FhirDate = Branded<string, 'FhirDate'>;
+
+                  /**
+                   * FHIR dateTime: a date, date-time, or partial date with optional time and timezone.
+                   * Format: `YYYY(-MM(-DD(Thh:mm:ss(.sss)?(Z|(+|-)hh:mm))?)?)?`
+                   * @see https://hl7.org/fhir/R4/datatypes.html#dateTime
+                   */
+                  export declare type FhirDateTime = Branded<string, 'FhirDateTime'>;
+
+                  /**
+                   * FHIR decimal: rational numbers with implicit precision.
+                   * Regex: `-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?`
+                   * Note: precision of the decimal value has significance
+                   * (e.g., 0.010 is regarded as different to 0.01).
+                   * @see https://hl7.org/fhir/R4/datatypes.html#decimal
+                   */
+                  export declare type FhirDecimal = Branded<number, 'FhirDecimal'>;
+
+                  /**
+                   * FHIR id: any combination of upper- or lower-case ASCII letters,
+                   * numerals, '-', and '.', with a length limit of 64 characters.
+                   * Regex: `[A-Za-z0-9\-\.]{1,64}`
+                   * @see https://hl7.org/fhir/R4/datatypes.html#id
+                   */
+                  export declare type FhirId = Branded<string, 'FhirId'>;
+
+                  /**
+                   * FHIR instant: an instant in time with at least second precision
+                   * and always includes a timezone.
+                   * Format: `YYYY-MM-DDThh:mm:ss.sss+zz:zz`
+                   * Regex: `([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-9]000)-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])T([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))`
+                   * @see https://hl7.org/fhir/R4/datatypes.html#instant
+                   */
+                  export declare type FhirInstant = Branded<string, 'FhirInstant'>;
+
+                  /**
+                   * FHIR integer: whole numbers in the range -2,147,483,648..2,147,483,647
+                   * Regex: `[0]|[-+]?[1-9][0-9]*`
+                   * @see https://hl7.org/fhir/R4/datatypes.html#integer
+                   */
+                  export declare type FhirInteger = Branded<number, 'FhirInteger'>;
+
+                  /**
+                   * FHIR markdown: a FHIR string that may contain markdown syntax.
+                   * Systems are not required to have markdown support.
+                   * @see https://hl7.org/fhir/R4/datatypes.html#markdown
+                   */
+                  export declare type FhirMarkdown = Branded<string, 'FhirMarkdown'>;
+
+                  /**
+                   * FHIR oid: an OID represented as a URI (RFC 3001).
+                   * Format: `urn:oid:[0-2](\.(0|[1-9][0-9]*))+`
+                   * @see https://hl7.org/fhir/R4/datatypes.html#oid
+                   */
+                  export declare type FhirOid = Branded<string, 'FhirOid'>;
+
+                  /**
+                   * Root wrapper atom for a parsed FHIRPath expression.
+                   * Iterates over each input element, setting `$this` for each evaluation.
+                   */
+                  declare class FhirPathAtom implements Atom {
+                      readonly original: string;
+                      readonly child: Atom;
+                      constructor(original: string, child: Atom);
+                      eval(context: AtomContext, input: TypedValue[]): TypedValue[];
+                      toString(): string;
+                  }
+
+                  /**
+                   * FHIR positiveInt: positive integer in the range 1..2,147,483,647.
+                   * Regex: `+?[1-9][0-9]*`
+                   * @see https://hl7.org/fhir/R4/datatypes.html#positiveInt
+                   */
+                  export declare type FhirPositiveInt = Branded<number, 'FhirPositiveInt'>;
+
+                  /**
+                   * FHIR string: a sequence of Unicode characters.
+                   * Regex: `[ \r\n\t\S]+`
+                   * Note: strings SHOULD not contain Unicode character points below 32,
+                   * except for horizontal tab, carriage return, and line feed.
+                   * @see https://hl7.org/fhir/R4/datatypes.html#string
+                   */
+                  export declare type FhirString = Branded<string, 'FhirString'>;
+
+                  /**
+                   * FHIR time: a time of day with no date and no timezone.
+                   * Format: `hh:mm:ss(.sss)?`
+                   * Regex: `([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?`
+                   * @see https://hl7.org/fhir/R4/datatypes.html#time
+                   */
+                  export declare type FhirTime = Branded<string, 'FhirTime'>;
+
+                  /**
+                   * FHIR unsignedInt: non-negative integer in the range 0..2,147,483,647.
+                   * Regex: `[0]|([1-9][0-9]*)`
+                   * @see https://hl7.org/fhir/R4/datatypes.html#unsignedInt
+                   */
+                  export declare type FhirUnsignedInt = Branded<number, 'FhirUnsignedInt'>;
+
+                  /**
+                   * FHIR uri: a Uniform Resource Identifier.
+                   * Regex: `\S*`
+                   * @see https://hl7.org/fhir/R4/datatypes.html#uri
+                   */
+                  export declare type FhirUri = Branded<string, 'FhirUri'>;
+
+                  /**
+                   * FHIR url: a Uniform Resource Locator (a subset of uri).
+                   * Must start with http:, https:, ftp:, mailto:, or mllp:.
+                   * @see https://hl7.org/fhir/R4/datatypes.html#url
+                   */
+                  export declare type FhirUrl = Branded<string, 'FhirUrl'>;
+
+                  /**
+                   * FHIR uuid: a UUID expressed as a URI (RFC 4122).
+                   * Format: `urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}`
+                   * @see https://hl7.org/fhir/R4/datatypes.html#uuid
+                   */
+                  export declare type FhirUuid = Branded<string, 'FhirUuid'>;
+
+                  /**
+                   * FHIR version identifier.
+                   * @see https://hl7.org/fhir/R4/valueset-FHIR-version.html
+                   */
+                  export declare type FhirVersionCode = '0.01' | '0.05' | '0.06' | '0.11' | '0.0.80' | '0.0.81' | '0.0.82' | '0.4.0' | '0.5.0' | '1.0.0' | '1.0.1' | '1.0.2' | '1.1.0' | '1.4.0' | '1.6.0' | '1.8.0' | '3.0.0' | '3.0.1' | '3.0.2' | '3.3.0' | '3.5.0' | '4.0.0' | '4.0.1';
+
+                  /**
+                   * FHIR xhtml: limited XHTML content as defined in the Narrative datatype.
+                   * @see https://hl7.org/fhir/R4/datatypes.html#xhtml
+                   * @see https://hl7.org/fhir/R4/narrative.html
+                   */
+                  export declare type FhirXhtml = Branded<string, 'FhirXhtml'>;
+
+                  /**
+                   * A loader that resolves StructureDefinitions from local JSON files.
+                   *
+                   * @example
+                   * ```typescript
+                   * const loader = new FileSystemLoader('/path/to/definitions');
+                   * const sd = await loader.load('http://hl7.org/fhir/StructureDefinition/Patient');
+                   * // Reads /path/to/definitions/Patient.json
+                   * ```
+                   */
+                  export declare class FileSystemLoader implements StructureDefinitionLoader {
+                      private readonly _basePath;
+                      /**
+                       * @param basePath - Directory containing `{ResourceName}.json` files
+                       */
+                      constructor(basePath: string);
+                      load(url: string): Promise<StructureDefinition | null>;
+                      canLoad(url: string): boolean;
+                      getSourceType(): string;
+                      /**
+                       * The base directory this loader reads from.
+                       */
+                      get basePath(): string;
+                  }
+
+                  /**
+                   * Find the index of a path in the base snapshot.
+                   *
+                   * Handles:
+                   * - Exact path match
+                   * - Choice type match (e.g., `valueString` matches `value[x]`)
+                   * - Slice paths (strips `:sliceName` from id to match by path)
+                   *
+                   * @param baseSnapshot - The base snapshot element list.
+                   * @param path - The path to find.
+                   * @param sliceName - Optional slice name for disambiguation.
+                   * @returns The index in baseSnapshot, or -1 if not found.
+                   */
+                  export declare function findBaseIndex(baseSnapshot: readonly ElementDefinition[], path: string, sliceName?: string): number;
+
+                  /**
+                   * Resolve the absolute path to the `core-definitions/` directory.
+                   *
+                   * Works both in ESM (via `import.meta.url`) and when a custom
+                   * `specDirectory` is provided.
+                   *
+                   * @param specDirectory - Optional override directory path
+                   * @returns Absolute path to the core definitions directory
+                   */
+                  export declare function getCoreDefinitionsDir(specDirectory?: string): string;
+
+                  /**
+                   * Get all sibling slices from a base snapshot starting after the slicing root.
+                   *
+                   * Corresponds to HAPI's `getSiblings()`. Collects all elements with the
+                   * same path as the slicing root that have a `sliceName`, plus their children.
+                   *
+                   * @param elements - The base snapshot element list.
+                   * @param slicingRootIndex - Index of the slicing root element.
+                   * @returns Array of slice elements (each with sliceName) and their children.
+                   */
+                  export declare function getSliceSiblings(elements: readonly ElementDefinition[], slicingRootIndex: number): ElementDefinition[];
+
+                  /**
+                   * Handle Case B: Base is already sliced, differential modifies/extends slices.
+                   *
+                   * Steps:
+                   * 1. Copy base slicing root (merge diff slicing definition if present)
+                   * 2. Collect base slice siblings
+                   * 3. Align base slices with diff slices by sliceName
+                   * 4. Matched slices → merge constraints
+                   * 5. Unmatched base slices → copy as-is
+                   * 6. Remaining diff slices → append as new (only if open/openAtEnd)
+                   *
+                   * @param context - Shared merge state.
+                   * @param result - Mutable output array.
+                   * @param currentBase - The base slicing root element.
+                   * @param baseScope - Scope of the base element and its children.
+                   * @param diffMatches - Diff trackers that matched this base path.
+                   * @param diffTrackers - All diff trackers (for recursive calls).
+                   * @param diffStart - Start index in diffTrackers.
+                   * @param diffEnd - End index in diffTrackers.
+                   * @param contextPathSrc - Source path prefix for rewriting.
+                   * @param contextPathDst - Destination path prefix for rewriting.
+                   * @param cpath - The current (rewritten) path.
+                   */
+                  export declare function handleExistingSlicing(context: MergeContext, result: ElementDefinition[], currentBase: ElementDefinition, baseScope: TraversalScope, diffMatches: DiffElementTracker[], diffTrackers: readonly DiffElementTracker[], diffStart: number, diffEnd: number, contextPathSrc: string, contextPathDst: string, cpath: string): void;
+
+                  /**
+                   * Handle Case A: Base is unsliced, differential introduces slicing.
+                   *
+                   * Steps:
+                   * 1. Create slicing root element (from diff slicing definition or synthesized extension slicing)
+                   * 2. Add slicing root to result
+                   * 3. For each diff slice, recursively process against the same base range
+                   *
+                   * @param context - Shared merge state.
+                   * @param result - Mutable output array.
+                   * @param currentBase - The base element being sliced.
+                   * @param baseScope - Scope of the base element and its children.
+                   * @param diffMatches - Diff trackers that matched this base path.
+                   * @param diffTrackers - All diff trackers (for recursive calls).
+                   * @param diffStart - Start index in diffTrackers.
+                   * @param diffEnd - End index in diffTrackers.
+                   * @param contextPathSrc - Source path prefix for rewriting.
+                   * @param contextPathDst - Destination path prefix for rewriting.
+                   * @param cpath - The current (rewritten) path.
+                   */
+                  export declare function handleNewSlicing(context: MergeContext, result: ElementDefinition[], currentBase: ElementDefinition, baseScope: TraversalScope, diffMatches: DiffElementTracker[], diffTrackers: readonly DiffElementTracker[], diffStart: number, diffEnd: number, contextPathSrc: string, contextPathDst: string, cpath: string): void;
+
+                  /**
+                   * Check whether an issues array contains at least one error (not just warnings).
+                   *
+                   * Useful for determining whether to return success or failure after
+                   * collecting issues from sub-parsers.
+                   */
+                  export declare function hasErrors(issues: readonly ParseIssue[]): boolean;
+
+                  /**
+                   * Check whether an element id contains a slice name (`:` separator).
+                   *
+                   * In FHIR, slice names appear in element ids, not in paths.
+                   * Format: `"ResourceType.path:sliceName"` or `"ResourceType.path:sliceName.child"`
+                   *
+                   * @example
+                   * hasSliceName('Patient.identifier:MRN')            // true
+                   * hasSliceName('Patient.identifier:MRN.system')     // true
+                   * hasSliceName('Patient.identifier')                // false
+                   */
+                  export declare function hasSliceName(elementId: string): boolean;
+
+                  /**
+                   * Check whether a validation result has any error-severity issues.
+                   *
+                   * @param issues - The issues to check.
+                   * @returns `true` if any issue has severity `'error'`.
+                   */
+                  export declare function hasValidationErrors(issues: readonly ValidationIssue[]): boolean;
+
+                  /**
+                   * An identifier intended for computation (e.g., MRN, NPI).
+                   * @see https://hl7.org/fhir/R4/datatypes.html#Identifier
+                   */
+                  export declare interface Identifier extends Element {
+                      /** usual | official | temp | secondary | old (0..1) */
+                      use?: FhirCode;
+                      /** Description of identifier (0..1) */
+                      type?: CodeableConcept;
+                      /** The namespace for the identifier value (0..1) */
+                      system?: FhirUri;
+                      /** The value that is unique (0..1) */
+                      value?: FhirString;
+                      /** Time period when id is/was valid for use (0..1) */
+                      period?: Period;
+                      /** Organization that issued id (0..1) */
+                      assigner?: Reference;
+                  }
+
+                  /**
+                   * Resolves profile inheritance chains by walking `baseDefinition` links.
+                   *
+                   * The resolver loads each StructureDefinition on demand via the provided
+                   * {@link DefinitionProvider}, detects circular dependencies, and caches
+                   * resolved chains for repeated lookups.
+                   *
+                   * @example
+                   * ```typescript
+                   * const resolver = new InheritanceChainResolver(provider);
+                   * const chain = await resolver.resolve(
+                   *   'http://hl7.org/fhir/StructureDefinition/Patient'
+                   * );
+                   * // → ['http://hl7.org/fhir/StructureDefinition/Patient',
+                   * //    'http://hl7.org/fhir/StructureDefinition/DomainResource',
+                   * //    'http://hl7.org/fhir/StructureDefinition/Resource']
+                   * ```
+                   */
+                  declare class InheritanceChainResolver {
+                      private readonly _provider;
+                      /** Cache of resolved chains: canonical URL → chain array */
+                      private readonly _cache;
+                      /** Statistics counter */
+                      private _resolutionCount;
+                      constructor(provider: DefinitionProvider);
+                      /**
+                       * Resolve the full inheritance chain for a profile.
+                       *
+                       * Returns an array of canonical URLs ordered from child to root:
+                       * `[startUrl, ..., parentUrl, rootUrl]`
+                       *
+                       * @param url - Canonical URL of the starting StructureDefinition
+                       * @returns Inheritance chain from child to root
+                       * @throws {@link CircularDependencyError} if a cycle is detected
+                           * @throws {@link ResourceNotFoundError} if a definition cannot be loaded
+                               */
+                           resolve(url: string): Promise<string[]>;
+                           /**
+                            * Invalidate the cached chain for a specific URL.
+                            *
+                            * Should be called when a StructureDefinition is re-registered,
+                            * as its `baseDefinition` may have changed.
+                            *
+                            * @param url - Canonical URL to invalidate
+                            */
+                           invalidate(url: string): void;
+                           /**
+                            * Clear all cached chains.
+                            */
+                           clearCache(): void;
+                           /**
+                            * Number of chains that have been resolved (not from cache).
+                            */
+                           get resolutionCount(): number;
+                           /**
+                            * Number of chains currently in the cache.
+                            */
+                           get cacheSize(): number;
+                           /**
+                            * Recursive resolution with circular dependency detection.
+                            *
+                            * @param url - Current URL to resolve
+                            * @param inFlight - Set of URLs currently being resolved (cycle detection)
+                            * @returns Chain from current URL to root
+                            */
+                           private _resolveRecursive;
+                       }
+
+                       /**
+                        * Thrown when a loaded or registered StructureDefinition is missing
+                        * required fields or has invalid structure.
+                        *
+                        * Required fields for a valid StructureDefinition:
+                        * - `url` — canonical URL
+                        * - `name` — computer-friendly name
+                        * - `status` — publication status
+                        * - `kind` — resource | complex-type | primitive-type | logical
+                        *
+                        * @example
+                        * ```typescript
+                        * throw new InvalidStructureDefinitionError(
+                        *   'Missing required field: url',
+                        *   'http://example.org/MyProfile'
+                        * );
+                        * ```
+                        */
+                       export declare class InvalidStructureDefinitionError extends ContextError {
+                           readonly name = "InvalidStructureDefinitionError";
+                           /** The URL of the invalid definition (if available) */
+                           readonly url: string | undefined;
+                           constructor(reason: string, url?: string);
+                       }
+
+                       /**
+                        * A resolved constraint (invariant) on a canonical element.
+                        *
+                        * Corresponds to a simplified version of `ElementDefinition.constraint`.
+                        */
+                       export declare interface Invariant {
+                           /** Unique key identifying this constraint. */
+                           key: string;
+                           /**
+                            * error | warning
+                            * @see https://hl7.org/fhir/R4/valueset-constraint-severity.html
+                            */
+                           severity: ConstraintSeverity;
+                           /** Human-readable description of the constraint. */
+                           human: string;
+                           /** FHIRPath expression that must evaluate to `true`. */
+                           expression?: string;
+                           /**
+                            * Canonical URL of the StructureDefinition where this constraint
+                            * was originally defined.
+                            */
+                           source?: string;
+                       }
+
+                       /**
+                        * Check if an element defines a BackboneElement or Element inner type.
+                        *
+                        * An element is an inner type root if:
+                        * - Its `types` array contains a type with `code === 'BackboneElement'` or `code === 'Element'`
+                        * - It is not the root element of the profile (path has at least one dot)
+                        *
+                        * @param element - The canonical element to check
+                        * @returns `true` if this element defines an inner type
+                        */
+                       export declare function isBackboneElementType(element: CanonicalElement): boolean;
+
+                       /**
+                        * Check whether a path ends with `[x]` (choice type wildcard).
+                        *
+                        * @example
+                        * isChoiceTypePath('Observation.value[x]')  // true
+                        * isChoiceTypePath('Observation.valueString')  // false
+                        * isChoiceTypePath('Observation.value')  // false
+                        */
+                       export declare function isChoiceTypePath(path: string): boolean;
+
+                       /**
+                        * Check whether `descendantPath` is a descendant of `ancestorPath`
+                        * (at any depth).
+                        *
+                        * @example
+                        * isDescendant('Patient.name', 'Patient.name.given')        // true
+                        * isDescendant('Patient.name', 'Patient.name.given.value')  // true
+                        * isDescendant('Patient.name', 'Patient.name')              // false
+                        * isDescendant('Patient.name', 'Patient.identifier')        // false
+                        */
+                       export declare function isDescendant(ancestorPath: string, descendantPath: string): boolean;
+
+                       /**
+                        * Check whether `childPath` is a direct child of `parentPath`.
+                        *
+                        * A direct child has exactly one more segment than the parent.
+                        *
+                        * @example
+                        * isDirectChild('Patient.name', 'Patient.name.given')       // true
+                        * isDirectChild('Patient.name', 'Patient.name.given.value')  // false
+                        * isDirectChild('Patient.name', 'Patient.identifier')        // false
+                        */
+                       export declare function isDirectChild(parentPath: string, childPath: string): boolean;
+
+                       /**
+                        * Determine whether max value `a` is larger than max value `b`.
+                        *
+                        * FHIR max is either a non-negative integer string or `"*"` (unbounded).
+                        * `"*"` is treated as infinity.
+                        *
+                        * @example
+                        * isLargerMax('5', '3')   // true
+                        * isLargerMax('*', '3')   // true
+                        * isLargerMax('3', '*')   // false
+                        * isLargerMax('3', '3')   // false
+                        * isLargerMax('*', '*')   // false
+                        */
+                       export declare function isLargerMax(a: string, b: string): boolean;
+
+                       /**
+                        * Load all core definitions and return them as a Map.
+                        *
+                        * Loads in dependency order (base → primitives → complex → resources).
+                        *
+                        * @param specDirectory - Optional override directory path
+                        * @returns Map of canonical URL → StructureDefinition
+                        */
+                       export declare function loadAllCoreDefinitions(specDirectory?: string): Promise<Map<string, StructureDefinition>>;
+
+                       /**
+                        * Load CanonicalProfiles from a FHIR Bundle JSON file.
+                        *
+                        * Reads the file synchronously (spec files are loaded once at startup),
+                        * parses the JSON, and delegates to `loadBundleFromObject`.
+                        *
+                        * @param filePath - Absolute path to a FHIR Bundle JSON file.
+                        * @param options - Optional filters to control which entries are loaded.
+                        * @returns BundleLoadResult with profiles, errors, and statistics.
+                        * @throws Error if the file cannot be read or is not valid JSON.
+                        */
+                       export declare function loadBundleFromFile(filePath: string, options?: BundleLoadOptions): BundleLoadResult;
+
+                       /**
+                        * Load CanonicalProfiles from an already-parsed Bundle object.
+                        *
+                        * This is the core loading function. It:
+                        * 1. Extracts all StructureDefinition entries from the bundle
+                        * 2. Applies filter options (kind, abstract, type)
+                        * 3. Parses each SD through `parseStructureDefinition`
+                        * 4. Converts each parsed SD to `CanonicalProfile` via `buildCanonicalProfile`
+                        * 5. Collects errors without aborting (partial failure tolerance)
+                        *
+                        * @param bundle - A parsed FHIR Bundle object containing StructureDefinition entries.
+                        * @param options - Optional filters to control which entries are loaded.
+                        * @returns BundleLoadResult with profiles, errors, and statistics.
+                        */
+                       export declare function loadBundleFromObject(bundle: BundleShape, options?: BundleLoadOptions): BundleLoadResult;
+
+                       /**
+                        * Load and merge multiple bundle files in order.
+                        *
+                        * Later bundles override earlier ones for the same canonical URL.
+                        * This supports the standard loading order:
+                        *   1. profiles-types.json    — type system (no tables)
+                        *   2. profiles-resources.json — clinical resources
+                        *   3. profiles-others.json   — conformance resources
+                        *   4. profiles-platform.json — platform resources (Phase 9)
+                        *
+                        * @param filePaths - Array of absolute paths to FHIR Bundle JSON files.
+                        * @param options - Optional filters applied to each bundle.
+                        * @returns Merged BundleLoadResult with deduplicated profiles.
+                        */
+                       export declare function loadBundlesFromFiles(filePaths: string[], options?: BundleLoadOptions): BundleLoadResult;
+
+                       /**
+                        * Load a single core StructureDefinition by name (async).
+                        *
+                        * @param name - Definition name (e.g., `"Patient"`, `"string"`)
+                        * @param baseDir - Directory containing the JSON files
+                        * @returns Parsed StructureDefinition
+                        * @throws {@link LoaderError} if the file cannot be read or parsed
+                            */
+                        export declare function loadCoreDefinition(name: string, baseDir: string): Promise<StructureDefinition>;
+
+                        /**
+                         * Load a single core StructureDefinition by name (synchronous).
+                         *
+                         * @param name - Definition name (e.g., `"Patient"`, `"string"`)
+                         * @param baseDir - Directory containing the JSON files
+                         * @returns Parsed StructureDefinition
+                         * @throws {@link LoaderError} if the file cannot be read or parsed
+                             */
+                         export declare function loadCoreDefinitionSync(name: string, baseDir: string): StructureDefinition;
+
+                         /**
+                          * Thrown when a {@link StructureDefinitionLoader} encounters an I/O
+                          * or parse failure while loading a definition.
+                          *
+                          * The original error is preserved as `cause` for debugging.
+                          *
+                          * @example
+                          * ```typescript
+                          * throw new LoaderError(
+                          *   'http://hl7.org/fhir/StructureDefinition/Patient',
+                          *   'filesystem',
+                          *   originalError
+                          * );
+                          * ```
+                          */
+                         export declare class LoaderError extends ContextError {
+                             readonly name = "LoaderError";
+                             /** The canonical URL being loaded when the error occurred */
+                             readonly url: string;
+                             /** The loader source type that failed */
+                             readonly sourceType: string;
+                             constructor(url: string, sourceType: string, cause?: Error);
+                         }
+
+                         /**
+                          * Options for individual loader instances.
+                          */
+                         export declare interface LoaderOptions {
+                             /**
+                              * Base directory or URL prefix for resolving relative paths.
+                              */
+                             basePath?: string;
+                             /**
+                              * Request timeout in milliseconds (for future HTTP loaders).
+                              *
+                              * @defaultValue `30000`
+                              */
+                             timeout?: number;
+                             /**
+                              * Number of retry attempts on transient failures.
+                              *
+                              * @defaultValue `0`
+                              */
+                             retryCount?: number;
+                         }
+
+                         /**
+                          * Generate the default slicing definition for extension elements.
+                          *
+                          * Corresponds to HAPI's `makeExtensionSlicing()`. Extension elements
+                          * are always sliced by `url` using the `value` discriminator type.
+                          *
+                          * @returns A new {@link ElementDefinitionSlicing} for extensions.
+                          */
+                         export declare function makeExtensionSlicing(): ElementDefinitionSlicing;
+
+                         /**
+                          * Check whether `concretePath` matches a choice type `choicePath`.
+                          *
+                          * The concrete path must share the same prefix (minus `[x]`) and the
+                          * remaining suffix must start with an uppercase letter (the type name).
+                          *
+                          * @example
+                          * matchesChoiceType('Observation.value[x]', 'Observation.valueString')    // true
+                          * matchesChoiceType('Observation.value[x]', 'Observation.valueQuantity')  // true
+                          * matchesChoiceType('Observation.value[x]', 'Observation.code')           // false
+                          * matchesChoiceType('Observation.value[x]', 'Observation.value')          // false
+                          */
+                         export declare function matchesChoiceType(choicePath: string, concretePath: string): boolean;
+
+                         /**
+                          * A loader that resolves StructureDefinitions from an in-memory Map.
+                          *
+                          * The map is keyed by canonical URL. Lookups are synchronous but the
+                          * interface returns a Promise for consistency with other loaders.
+                          *
+                          * @example
+                          * ```typescript
+                          * const definitions = new Map<string, StructureDefinition>();
+                          * definitions.set('http://hl7.org/fhir/StructureDefinition/Patient', patientSD);
+                          * const loader = new MemoryLoader(definitions);
+                          * ```
+                          */
+                         export declare class MemoryLoader implements StructureDefinitionLoader {
+                             private readonly _definitions;
+                             /**
+                              * @param definitions - Map of canonical URL → StructureDefinition.
+                              *                      The map is **not** copied; mutations to the
+                              *                      original map are visible to the loader.
+                              */
+                             constructor(definitions: Map<string, StructureDefinition>);
+                             load(url: string): Promise<StructureDefinition | null>;
+                             canLoad(url: string): boolean;
+                             getSourceType(): string;
+                             /**
+                              * Number of definitions currently held in the map.
+                              */
+                             get size(): number;
+                         }
+
+                         /**
+                          * Merge binding constraints with strength validation.
+                          *
+                          * Rules:
+                          * - Cannot relax a REQUIRED binding (REQUIRED → anything else = error)
+                          * - Derived binding replaces base binding
+                          *
+                          * @returns The merged binding.
+                          */
+                         export declare function mergeBinding(baseBinding: ElementDefinitionBinding | undefined, diffBinding: ElementDefinitionBinding | undefined, issues: SnapshotIssue[], path: string): ElementDefinitionBinding | undefined;
+
+                         /**
+                          * Merge cardinality constraints (min/max) with validation.
+                          *
+                          * Rules:
+                          * - `derived.min` must be >= `base.min` (except for slices)
+                          * - `derived.max` must be <= `base.max`
+                          *
+                          * @internal Exported for direct testing.
+                          */
+                         export declare function mergeCardinality(dest: ElementDefinition, source: ElementDefinition, issues: SnapshotIssue[], path?: string): void;
+
+                         /**
+                          * Merge constraint (invariant) lists by appending derived constraints,
+                          * de-duplicating by `key`.
+                          *
+                          * Base constraints are kept; derived constraints with the same key
+                          * replace the base version.
+                          *
+                          * @returns The merged constraint array.
+                          */
+                         export declare function mergeConstraintList(baseConstraints: readonly ElementDefinitionConstraint[] | undefined, diffConstraints: readonly ElementDefinitionConstraint[] | undefined): ElementDefinitionConstraint[] | undefined;
+
+                         /**
+                          * Apply differential constraints onto a snapshot element.
+                          *
+                          * Corresponds to HAPI `updateFromDefinition(dest, source, ...)`.
+                          * The `dest` element is mutated in place and also returned.
+                          *
+                          * @param dest - The working snapshot element (initially cloned from base).
+                          * @param source - The differential element to apply.
+                          * @param issues - Mutable array to collect issues.
+                          * @returns The mutated `dest` element.
+                          */
+                         export declare function mergeConstraints(dest: ElementDefinition, source: ElementDefinition, issues: SnapshotIssue[]): ElementDefinition;
+
+                         /**
+                          * Shared state passed through all recursive `processPaths` calls.
+                          */
+                         export declare interface MergeContext {
+                             /** FhirContext for loading datatype definitions (async). `undefined` for sync-only tests. */
+                             readonly fhirContext?: FhirContext;
+                             /** Preloaded datatype snapshots cache (url → snapshot elements). */
+                             readonly datatypeCache: Map<string, readonly ElementDefinition[]>;
+                             /** Issue collector. */
+                             readonly issues: SnapshotIssue[];
+                             /** URL of the profile being generated. */
+                             readonly profileUrl: string;
+                             /** Current recursion depth. */
+                             depth: number;
+                             /** Maximum allowed recursion depth. */
+                             readonly maxDepth: number;
+                         }
+
+                         /**
+                          * High-level convenience function: merge a base snapshot with a differential
+                          * to produce a new snapshot element list.
+                          *
+                          * This is the primary entry point for testing and for the SnapshotGenerator
+                          * orchestrator (Task 4.5).
+                          *
+                          * @param baseElements - The base profile's snapshot elements.
+                          * @param diffElements - The differential elements to apply.
+                          * @param context - Merge context (or auto-created if not provided).
+                          * @returns The merged snapshot element list.
+                          */
+                         export declare function mergeSnapshot(baseElements: readonly ElementDefinition[], diffElements: readonly ElementDefinition[], context?: MergeContext): {
+                             elements: ElementDefinition[];
+                             issues: SnapshotIssue[];
+                         };
+
+                         /**
+                          * Merge type constraints with compatibility validation.
+                          *
+                          * Each derived type must be compatible with at least one base type.
+                          * Special allowances: Extension, Element, *, Resource/DomainResource.
+                          *
+                          * If valid, derived types replace base types entirely.
+                          *
+                          * @returns The merged type array (derived types if valid, base types if no diff).
+                          */
+                         export declare function mergeTypes(baseTypes: readonly ElementDefinitionType[] | undefined, diffTypes: readonly ElementDefinitionType[] | undefined, issues: SnapshotIssue[], path: string): ElementDefinitionType[] | undefined;
+
+                         /**
+                          * The metadata about a resource. This is content in the resource that is
+                          * maintained by the infrastructure.
+                          * @see https://hl7.org/fhir/R4/resource.html#Meta
+                          */
+                         export declare interface Meta extends Element {
+                             /** Version specific identifier (0..1) */
+                             versionId?: FhirId;
+                             /** When the resource version last changed (0..1) */
+                             lastUpdated?: FhirInstant;
+                             /** Identifies where the resource comes from (0..1) */
+                             source?: FhirUri;
+                             /** Profiles this resource claims to conform to (0..*) */
+                             profile?: FhirCanonical[];
+                             /** Security Labels applied to this resource (0..*) */
+                             security?: Coding[];
+                             /** Tags applied to this resource (0..*) */
+                             tag?: Coding[];
+                         }
+
+                         /**
+                          * A human-readable summary of the resource conveying the essential
+                          * clinical and business information.
+                          * @see https://hl7.org/fhir/R4/narrative.html#Narrative
+                          */
+                         export declare interface Narrative extends Element {
+                             /** generated | extensions | additional | empty (1..1) */
+                             status: NarrativeStatus;
+                             /** Limited xhtml content (1..1) */
+                             div: FhirXhtml;
+                         }
+
+                         /**
+                          * The status of a narrative.
+                          * @see https://hl7.org/fhir/R4/valueset-narrative-status.html
+                          */
+                         export declare type NarrativeStatus = 'generated' | 'extensions' | 'additional' | 'empty';
+
+                         /**
+                          * Get the parent path (everything before the last `.`).
+                          *
+                          * @example
+                          * parentPath('Patient.name.given')  // 'Patient.name'
+                          * parentPath('Patient.name')        // 'Patient'
+                          * parentPath('Patient')             // undefined
+                          */
+                         export declare function parentPath(path: string): string | undefined;
+
+                         /**
+                          * Parse an ElementDefinition JSON object.
+                          *
+                          * ElementDefinition is the most complex data type in FHIR,
+                          * with ~37 fields and 8 sub-types.
+                          */
+                         export declare function parseElementDefinition(obj: Record<string, unknown>, path: string): {
+                             result: ElementDefinition;
+                             issues: ParseIssue[];
+                         };
+
+                         /**
+                          * Machine-readable error codes for parse issues.
+                          *
+                          * Each code corresponds to a specific category of parsing problem.
+                          * Consumers can switch on these codes for programmatic error handling.
+                          */
+                         export declare type ParseErrorCode = 
+                         /** JSON syntax error (e.g., malformed JSON string) */
+                         'INVALID_JSON'
+                         /** Missing required `resourceType` property */
+                         | 'MISSING_RESOURCE_TYPE'
+                         /** `resourceType` value is not a recognized FHIR resource type */
+                         | 'UNKNOWN_RESOURCE_TYPE'
+                         /** Primitive value has wrong JavaScript type (e.g., string where number expected) */
+                         | 'INVALID_PRIMITIVE'
+                         /** Object structure does not match expected shape (e.g., array where object expected) */
+                         | 'INVALID_STRUCTURE'
+                         /** Choice type `[x]` property name has an unrecognized type suffix */
+                         | 'INVALID_CHOICE_TYPE'
+                         /** Multiple variants of the same choice type field are present */
+                         | 'MULTIPLE_CHOICE_VALUES'
+                         /** `_element` array length does not match the corresponding value array */
+                         | 'ARRAY_MISMATCH'
+                         /** Unexpected `null` value in a non-nullable position */
+                         | 'UNEXPECTED_NULL'
+                         /** Property name not recognized for this type (severity: warning) */
+                         | 'UNEXPECTED_PROPERTY';
+
+                         /**
+                          * Create a failed parse result.
+                          *
+                          * @param issues - The error(s) that caused the failure (must contain at least one error)
+                          */
+                         export declare function parseFailure<T>(issues: ParseIssue[]): ParseResult<T>;
+
+                         /**
+                          * Parse a FHIR JSON string into a Resource object.
+                          *
+                          * This is the main entry point for the parser. It:
+                          * 1. Calls `JSON.parse()` with error capture
+                          * 2. Delegates to {@link parseFhirObject} for structural parsing
+                          *
+                          * Stage-1 supports dedicated parsing for `StructureDefinition` (Task 2.5).
+                          * All other resource types are parsed generically.
+                          *
+                          * @param json - A FHIR JSON string
+                          * @returns A `ParseResult` containing the parsed `Resource` or error details
+                          *
+                          * @example
+                          * ```typescript
+                          * const result = parseFhirJson('{"resourceType":"Patient","id":"123"}');
+                          * if (result.success) {
+                          *   console.log(result.data.resourceType); // "Patient"
+                          * }
+                          * ```
+                          */
+                         export declare function parseFhirJson(json: string): ParseResult<Resource>;
+
+                         /**
+                          * Parse an already-parsed JSON value into a Resource object.
+                          *
+                          * Use this when you already have a JavaScript object (e.g., from a database
+                          * or from `JSON.parse()` called externally).
+                          *
+                          * @param obj - An unknown value (expected to be a plain JSON object with `resourceType`)
+                          * @returns A `ParseResult` containing the parsed `Resource` or error details
+                          */
+                         export declare function parseFhirObject(obj: unknown): ParseResult<Resource>;
+
+                         /**
+                          * A single issue encountered during parsing.
+                          *
+                          * Issues are collected throughout the parse process and returned in the
+                          * {@link ParseResult}. Both errors and warnings use this same structure.
+                          *
+                          * @example
+                          * ```typescript
+                          * const issue: ParseIssue = {
+                          *   severity: 'error',
+                          *   code: 'MISSING_RESOURCE_TYPE',
+                          *   message: 'Object is missing the required "resourceType" property',
+                          *   path: '$',
+                          * };
+                          * ```
+                          */
+                         export declare interface ParseIssue {
+                             /** Severity level — `error` blocks successful parsing, `warning` does not */
+                             readonly severity: ParseSeverity;
+                             /** Machine-readable error code for programmatic handling */
+                             readonly code: ParseErrorCode;
+                             /** Human-readable description of the issue */
+                             readonly message: string;
+                             /**
+                              * JSON path where the issue was detected.
+                              *
+                              * Uses dot notation with array indices:
+                              * - `"StructureDefinition"` — root level
+                              * - `"StructureDefinition.snapshot.element[0].type[1].code"` — nested
+                              * - `"$"` — before resourceType is known
+                              */
+                             readonly path: string;
+                         }
+
+                         /**
+                          * Result of a parse operation.
+                          *
+                          * Uses a discriminated union on `success`:
+                          * - `success: true` — parsing succeeded; `data` contains the parsed value,
+                          *   `issues` may contain warnings
+                          * - `success: false` — parsing failed; `data` is `undefined`,
+                          *   `issues` contains at least one error
+                          *
+                          * @typeParam T - The expected output type (e.g., `StructureDefinition`)
+                          *
+                          * @example
+                          * ```typescript
+                          * const result = parseFhirJson(jsonString);
+                          * if (result.success) {
+                          *   console.log(result.data.url); // T is available
+                          * } else {
+                          *   for (const issue of result.issues) {
+                          *     console.error(`[${issue.path}] ${issue.message}`);
+                          *   }
+                          * }
+                          * ```
+                          */
+                         export declare type ParseResult<T> = {
+                             readonly success: true;
+                             readonly data: T;
+                             readonly issues: readonly ParseIssue[];
+                         } | {
+                             readonly success: false;
+                             readonly data: undefined;
+                             readonly issues: readonly ParseIssue[];
+                         };
+
+                         /**
+                          * FHIR JSON Parse Error Types
+                          *
+                          * Structured error types for the fhir-parser module. Provides precise
+                          * error localization via JSON path tracking and supports collecting
+                          * multiple issues (errors + warnings) in a single parse pass.
+                          *
+                          * Design decisions:
+                          * - Result type over exceptions: allows multi-error collection
+                          * - Path tracking: every issue carries the JSON path for precise localization
+                          * - Warning support: non-fatal issues (e.g., unknown properties) reported
+                          *   as warnings without blocking the parse
+                          *
+                          * @module fhir-parser
+                          */
+                         /**
+                          * Severity level of a parse issue.
+                          *
+                          * - `error` — the issue prevents correct interpretation of the data
+                          * - `warning` — the data can still be used, but something unexpected was found
+                          */
+                         export declare type ParseSeverity = 'error' | 'warning';
+
+                         /**
+                          * Parse a StructureDefinition JSON object.
+                          *
+                          * This is the most important parse function in Stage-1. All downstream
+                          * modules (fhir-context, fhir-profile, fhir-validator) depend on
+                          * correctly parsed StructureDefinitions.
+                          *
+                          * @param obj - A parsed JSON object (already validated as having resourceType = "StructureDefinition")
+                          * @param path - Current JSON path (for error reporting)
+                          */
+                         export declare function parseStructureDefinition(obj: Record<string, unknown>, path: string): ParseResult<StructureDefinition>;
+
+                         /**
+                          * Create a successful parse result.
+                          *
+                          * @param data - The parsed value
+                          * @param issues - Any warnings collected during parsing (default: none)
+                          */
+                         export declare function parseSuccess<T>(data: T, issues?: ParseIssue[]): ParseResult<T>;
+
+                         /**
+                          * Get the depth (number of segments) of a path.
+                          *
+                          * @example
+                          * pathDepth('Patient')             // 1
+                          * pathDepth('Patient.name')        // 2
+                          * pathDepth('Patient.name.given')  // 3
+                          */
+                         export declare function pathDepth(path: string): number;
+
+                         /**
+                          * Check whether two paths match exactly.
+                          *
+                          * @example
+                          * pathMatches('Patient.name', 'Patient.name')       // true
+                          * pathMatches('Patient.name', 'Patient.identifier')  // false
+                          */
+                         export declare function pathMatches(basePath: string, diffPath: string): boolean;
+
+                         /**
+                          * A time period defined by a start and end date/time.
+                          * @see https://hl7.org/fhir/R4/datatypes.html#Period
+                          */
+                         export declare interface Period extends Element {
+                             /** Starting time with inclusive boundary (0..1) */
+                             start?: FhirDateTime;
+                             /** End time with inclusive boundary, if not ongoing (0..1) */
+                             end?: FhirDateTime;
+                         }
+
+                         /**
+                          * Primitive types — FHIR primitive data types.
+                          */
+                         export declare const PRIMITIVE_TYPES: readonly ["base64Binary", "boolean", "canonical", "code", "date", "dateTime", "decimal", "id", "instant", "integer", "markdown", "oid", "positiveInt", "string", "time", "unsignedInt", "uri", "url", "uuid", "xhtml"];
+
+                         /**
+                          * Base-driven merge loop (corresponds to HAPI `processPaths`).
+                          *
+                          * Walks the base snapshot within `baseScope`, finds matching differential
+                          * entries within `[diffStart, diffEnd]`, and appends merged elements to `result`.
+                          *
+                          * @param context - Shared merge state.
+                          * @param result - Mutable output array to append merged elements to.
+                          * @param baseElements - The base snapshot element list.
+                          * @param baseCursor - Start index in baseElements (inclusive).
+                          * @param baseLimit - End index in baseElements (inclusive).
+                          * @param diffTrackers - The differential element trackers.
+                          * @param diffStart - Start index in diffTrackers (inclusive).
+                          * @param diffEnd - End index in diffTrackers (inclusive).
+                          * @param contextPathSrc - Source path prefix for rewriting (e.g., datatype name).
+                          * @param contextPathDst - Destination path prefix for rewriting.
+                          */
+                         export declare function processPaths(context: MergeContext, result: ElementDefinition[], baseElements: readonly ElementDefinition[], baseCursor: number, baseLimit: number, diffTrackers: readonly DiffElementTracker[], diffStart: number, diffEnd: number, contextPathSrc: string, contextPathDst: string): void;
+
+                         /**
+                          * fhir-profile — Error Types
+                          *
+                          * Structured error hierarchy for the FHIR profile module.
+                          * All errors extend {@link ProfileError} so consumers can catch
+                          * profile-related failures with a single `catch` clause.
+                          *
+                          * Error hierarchy:
+                          * ```
+                          * ProfileError (base)
+                          * ├── SnapshotCircularDependencyError
+                          * ├── BaseNotFoundError
+                          * ├── ConstraintViolationError
+                          * └── UnconsumedDifferentialError
+                          * ```
+                          *
+                          * @module fhir-profile
+                          */
+                         /**
+                          * Base error class for all fhir-profile failures.
+                          *
+                          * Provides a stable `name` property and preserves the original `cause`
+                          * when wrapping lower-level errors.
+                          *
+                          * @example
+                          * ```typescript
+                          * try {
+                          *   await generator.generate(sd);
+                          * } catch (err) {
+                          *   if (err instanceof ProfileError) {
+                          *     // Handle any profile-related error
+                          *   }
+                          * }
+                          * ```
+                          */
+                         export declare class ProfileError extends Error {
+                             readonly name: string;
+                             constructor(message: string, options?: ErrorOptions);
+                         }
+
+                         /**
+                          * Thrown when the profile required for validation cannot be found or loaded.
+                          *
+                          * This occurs when:
+                          * - The specified `profileUrl` does not exist in the FhirContext
+                          * - The profile exists but has no snapshot
+                          * - No profile URL is specified and none can be inferred from the resource
+                          *
+                          * @example
+                          * ```typescript
+                          * throw new ProfileNotFoundError(
+                          *   'http://example.org/StructureDefinition/UnknownProfile',
+                          * );
+                          * ```
+                          */
+                         export declare class ProfileNotFoundError extends ValidatorError {
+                             readonly name = "ProfileNotFoundError";
+                             /** The canonical URL of the profile that could not be found. */
+                             readonly profileUrl: string;
+                             constructor(profileUrl: string, cause?: Error);
+                         }
+
+                         /**
+                          * How a property is represented when serialized.
+                          * @see https://hl7.org/fhir/R4/valueset-property-representation.html
+                          */
+                         export declare type PropertyRepresentation = 'xmlAttr' | 'xmlText' | 'typeAttr' | 'cdaText' | 'xhtml';
+
+                         /**
+                          * Publication status of a FHIR conformance resource.
+                          * @see https://hl7.org/fhir/R4/valueset-publication-status.html
+                          */
+                         export declare type PublicationStatus = 'draft' | 'active' | 'retired' | 'unknown';
+
+                         /**
+                          * A measured amount (or an amount that can potentially be measured).
+                          * @see https://hl7.org/fhir/R4/datatypes.html#Quantity
+                          */
+                         export declare interface Quantity extends Element {
+                             /** Numerical value (with implicit precision) (0..1) */
+                             value?: FhirDecimal;
+                             /** `<` | `<=` | `>=` | `>` — how to understand the value (0..1) */
+                             comparator?: FhirCode;
+                             /** Unit representation (0..1) */
+                             unit?: FhirString;
+                             /** System that defines coded unit form (0..1) */
+                             system?: FhirUri;
+                             /** Coded form of the unit (0..1) */
+                             code?: FhirCode;
+                         }
+
+                         /**
+                          * A reference from one resource to another.
+                          * @see https://hl7.org/fhir/R4/references.html#Reference
+                          */
+                         export declare interface Reference extends Element {
+                             /** Literal reference, Relative, internal or absolute URL (0..1) */
+                             reference?: FhirString;
+                             /** Type the reference refers to (e.g., "Patient") (0..1) */
+                             type?: FhirUri;
+                             /** Logical reference, when literal reference is not known (0..1) */
+                             identifier?: Identifier;
+                             /** Text alternative for the resource (0..1) */
+                             display?: FhirString;
+                         }
+
+                         /**
+                          * Whether all resource references need to be version-specific.
+                          * @see https://hl7.org/fhir/R4/valueset-reference-version-rules.html
+                          */
+                         export declare type ReferenceVersionRules = 'either' | 'independent' | 'specific';
+
+                         /**
+                          * Resolve default validation options.
+                          *
+                          * Fills in missing fields with sensible defaults.
+                          *
+                          * @param options - User-provided options (may be partial).
+                          * @returns Fully resolved options with all fields populated.
+                          */
+                         export declare function resolveValidationOptions(options?: ValidationOptions): Required<ValidationOptions>;
+
+                         /**
+                          * Abstract base for all FHIR resources.
+                          * @see https://hl7.org/fhir/R4/resource.html
+                          */
+                         export declare interface Resource {
+                             /**
+                              * The type of the resource (1..1)
+                              *
+                              * This is typed as `string` rather than `FhirString` because it serves
+                              * as a discriminator field that concrete resource interfaces narrow to
+                              * a string literal (e.g., `'StructureDefinition'`, `'Patient'`).
+                              * Branded types would prevent this narrowing.
+                              */
+                             resourceType: string;
+                             /** Logical id of this artifact (0..1) */
+                             id?: FhirId;
+                             /** Metadata about the resource (0..1) */
+                             meta?: Meta;
+                             /** A set of rules under which this content was created (0..1) */
+                             implicitRules?: FhirUri;
+                             /** Language of the resource content (0..1) */
+                             language?: FhirCode;
+                         }
+
+                         /**
+                          * Thrown when a StructureDefinition cannot be resolved by any loader.
+                          *
+                          * @example
+                          * ```typescript
+                          * throw new ResourceNotFoundError(
+                          *   'http://hl7.org/fhir/StructureDefinition/UnknownType',
+                          *   ['memory', 'filesystem']
+                          * );
+                          * ```
+                          */
+                         export declare class ResourceNotFoundError extends ContextError {
+                             readonly name = "ResourceNotFoundError";
+                             /** The canonical URL that could not be resolved */
+                             readonly url: string;
+                             /** Loader source types that were tried */
+                             readonly triedSources: readonly string[];
+                             constructor(url: string, triedSources?: string[]);
+                         }
+
+                         /**
+                          * Serialize a Resource object to a FHIR JSON string.
+                          *
+                          * Output conforms to FHIR R4 JSON conventions:
+                          * - `resourceType` is the first property
+                          * - Remaining properties are in alphabetical order
+                          * - Choice type fields use their original JSON property names
+                          * - Empty values (`undefined`, `[]`, `{}`) are omitted
+                          *
+                          * @param resource - The Resource to serialize
+                          * @returns A FHIR JSON string (pretty-printed with 2-space indent)
+                          *
+                          * @example
+                          * ```typescript
+                          * const sd: StructureDefinition = { resourceType: 'StructureDefinition', ... };
+                          * const json = serializeToFhirJson(sd);
+                          * // '{\n  "resourceType": "StructureDefinition",\n  ...\n}'
+                          * ```
+                          */
+                         export declare function serializeToFhirJson(resource: Resource): string;
+
+                         /**
+                          * Serialize a Resource object to a plain JavaScript object suitable
+                          * for FHIR JSON (without calling `JSON.stringify`).
+                          *
+                          * Use this when you need the object form (e.g., for storage or
+                          * further manipulation) rather than a string.
+                          *
+                          * @param resource - The Resource to serialize
+                          * @returns A plain object conforming to FHIR JSON conventions
+                          */
+                         export declare function serializeToFhirObject(resource: Resource): Record<string, unknown>;
+
+                         /**
+                          * Populate `dest.base` with traceability information from the base element.
+                          *
+                          * Corresponds to HAPI `updateFromBase(derived, base)`.
+                          * If `base` already has a `.base`, we copy from `base.base` (preserving
+                          * original ancestry). Otherwise we copy from `base` directly.
+                          *
+                          * @param dest - The element to set base traceability on.
+                          * @param base - The base element to derive traceability from.
+                          */
+                         export declare function setBaseTraceability(dest: ElementDefinition, base: ElementDefinition): void;
+
+                         /**
+                          * A resolved slicing definition on a canonical element.
+                          *
+                          * Corresponds to a simplified version of `ElementDefinition.slicing`.
+                          * Unlike the FHIR version, `ordered` is always a boolean (default `false`).
+                          */
+                         export declare interface SlicingDefinition {
+                             /** Discriminators used to match slices. */
+                             discriminators: SlicingDiscriminatorDef[];
+                             /**
+                              * closed | open | openAtEnd
+                              * @see https://hl7.org/fhir/R4/valueset-resource-slicing-rules.html
+                              */
+                             rules: SlicingRules;
+                             /**
+                              * Whether elements must appear in the same order as slices.
+                              *
+                              * Always has a value (default `false`), unlike the FHIR spec where
+                              * this is optional.
+                              */
+                             ordered: boolean;
+                             /** Human-readable description of the slicing. */
+                             description?: string;
+                         }
+
+                         /**
+                          * Designates a discriminator to differentiate between slices.
+                          * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.slicing.discriminator
+                          */
+                         export declare interface SlicingDiscriminator extends Element {
+                             /**
+                              * value | exists | pattern | type | profile (1..1)
+                              * @see https://hl7.org/fhir/R4/valueset-discriminator-type.html
+                              */
+                             type: DiscriminatorType;
+                             /**
+                              * Path to element value (1..1)
+                              *
+                              * A FHIRPath expression that identifies the element within the
+                              * resource/type to be used as the discriminator.
+                              */
+                             path: FhirString;
+                         }
+
+                         /**
+                          * A single discriminator within a slicing definition.
+                          *
+                          * Corresponds to `ElementDefinition.slicing.discriminator`.
+                          */
+                         export declare interface SlicingDiscriminatorDef {
+                             /**
+                              * value | exists | pattern | type | profile
+                              * @see https://hl7.org/fhir/R4/valueset-discriminator-type.html
+                              */
+                             type: DiscriminatorType;
+                             /**
+                              * FHIRPath expression identifying the discriminating element.
+                              */
+                             path: string;
+                         }
+
+                         /**
+                          * How slices are interpreted when evaluating an instance.
+                          * @see https://hl7.org/fhir/R4/valueset-resource-slicing-rules.html
+                          */
+                         export declare type SlicingRules = 'closed' | 'open' | 'openAtEnd';
+
+                         /**
+                          * Thrown when snapshot generation detects a circular dependency in the
+                          * profile chain.
+                          *
+                          * This occurs when profile A's base chain eventually references A again,
+                          * which would cause infinite recursion during snapshot generation.
+                          * HAPI detects this via a `snapshotStack` of URLs currently being generated.
+                          *
+                          * @example
+                          * ```typescript
+                          * throw new SnapshotCircularDependencyError(
+                          *   'http://example.org/ProfileA',
+                          *   [
+                          *     'http://example.org/ProfileA',
+                          *     'http://example.org/ProfileB',
+                          *     'http://example.org/ProfileA', // cycle back
+                          *   ]
+                          * );
+                          * ```
+                          */
+                         export declare class SnapshotCircularDependencyError extends ProfileError {
+                             readonly name = "SnapshotCircularDependencyError";
+                             /** The canonical URL of the profile that triggered the cycle. */
+                             readonly url: string;
+                             /** The full chain of URLs forming the cycle. */
+                             readonly chain: readonly string[];
+                             constructor(url: string, chain: string[]);
+                         }
+
+                         /**
+                          * Snapshot Generator — top-level orchestrator for snapshot generation.
+                          *
+                          * Corresponds to HAPI's `ProfileUtilities.generateSnapshot()`.
+                          *
+                          * @example
+                          * ```typescript
+                          * const generator = new SnapshotGenerator(fhirContext, { throwOnError: false });
+                          * const result = await generator.generate(myProfile);
+                          * if (result.success) {
+                          *   console.log('Snapshot generated with', result.structureDefinition.snapshot?.element.length, 'elements');
+                          * }
+                          * ```
+                          */
+                         export declare class SnapshotGenerator {
+                             private readonly context;
+                             private readonly options;
+                             /** URLs currently being generated — for circular dependency detection. */
+                             private readonly generationStack;
+                             constructor(context: FhirContext, options?: SnapshotGeneratorOptions);
+                             /**
+                              * Generate a snapshot for a StructureDefinition.
+                              *
+                              * @param sd - StructureDefinition with a differential to expand.
+                              * @returns SnapshotResult with the populated snapshot and any issues.
+                              * @throws {SnapshotCircularDependencyError} if circular reference detected
+                              * @throws {BaseNotFoundError} if base SD cannot be loaded
+                              * @throws {UnconsumedDifferentialError} if throwOnError and unconsumed diffs
+                              */
+                             generate(sd: StructureDefinition): Promise<SnapshotResult>;
+                             /**
+                              * Validate input StructureDefinition.
+                              * Returns true if there's a fatal validation error.
+                              */
+                             private validateInput;
+                             /**
+                              * Load the base StructureDefinition.
+                              */
+                             private loadBase;
+                             /**
+                              * Populate the datatype cache with snapshots of types referenced by
+                              * the differential's child paths.
+                              *
+                              * Scans both base elements and diff elements for type codes, then
+                              * pre-loads their StructureDefinitions into the merge context cache.
+                              */
+                             private populateDatatypeCache;
+                             /**
+                              * Build a SnapshotResult from the current state.
+                              */
+                             private buildResult;
+                         }
+
+                         /**
+                          * Configuration options for snapshot generation.
+                          *
+                          * @example
+                          * ```typescript
+                          * const options: SnapshotGeneratorOptions = {
+                          *   throwOnError: false,
+                          *   maxRecursionDepth: 50,
+                          *   generateCanonical: true,
+                          * };
+                          * ```
+                          */
+                         export declare interface SnapshotGeneratorOptions {
+                             /**
+                              * Whether to throw on the first error or collect all errors.
+                              *
+                              * When `true`, the generator throws immediately on the first error
+                              * (matching HAPI's "exception mode"). When `false` (default), errors
+                              * are collected in {@link SnapshotResult.issues} and generation
+                              * continues as far as possible.
+                              *
+                              * @default false
+                              */
+                             readonly throwOnError?: boolean;
+                             /**
+                              * Maximum recursion depth for nested snapshot generation.
+                              *
+                              * Snapshot generation can recursively trigger generation of other
+                              * profiles (e.g., when a base profile lacks a snapshot, or when
+                              * expanding into datatype definitions). This limit prevents runaway
+                              * recursion in pathological or circular profiles.
+                              *
+                              * @default 50
+                              */
+                             readonly maxRecursionDepth?: number;
+                             /**
+                              * Whether to generate a {@link CanonicalProfile} alongside the snapshot.
+                              *
+                              * When `true`, the result includes a `canonical` field containing
+                              * the MedXAI internal semantic model derived from the generated snapshot.
+                              *
+                              * @default false
+                              */
+                             readonly generateCanonical?: boolean;
+                         }
+
+                         /**
+                          * An issue encountered during snapshot generation.
+                          *
+                          * Mirrors the concept of HAPI's `ValidationMessage` but scoped to
+                          * snapshot generation. Issues are collected during generation and
+                          * returned in {@link SnapshotResult.issues}.
+                          *
+                          * @example
+                          * ```typescript
+                          * const issue: SnapshotIssue = {
+                          *   severity: 'error',
+                          *   code: 'CARDINALITY_VIOLATION',
+                          *   message: 'Derived min (0) is less than base min (1)',
+                          *   path: 'Patient.identifier',
+                          * };
+                          * ```
+                          */
+                         export declare interface SnapshotIssue {
+                             /** Severity level of the issue. */
+                             readonly severity: 'error' | 'warning' | 'information';
+                             /** Machine-readable issue code. */
+                             readonly code: SnapshotIssueCode;
+                             /** Human-readable description of the issue. */
+                             readonly message: string;
+                             /** Element path where the issue occurred (e.g., `'Patient.identifier'`). */
+                             readonly path?: string;
+                             /** Additional details for debugging. */
+                             readonly details?: string;
+                         }
+
+                         /**
+                          * Machine-readable issue codes for snapshot generation.
+                          *
+                          * Each code corresponds to a specific category of problem that can
+                          * occur during the snapshot generation process.
+                          */
+                         export declare type SnapshotIssueCode = 
+                         /** Circular dependency detected in profile chain. */
+                         'CIRCULAR_DEPENDENCY'
+                         /** Base StructureDefinition could not be loaded. */
+                         | 'BASE_NOT_FOUND'
+                         /** Base StructureDefinition exists but has no snapshot. */
+                         | 'BASE_MISSING_SNAPSHOT'
+                         /** Differential element was not consumed during generation. */
+                         | 'DIFFERENTIAL_NOT_CONSUMED'
+                         /** Cardinality constraint violation (min/max tightening rules). */
+                         | 'CARDINALITY_VIOLATION'
+                         /** Type constraint is incompatible with base types. */
+                         | 'TYPE_INCOMPATIBLE'
+                         /** Binding constraint violation (e.g., relaxing REQUIRED binding). */
+                         | 'BINDING_VIOLATION'
+                         /** Slicing-related error (compatibility, closed slicing, etc.). */
+                         | 'SLICING_ERROR'
+                         /** Differential path not found in base snapshot. */
+                         | 'PATH_NOT_FOUND'
+                         /** Generic invalid constraint (catch-all for other violations). */
+                         | 'INVALID_CONSTRAINT'
+                         /** Internal error in the generator (should not happen). */
+                         | 'INTERNAL_ERROR';
+
+                         /**
+                          * Result of snapshot generation.
+                          *
+                          * Contains the StructureDefinition with its populated snapshot, any issues
+                          * encountered during generation, and optionally a {@link CanonicalProfile}.
+                          *
+                          * @example
+                          * ```typescript
+                          * const result = await generator.generate(sd);
+                          * if (result.success) {
+                          *   console.log(`Generated ${result.structureDefinition.snapshot?.element.length} elements`);
+                          * } else {
+                          *   console.error('Errors:', result.issues.filter(i => i.severity === 'error'));
+                          * }
+                          * ```
+                          */
+                         export declare interface SnapshotResult {
+                             /** The StructureDefinition with populated snapshot. */
+                             readonly structureDefinition: StructureDefinition;
+                             /**
+                              * Optional {@link CanonicalProfile} if
+                              * {@link SnapshotGeneratorOptions.generateCanonical} was `true`.
+                              */
+                             readonly canonical?: CanonicalProfile;
+                             /** Issues encountered during generation (warnings + errors). */
+                             readonly issues: readonly SnapshotIssue[];
+                             /**
+                              * Whether generation completed successfully.
+                              *
+                              * `true` when no error-severity issues were recorded.
+                              * Warnings and informational issues do not affect this flag.
+                              */
+                             readonly success: boolean;
+                         }
+
+                         /**
+                          * Sort differential elements according to base snapshot order.
+                          *
+                          * Corresponds to HAPI's `sortDifferential()`. The algorithm:
+                          * 1. Build a tree from the differential elements (parent-child by path)
+                          * 2. Assign each node a base index via {@link findBaseIndex}
+                          * 3. Sort children at each level by base index
+                          * 4. Flatten the tree back to a linear list
+                          *
+                          * Elements not found in the base are placed at the end of their level
+                          * and an issue is recorded.
+                          *
+                          * @param differential - The differential elements to sort (not mutated).
+                          * @param baseSnapshot - The base snapshot providing the authoritative order.
+                          * @param issues - Issue collector for recording problems.
+                          * @returns A new array of elements in sorted order.
+                          */
+                         export declare function sortDifferential(differential: readonly ElementDefinition[], baseSnapshot: readonly ElementDefinition[], issues: SnapshotIssue[]): ElementDefinition[];
+
+                         /**
+                          * A definition of a FHIR structure — a resource, data type, or extension.
+                          *
+                          * StructureDefinition is the central metadata resource in FHIR. It defines:
+                          * - The shape of resources and data types (via snapshot/differential)
+                          * - Profile constraints (via derivation = 'constraint')
+                          * - Extension definitions (via kind = 'resource', type = 'Extension')
+                          *
+                          * This interface extends DomainResource and includes all fields defined
+                          * in the FHIR R4 specification.
+                          *
+                          * @see https://hl7.org/fhir/R4/structuredefinition.html
+                          */
+                         export declare interface StructureDefinition extends DomainResource {
+                             /** Resource type discriminator (1..1) */
+                             resourceType: 'StructureDefinition';
+                             /**
+                              * Canonical identifier for this structure definition, represented as a URI
+                              * (globally unique) (1..1)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.url
+                              */
+                             url: FhirUri;
+                             /**
+                              * Additional identifier for the structure definition (0..*)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.identifier
+                              */
+                             identifier?: Identifier[];
+                             /**
+                              * Business version of the structure definition (0..1)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.version
+                              */
+                             version?: FhirString;
+                             /**
+                              * Computer-readable name of the structure definition (1..1)
+                              *
+                              * Name should be usable as an identifier for the module by machine
+                              * processing applications such as code generation.
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.name
+                              */
+                             name: FhirString;
+                             /**
+                              * Human-readable name for the structure definition (0..1)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.title
+                              */
+                             title?: FhirString;
+                             /**
+                              * Publication status: draft | active | retired | unknown (1..1)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.status
+                              */
+                             status: PublicationStatus;
+                             /**
+                              * For testing purposes, not real usage (0..1)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.experimental
+                              */
+                             experimental?: FhirBoolean;
+                             /**
+                              * Date last changed (0..1)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.date
+                              */
+                             date?: FhirDateTime;
+                             /**
+                              * Name of the publisher (organization or individual) (0..1)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.publisher
+                              */
+                             publisher?: FhirString;
+                             /**
+                              * Contact details for the publisher (0..*)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.contact
+                              */
+                             contact?: ContactDetail[];
+                             /**
+                              * Natural language description of the structure definition (0..1)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.description
+                              */
+                             description?: FhirMarkdown;
+                             /**
+                              * The context that the content is intended to support (0..*)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.useContext
+                              */
+                             useContext?: UsageContext[];
+                             /**
+                              * Intended jurisdiction for structure definition (0..*)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.jurisdiction
+                              */
+                             jurisdiction?: CodeableConcept[];
+                             /**
+                              * Why this structure definition is defined (0..1)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.purpose
+                              */
+                             purpose?: FhirMarkdown;
+                             /**
+                              * Use and/or publishing restrictions (0..1)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.copyright
+                              */
+                             copyright?: FhirMarkdown;
+                             /**
+                              * Assist with indexing and finding (0..*)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.keyword
+                              */
+                             keyword?: Coding[];
+                             /**
+                              * FHIR Version this StructureDefinition targets (0..1)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.fhirVersion
+                              */
+                             fhirVersion?: FhirVersionCode;
+                             /**
+                              * External specification that the content is mapped to (0..*)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.mapping
+                              */
+                             mapping?: StructureDefinitionMapping[];
+                             /**
+                              * The kind of structure: primitive-type | complex-type | resource | logical (1..1)
+                              *
+                              * Determines the fundamental nature of the structure being defined.
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.kind
+                              */
+                             kind: StructureDefinitionKind;
+                             /**
+                              * Whether the structure is abstract (1..1)
+                              *
+                              * Abstract types cannot be instantiated directly. For example,
+                              * `DomainResource` is abstract — you cannot create a resource
+                              * with `resourceType: "DomainResource"`.
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.abstract
+                              */
+                             abstract: FhirBoolean;
+                             /**
+                              * If an extension, where it can be used in instances (0..*)
+                              *
+                              * Only meaningful when kind = 'resource' and type = 'Extension'.
+                              * Defines the contexts in which the extension can appear.
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.context
+                              */
+                             context?: StructureDefinitionContext[];
+                             /**
+                              * FHIRPath invariants — conditions that must be true for the
+                              * extension to be valid in a given context (0..*)
+                              *
+                              * Only meaningful when kind = 'resource' and type = 'Extension'.
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.contextInvariant
+                              */
+                             contextInvariant?: FhirString[];
+                             /**
+                              * Type defined or constrained by this structure (1..1)
+                              *
+                              * For base definitions (derivation = 'specialization'), this is the
+                              * type being defined (e.g., 'Patient', 'Observation').
+                              * For profiles (derivation = 'constraint'), this is the type being
+                              * constrained (must match the type of the base definition).
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.type
+                              */
+                             type: FhirUri;
+                             /**
+                              * Definition that this type is constrained/specialized from (0..1)
+                              *
+                              * The canonical URL of the base StructureDefinition. This forms the
+                              * inheritance chain used in snapshot generation.
+                              * - For specializations: points to the parent type
+                              * - For constraints: points to the profile being constrained
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.baseDefinition
+                              */
+                             baseDefinition?: FhirCanonical;
+                             /**
+                              * specialization | constraint (0..1)
+                              *
+                              * - `specialization`: defines a new type (e.g., Patient specializes DomainResource)
+                              * - `constraint`: constrains an existing type (e.g., USCorePatient constrains Patient)
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.derivation
+                              */
+                             derivation?: TypeDerivationRule;
+                             /**
+                              * Snapshot view of the structure (0..1)
+                              *
+                              * Contains the complete, flattened element tree with all constraints
+                              * from the inheritance chain resolved. Generated by the snapshot
+                              * generation algorithm (fhir-profile module).
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.snapshot
+                              */
+                             snapshot?: StructureDefinitionSnapshot;
+                             /**
+                              * Differential constraints of the structure (0..1)
+                              *
+                              * Contains only the constraints that differ from the base definition.
+                              * This is the authoring format — profiles are typically written as
+                              * differentials to avoid repeating base constraints.
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.differential
+                              */
+                             differential?: StructureDefinitionDifferential;
+                         }
+
+                         /**
+                          * Identifies the types of resource or data type elements to which the
+                          * extension can be applied. Only relevant when kind = 'resource' and
+                          * type = 'Extension'.
+                          * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.context
+                          */
+                         export declare interface StructureDefinitionContext extends BackboneElement {
+                             /** fhirpath | element | extension (1..1) */
+                             type: ExtensionContextType;
+                             /** Where the extension can be used in instances (1..1) */
+                             expression: FhirString;
+                         }
+
+                         /**
+                          * A differential view of the structure, containing only the constraints
+                          * that differ from the base definition. This is the compact authoring
+                          * format used when creating profiles.
+                          * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.differential
+                          */
+                         export declare interface StructureDefinitionDifferential extends BackboneElement {
+                             /**
+                              * Definition of elements in the resource (if no StructureDefinition) (1..*)
+                              *
+                              * The differential contains only the constraints that differ from the base
+                              * profile. It MUST NOT be used directly for semantic interpretation — it
+                              * must first be expanded into a snapshot via snapshot generation.
+                              */
+                             element: ElementDefinition[];
+                         }
+
+                         /**
+                          * The kind of structure being defined by a StructureDefinition.
+                          * @see https://hl7.org/fhir/R4/valueset-structure-definition-kind.html
+                          */
+                         export declare type StructureDefinitionKind = 'primitive-type' | 'complex-type' | 'resource' | 'logical';
+
+                         /**
+                          * Pluggable strategy for loading StructureDefinitions from an external source.
+                          *
+                          * Implementations include:
+                          * - `MemoryLoader` — loads from an in-memory map (for testing / preloaded data)
+                          * - `FileSystemLoader` — loads from local JSON files
+                          * - `CompositeLoader` — chains multiple loaders (fallback pattern)
+                          *
+                          * Conceptually equivalent to HAPI's `IValidationSupport` implementations.
+                          */
+                         export declare interface StructureDefinitionLoader {
+                             /**
+                              * Attempt to load a StructureDefinition by canonical URL.
+                              *
+                              * @param url - Canonical URL (without `|version` — version is stripped
+                              *              by the caller before delegation)
+                              * @returns The loaded StructureDefinition, or `null` if this loader
+                              *          cannot resolve the URL (allows fallback to next loader)
+                              * @throws {@link LoaderError} on I/O or parse failures
+                                  */
+                              load(url: string): Promise<StructureDefinition | null>;
+                              /**
+                               * Quick check whether this loader is likely able to resolve the URL.
+                               *
+                               * This is a hint — returning `true` does not guarantee `load()` will
+                               * succeed. Returning `false` allows the composite loader to skip this
+                               * source entirely.
+                               *
+                               * @param url - Canonical URL to check
+                               */
+                              canLoad(url: string): boolean;
+                              /**
+                               * Human-readable identifier for the loader source.
+                               *
+                               * Used in error messages and diagnostics.
+                               *
+                               * @returns Source type label (e.g., `'memory'`, `'filesystem'`, `'http'`)
+                               */
+                              getSourceType(): string;
+                             }
+
+                             /**
+                              * A mapping to an external specification that the structure conforms to.
+                              * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.mapping
+                              */
+                             export declare interface StructureDefinitionMapping extends BackboneElement {
+                                 /** Internal id when this mapping is used (1..1) */
+                                 identity: FhirId;
+                                 /** Identifies what this mapping refers to (0..1) */
+                                 uri?: FhirUri;
+                                 /** Names what this mapping refers to (0..1) */
+                                 name?: FhirString;
+                                 /** Versions, issues, scope limitations, etc. (0..1) */
+                                 comment?: FhirString;
+                             }
+
+                             /**
+                              * In-memory registry for StructureDefinitions.
+                              *
+                              * Storage strategy:
+                              * - **Primary map**: keyed by `url|version` (exact match)
+                              * - **Latest map**: keyed by bare `url` → points to the most recently
+                              *   registered version (for unversioned lookups)
+                              *
+                              * When a lookup uses a bare URL (no `|version`), the latest map is consulted.
+                              * When a lookup uses `url|version`, the primary map is used for exact match.
+                              */
+                             declare class StructureDefinitionRegistry {
+                                 /** Primary storage: `url|version` → StructureDefinition */
+                                 private readonly _entries;
+                                 /** Latest-version index: bare `url` → `url|version` key in _entries */
+                                 private readonly _latestIndex;
+                                 /** Statistics counters */
+                                 private _queryCount;
+                                 private _hitCount;
+                                 /**
+                                  * Register a StructureDefinition.
+                                  *
+                                  * Validates that the definition has a `url` field. If a definition with
+                                  * the same URL (and version) already exists, it is silently replaced.
+                                  *
+                                  * @param sd - The StructureDefinition to register
+                                  * @throws {@link InvalidStructureDefinitionError} if `sd.url` is missing
+                                      */
+                                  register(sd: StructureDefinition): void;
+                                  /**
+                                   * Remove a StructureDefinition by canonical URL.
+                                   *
+                                   * @param urlWithVersion - Canonical URL (with optional `|version`)
+                                   * @returns `true` if a definition was removed, `false` if not found
+                                   */
+                                  delete(urlWithVersion: string): boolean;
+                                  /**
+                                   * Remove all entries and reset statistics.
+                                   */
+                                  clear(): void;
+                                  /**
+                                   * Retrieve a StructureDefinition by canonical URL.
+                                   *
+                                   * - If `urlWithVersion` contains `|version`, performs exact match.
+                                   * - If no version, returns the latest registered version.
+                                   *
+                                   * @param urlWithVersion - Canonical URL (with optional `|version`)
+                                   * @returns The StructureDefinition, or `undefined` if not found
+                                   */
+                                  get(urlWithVersion: string): StructureDefinition | undefined;
+                                  /**
+                                   * Check whether a StructureDefinition is registered.
+                                   *
+                                   * @param urlWithVersion - Canonical URL (with optional `|version`)
+                                   */
+                                  has(urlWithVersion: string): boolean;
+                                  /**
+                                   * Total number of registered StructureDefinitions.
+                                   */
+                                  get size(): number;
+                                  /**
+                                   * Return all registered canonical URLs (including version suffixes).
+                                   */
+                                  getAllKeys(): string[];
+                                  /**
+                                   * Return all registered bare URLs (without version suffixes).
+                                   */
+                                  getAllUrls(): string[];
+                                  /**
+                                   * Total number of `get()` calls.
+                                   */
+                                  get queryCount(): number;
+                                  /**
+                                   * Number of `get()` calls that returned a result (cache hits).
+                                   */
+                                  get hitCount(): number;
+                                  /**
+                                   * Number of `get()` calls that returned `undefined` (cache misses).
+                                   */
+                                  get missCount(): number;
+                                  /**
+                                   * Cache hit ratio (0–1). Returns 0 if no queries have been made.
+                                   */
+                                  get hitRate(): number;
+                                 }
+
+                                 /**
+                                  * A snapshot view of the structure, containing all element definitions
+                                  * with their complete constraint information resolved from the
+                                  * inheritance chain.
+                                  * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.snapshot
+                                  */
+                                 export declare interface StructureDefinitionSnapshot extends BackboneElement {
+                                     /**
+                                      * Definition of elements in the resource (if no StructureDefinition) (1..*)
+                                      *
+                                      * The snapshot contains the complete, flattened list of all ElementDefinition
+                                      * entries with all constraints from the inheritance chain fully resolved.
+                                      * This is the "semantic truth" used for validation and interpretation.
+                                      */
+                                     element: ElementDefinition[];
+                                 }
+
+                                 /**
+                                  * Main validator class for structural validation of FHIR resources.
+                                  *
+                                  * Validates a resource instance against a {@link CanonicalProfile} by
+                                  * orchestrating all individual validation rules (cardinality, type,
+                                  * fixed/pattern, reference, slicing).
+                                  *
+                                  * @example
+                                  * ```typescript
+                                  * const validator = new StructureValidator();
+                                  *
+                                  * // Validate with an explicit profile
+                                  * const result = validator.validate(patient, patientProfile);
+                                  *
+                                  * if (!result.valid) {
+                                  *   for (const issue of result.issues) {
+                                  *     console.error(`${issue.severity}: ${issue.message}`);
+                                  *   }
+                                  * }
+                                  * ```
+                                  */
+                                 export declare class StructureValidator {
+                                     private readonly options;
+                                     constructor(options?: ValidationOptions);
+                                     /**
+                                      * Validate a resource instance against a CanonicalProfile.
+                                      *
+                                      * @param resource - The FHIR resource to validate.
+                                      * @param profile - The CanonicalProfile to validate against.
+                                      * @param options - Optional per-call overrides for validation options.
+                                      * @returns The validation result with all issues.
+                                      * @throws {@link ProfileNotFoundError} if profile is undefined.
+                                          * @throws {@link ValidationFailedError} if failFast is enabled and an error is found.
+                                              */
+                                          validate(resource: Resource, profile: CanonicalProfile, options?: ValidationOptions): ValidationResult;
+                                          /**
+                                           * Check that the resource type matches the profile type.
+                                           */
+                                          private validateResourceType;
+                                          /**
+                                           * Validate all elements in the profile against the resource.
+                                           */
+                                          private validateElements;
+                                          /**
+                                           * Get all named slice elements for a slicing root path.
+                                           */
+                                          private getSliceElements;
+                                          /**
+                                           * Check if failFast is enabled and there are errors; if so, throw.
+                                           */
+                                          private checkFailFast;
+                                      }
+
+                                      /**
+                                       * Get the last segment (tail) of a path.
+                                       *
+                                       * @example
+                                       * tailSegment('Patient.name.given')  // 'given'
+                                       * tailSegment('Patient')             // 'Patient'
+                                       */
+                                      export declare function tailSegment(path: string): string;
+
+                                      /**
+                                       * Cursor-based scope for base-driven traversal.
+                                       *
+                                       * Used by the element merger (`processPaths` equivalent) to define
+                                       * the current working range within a list of ElementDefinitions.
+                                       * Both `start` and `end` are inclusive indices.
+                                       *
+                                       * This mirrors HAPI's `baseCursor/baseLimit` and `diffCursor/diffLimit`
+                                       * parameter pairs in `processPaths()`.
+                                       *
+                                       * @example
+                                       * ```typescript
+                                       * // Scope covering elements[2] through elements[5]
+                                       * const scope: TraversalScope = {
+                                       *   elements: baseSnapshot.element,
+                                       *   start: 2,
+                                       *   end: 5,
+                                       * };
+                                       * ```
+                                       *
+                                       * @internal Used by {@link ElementMerger}.
+                                       */
+                                      export declare interface TraversalScope {
+                                          /** The element list being traversed. */
+                                          readonly elements: readonly ElementDefinition[];
+                                          /** Start index (inclusive). */
+                                          readonly start: number;
+                                          /** End index (inclusive). */
+                                          readonly end: number;
+                                      }
+
+                                      /**
+                                       * A resolved type constraint on a canonical element.
+                                       *
+                                       * Corresponds to a simplified, pre-validated version of
+                                       * `ElementDefinition.type` from the FHIR spec.
+                                       */
+                                      export declare interface TypeConstraint {
+                                          /**
+                                           * The data type or resource name (e.g., `string`, `Reference`, `Patient`).
+                                           *
+                                           * Unlike `ElementDefinitionType.code` (which is a URI), this is the
+                                           * resolved short name used for runtime dispatch.
+                                           */
+                                          code: string;
+                                          /**
+                                           * Profiles that the type must conform to (resolved canonical URLs).
+                                           *
+                                           * Corresponds to `ElementDefinitionType.profile`.
+                                           */
+                                          profiles?: string[];
+                                          /**
+                                           * For Reference/canonical types, profiles that the target must conform to.
+                                           *
+                                           * Corresponds to `ElementDefinitionType.targetProfile`.
+                                           */
+                                          targetProfiles?: string[];
+                                      }
+
+                                      /**
+                                       * Whether a StructureDefinition is a specialization or a constraint.
+                                       * - `specialization`: defines a new type (e.g., Patient specializes DomainResource)
+                                       * - `constraint`: constrains an existing type (e.g., USCorePatient constrains Patient)
+                                       * @see https://hl7.org/fhir/R4/valueset-type-derivation-rule.html
+                                       */
+                                      export declare type TypeDerivationRule = 'specialization' | 'constraint';
+
+                                      /**
+                                       * A value paired with its FHIR type identifier.
+                                       * This is the fundamental unit of data flowing through the FHIRPath engine.
+                                       *
+                                       * @example
+                                       * ```ts
+                                       * const tv: TypedValue = { type: PropertyType.string, value: 'hello' };
+                                       * ```
+                                       */
+                                      declare interface TypedValue {
+                                          readonly type: string;
+                                          readonly value: unknown;
+                                      }
+
+                                      /**
+                                       * Thrown when differential elements remain unconsumed after snapshot
+                                       * generation completes.
+                                       *
+                                       * This indicates that the algorithm could not find a matching base
+                                       * element for one or more differential entries. Common causes:
+                                       * - Incorrect path in differential
+                                       * - Slicing mismatch
+                                       * - Unsupported constraint pattern
+                                       *
+                                       * HAPI detects this via the `GENERATED_IN_SNAPSHOT` marker pattern.
+                                       *
+                                       * Only thrown when {@link SnapshotGeneratorOptions.throwOnError} is `true`.
+                                       * Otherwise, each unconsumed element is recorded as an issue.
+                                       *
+                                       * @example
+                                       * ```typescript
+                                       * throw new UnconsumedDifferentialError([
+                                       *   'Patient.nonExistentField',
+                                       *   'Patient.identifier:BadSlice',
+                                       * ]);
+                                       * ```
+                                       */
+                                      export declare class UnconsumedDifferentialError extends ProfileError {
+                                          readonly name = "UnconsumedDifferentialError";
+                                          /** Paths of the unconsumed differential elements. */
+                                          readonly unconsumedPaths: readonly string[];
+                                          constructor(unconsumedPaths: string[]);
+                                      }
+
+                                      /**
+                                       * Specifies clinical/business/etc. context in which a conformance
+                                       * artifact is applicable.
+                                       * @see https://hl7.org/fhir/R4/metadatatypes.html#UsageContext
+                                       */
+                                      export declare interface UsageContext extends Element {
+                                          /** Type of context being specified (1..1) */
+                                          code: Coding;
+                                          /**
+                                           * Value that defines the context (1..1).
+                                           *
+                                           * Choice type [x] — the actual property name in JSON will be
+                                           * `valueCodeableConcept`, `valueQuantity`, `valueRange`, or `valueReference`.
+                                           * Allows: CodeableConcept | Quantity | Range | Reference.
+                                           *
+                                           * Stage-1: represented as `unknown`; fhir-parser will handle
+                                           * concrete dispatch in Phase 2.
+                                           * @see https://hl7.org/fhir/R4/metadatatypes-definitions.html#UsageContext.value_x_
+                                           */
+                                          value?: unknown;
+                                      }
+
+                                      /**
+                                       * Validate that snapshot elements are in correct order.
+                                       *
+                                       * Rules:
+                                       * - Parent elements must appear before their children
+                                       * - Slice elements must appear after their slicing root
+                                       * - No duplicate paths (unless sliced)
+                                       *
+                                       * @param snapshot - The snapshot elements to validate.
+                                       * @param issues - Issue collector for recording problems.
+                                       * @returns `true` if order is valid, `false` if any violations found.
+                                       */
+                                      export declare function validateElementOrder(snapshot: readonly ElementDefinition[], issues: SnapshotIssue[]): boolean;
+
+                                      /**
+                                       * Validate that a differential slicing definition is compatible with
+                                       * the base slicing definition.
+                                       *
+                                       * Rules:
+                                       * - Discriminators must match (same type and path, in same order)
+                                       * - `ordered` cannot change from `true` to `false`
+                                       * - `rules` cannot relax from `closed` to `open`/`openAtEnd`
+                                       *
+                                       * @param baseSlicing - The base element's slicing definition.
+                                       * @param diffSlicing - The differential element's slicing definition.
+                                       * @param issues - Issue collector for recording incompatibilities.
+                                       * @param path - Element path for issue reporting.
+                                       * @returns `true` if compatible, `false` if incompatible.
+                                       */
+                                      export declare function validateSlicingCompatibility(baseSlicing: ElementDefinitionSlicing, diffSlicing: ElementDefinitionSlicing, issues: SnapshotIssue[], path: string): boolean;
+
+                                      /**
+                                       * Thrown when validation fails and {@link ValidationOptions.failFast} is enabled.
+                                       *
+                                       * Contains the issues accumulated up to the point of failure. This allows
+                                       * callers to inspect the first error(s) that triggered the failure.
+                                       *
+                                       * @example
+                                       * ```typescript
+                                       * try {
+                                       *   await validator.validate(resource, { failFast: true });
+                                       * } catch (err) {
+                                       *   if (err instanceof ValidationFailedError) {
+                                       *     console.error('First error:', err.issues[0].message);
+                                       *   }
+                                       * }
+                                       * ```
+                                       */
+                                      export declare class ValidationFailedError extends ValidatorError {
+                                          readonly name = "ValidationFailedError";
+                                          /** The validation issues accumulated before failure. */
+                                          readonly issues: readonly ValidationIssue[];
+                                          constructor(message: string, issues: readonly ValidationIssue[], cause?: Error);
+                                      }
+
+                                      /**
+                                       * A single issue encountered during validation.
+                                       *
+                                       * Mirrors the concept of FHIR OperationOutcome.issue but scoped to
+                                       * structural validation. Issues are collected during validation and
+                                       * returned in {@link ValidationResult.issues}.
+                                       *
+                                       * @example
+                                       * ```typescript
+                                       * const issue: ValidationIssue = {
+                                       *   severity: 'error',
+                                       *   code: 'CARDINALITY_MIN_VIOLATION',
+                                       *   message: "Element 'Patient.name' requires at least 1 value(s), but found 0",
+                                       *   path: 'Patient.name',
+                                       *   expression: 'Patient.name',
+                                       * };
+                                       * ```
+                                       */
+                                      export declare interface ValidationIssue {
+                                          /** Severity level of the issue. */
+                                          readonly severity: 'error' | 'warning' | 'information';
+                                          /** Machine-readable issue code. */
+                                          readonly code: ValidationIssueCode;
+                                          /** Human-readable description of the issue. */
+                                          readonly message: string;
+                                          /**
+                                           * Element path where the issue occurred (dot-notation).
+                                           *
+                                           * @example `'Patient.name'`, `'Observation.value[x]'`
+                                           */
+                                          readonly path?: string;
+                                          /**
+                                           * FHIRPath expression pointing to the problematic element.
+                                           *
+                                           * Typically identical to `path` for structural validation, but may
+                                           * differ for sliced elements or choice types.
+                                           *
+                                           * @example `'Patient.identifier.where(system="urn:oid:1.2.3")'`
+                                           */
+                                          readonly expression?: string;
+                                          /** Additional diagnostic information for debugging. */
+                                          readonly diagnostics?: string;
+                                      }
+
+                                      /**
+                                       * Machine-readable issue codes for structural validation.
+                                       *
+                                       * Each code corresponds to a specific category of validation failure.
+                                       * Codes are designed to be stable across versions for programmatic
+                                       * consumption.
+                                       */
+                                      export declare type ValidationIssueCode = 
+                                      /** Element has fewer values than the minimum cardinality. */
+                                      'CARDINALITY_MIN_VIOLATION'
+                                      /** Element has more values than the maximum cardinality. */
+                                      | 'CARDINALITY_MAX_VIOLATION'
+                                      /** Value type does not match any of the allowed types. */
+                                      | 'TYPE_MISMATCH'
+                                      /** Choice type field uses an unsupported type suffix. */
+                                      | 'INVALID_CHOICE_TYPE'
+                                      /** A required element (min ≥ 1) is missing from the resource. */
+                                      | 'REQUIRED_ELEMENT_MISSING'
+                                      /** Value does not match the fixed value constraint. */
+                                      | 'FIXED_VALUE_MISMATCH'
+                                      /** Value does not match the pattern value constraint (partial match). */
+                                      | 'PATTERN_VALUE_MISMATCH'
+                                      /** Value does not match any slice discriminator in a closed slicing. */
+                                      | 'SLICING_NO_MATCH'
+                                      /** Slice cardinality violation (too few or too many values in a slice). */
+                                      | 'SLICING_CARDINALITY_VIOLATION'
+                                      /** Ordered slicing constraint violated (values out of order). */
+                                      | 'SLICING_ORDER_VIOLATION'
+                                      /** Reference target does not match any of the allowed target profiles. */
+                                      | 'REFERENCE_TARGET_MISMATCH'
+                                      /** The specified profile could not be found or loaded. */
+                                      | 'PROFILE_NOT_FOUND'
+                                      /** Resource type does not match the profile's type. */
+                                      | 'RESOURCE_TYPE_MISMATCH'
+                                      /** Resource contains an element not defined in the profile. */
+                                      | 'UNKNOWN_ELEMENT'
+                                      /** FHIRPath invariant evaluation is not yet supported (skipped). */
+                                      | 'INVARIANT_NOT_EVALUATED'
+                                      /** FHIRPath invariant constraint evaluated to false. */
+                                      | 'INVARIANT_VIOLATION'
+                                      /** FHIRPath invariant expression failed to evaluate (runtime error). */
+                                      | 'INVARIANT_EVALUATION_ERROR'
+                                      /** Internal validator error (should not happen). */
+                                      | 'INTERNAL_ERROR';
+
+                                      /**
+                                       * Configuration options for structural validation.
+                                       *
+                                       * @example
+                                       * ```typescript
+                                       * const options: ValidationOptions = {
+                                       *   profileUrl: 'http://hl7.org/fhir/StructureDefinition/Patient',
+                                       *   validateSlicing: true,
+                                       *   validateFixed: true,
+                                       *   failFast: false,
+                                       * };
+                                       * ```
+                                       */
+                                      export declare interface ValidationOptions {
+                                          /**
+                                           * Profile URL to validate against.
+                                           *
+                                           * If not specified, the validator will attempt to extract the profile
+                                           * from `resource.meta.profile[0]`. If neither is available, the
+                                           * validator falls back to the base resource type
+                                           * (e.g., `http://hl7.org/fhir/StructureDefinition/{resourceType}`).
+                                           */
+                                          readonly profileUrl?: string;
+                                          /**
+                                           * Whether to validate slicing constraints.
+                                           *
+                                           * When `true` (default), the validator checks that array elements
+                                           * match their declared slices and that closed slicing rules are
+                                           * respected.
+                                           *
+                                           * @default true
+                                           */
+                                          readonly validateSlicing?: boolean;
+                                          /**
+                                           * Whether to validate fixed and pattern value constraints.
+                                           *
+                                           * When `true` (default), the validator checks that element values
+                                           * match any `fixed[x]` or `pattern[x]` constraints declared in
+                                           * the profile.
+                                           *
+                                           * @default true
+                                           */
+                                          readonly validateFixed?: boolean;
+                                          /**
+                                           * Maximum depth for nested validation.
+                                           *
+                                           * Prevents runaway recursion in deeply nested or pathological
+                                           * resource structures.
+                                           *
+                                           * @default 50
+                                           */
+                                          readonly maxDepth?: number;
+                                          /**
+                                           * Whether to stop on the first error or collect all issues.
+                                           *
+                                           * When `true`, the validator throws a {@link ValidationFailedError}
+                                           * on the first error-severity issue. When `false` (default), all
+                                           * issues are collected and returned in the result.
+                                           *
+                                           * @default false
+                                           */
+                                          readonly failFast?: boolean;
+                                          /**
+                                           * Whether to skip FHIRPath invariant validation.
+                                           *
+                                           * When `true`, constraint expressions from the profile are not
+                                           * evaluated. Useful for performance or when FHIRPath evaluation
+                                           * is not needed.
+                                           *
+                                           * @default false
+                                           */
+                                          readonly skipInvariants?: boolean;
+                                      }
+
+                                      /**
+                                       * Result of structural validation.
+                                       *
+                                       * Contains the overall validity status, the validated resource, and
+                                       * all issues encountered during validation.
+                                       *
+                                       * @example
+                                       * ```typescript
+                                       * const result = await validator.validate(patient);
+                                       * if (result.valid) {
+                                       *   console.log('Resource is valid');
+                                       * } else {
+                                       *   for (const issue of result.issues) {
+                                       *     console.error(`${issue.severity}: ${issue.message} (at ${issue.path})`);
+                                       *   }
+                                       * }
+                                       * ```
+                                       */
+                                      export declare interface ValidationResult {
+                                          /**
+                                           * Whether the resource is valid.
+                                           *
+                                           * `true` when no error-severity issues were recorded.
+                                           * Warnings and informational issues do not affect this flag.
+                                           */
+                                          readonly valid: boolean;
+                                          /** The resource that was validated. */
+                                          readonly resource: Resource;
+                                          /** The profile that was validated against. */
+                                          readonly profileUrl: string;
+                                          /** The resolved CanonicalProfile used for validation. */
+                                          readonly profile: CanonicalProfile;
+                                          /** Issues encountered during validation (errors + warnings + info). */
+                                          readonly issues: readonly ValidationIssue[];
+                                      }
+
+                                      /**
+                                       * Base error class for all fhir-validator failures.
+                                       *
+                                       * Provides a stable `name` property and preserves the original `cause`
+                                       * when wrapping lower-level errors.
+                                       *
+                                       * @example
+                                       * ```typescript
+                                       * try {
+                                       *   await validator.validate(resource);
+                                       * } catch (err) {
+                                       *   if (err instanceof ValidatorError) {
+                                       *     // Handle any validator-related error
+                                       *   }
+                                       * }
+                                       * ```
+                                       */
+                                      declare class ValidatorError extends Error {
+                                          readonly name: string;
+                                          constructor(message: string, options?: ErrorOptions);
+                                      }
+
+                                      export { }