fhir-runtime 0.2.0

package/dist/lib/context/bundle-loader.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Bundle Loader — Phase 7
+ *
+ * Loads FHIR Bundle JSON files containing StructureDefinition entries
+ * and converts them to CanonicalProfile[] for downstream consumption
+ * by Phase 8's schema generation pipeline.
+ *
+ * Two data paths exist in MedXAI:
+ *
+ * ```
+ * Path A — Stage-1 Validation (unchanged):
+ *   core-definitions/*.json (73 files)
+ *     → loadAllCoreDefinitions()
+ *     → FhirContextImpl (runtime validation)
+ *
+ * Path B — Stage-2 Schema Generation (this module):
+ *   spec/fhir/r4/profiles-*.json (complete bundles)
+ *     → BundleLoader
+ *     → StructureDefinitionRegistry (Phase 8)
+ *     → TableSchemaBuilder (Phase 8)
+ * ```
+ *
+ * @module fhir-context
+ */
+import type { CanonicalProfile } from '../model/canonical-profile.js';
+import type { StructureDefinitionKind } from '../model/primitives.js';
+import type { ParseIssue } from '../parser/parse-error.js';
+/**
+ * Options for filtering which StructureDefinitions to load from a bundle.
+ */
+export 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 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;
+    };
+}
+/**
+ * Describes a single error encountered while loading a StructureDefinition.
+ */
+export 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[];
+}
+/**
+ * Minimal Bundle shape for type-safe access.
+ */
+interface BundleShape {
+    resourceType: string;
+    entry?: Array<{
+        resource?: Record<string, unknown>;
+    }>;
+}
+/**
+ * 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 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 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;
+export {};
+//# sourceMappingURL=bundle-loader.d.ts.map

package/dist/lib/context/bundle-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-loader.d.ts","sourceRoot":"","sources":["../../../src/context/bundle-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAM3D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,UAAU,CAAC,EAAE,uBAAuB,GAAG,uBAAuB,EAAE,CAAC;IAEjE,uEAAuE;IACvE,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAE7B,4DAA4D;IAC5D,MAAM,EAAE,eAAe,EAAE,CAAC;IAE1B,0BAA0B;IAC1B,KAAK,EAAE;QACL,4DAA4D;QAC5D,KAAK,EAAE,MAAM,CAAC;QACd,6DAA6D;QAC7D,MAAM,EAAE,MAAM,CAAC;QACf,sDAAsD;QACtD,OAAO,EAAE,MAAM,CAAC;QAChB,kCAAkC;QAClC,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ,+BAA+B;IAC/B,KAAK,EAAE,KAAK,CAAC;IACb,uDAAuD;IACvD,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CACrC;AAMD;;GAEG;AACH,UAAU,WAAW;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,CAAC,CAAC;CACJ;AAoED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,gBAAgB,CA+ClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,gBAAgB,CAIlB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EAAE,EACnB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,gBAAgB,CAyBlB"}

package/dist/lib/context/core-definitions/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * fhir-context — Core Definitions Index
+ *
+ * Provides the list of core FHIR R4 StructureDefinition filenames
+ * and a utility to load them from the `core-definitions/` directory.
+ *
+ * These definitions are extracted from the official FHIR R4 v4.0.1
+ * specification (`profiles-resources.json` and `profiles-types.json`).
+ *
+ * @module fhir-context
+ */
+import type { StructureDefinition } from '../../model/index.js';
+/**
+ * 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"];
+/**
+ * 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"];
+/**
+ * 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"];
+/**
+ * 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"];
+/**
+ * All core definition filenames in dependency order:
+ * base → primitives → complex types → resources.
+ */
+export declare const ALL_CORE_DEFINITIONS: readonly string[];
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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 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>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/context/core-definitions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/context/core-definitions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAQhE;;;GAGG;AACH,eAAO,MAAM,cAAc,oFAMjB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,eAAe,wNAKlB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,aAAa,sTAMhB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,cAAc,uWAMjB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAKjD,CAAC;AAMF;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAOpE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,mBAAmB,CA2BrB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,mBAAmB,CAAC,CA2B9B;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAU3C"}

package/dist/lib/context/errors.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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);
+}
+/**
+ * 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[]);
+}
+/**
+ * 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[]);
+}
+/**
+ * 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);
+}
+/**
+ * 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);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/context/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/context/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAkB,IAAI,EAAE,MAAM,CAAkB;gBAEpC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAKpD;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;IACrD,SAAkB,IAAI,2BAA2B;IAEjD,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;gBAE7B,GAAG,EAAE,MAAM,EAAE,YAAY,GAAE,MAAM,EAAO;CASrD;AAMD;;;;;;;;;;;;GAYG;AACH,qBAAa,uBAAwB,SAAQ,YAAY;IACvD,SAAkB,IAAI,6BAA6B;IAEnD,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;gBAEtB,KAAK,EAAE,MAAM,EAAE;CAK5B;AAMD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,WAAY,SAAQ,YAAY;IAC3C,SAAkB,IAAI,iBAAiB;IAEvC,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAQ3D;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,+BAAgC,SAAQ,YAAY;IAC/D,SAAkB,IAAI,qCAAqC;IAE3D,uDAAuD;IACvD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;gBAErB,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM;CAKzC"}

package/dist/lib/context/fhir-context.d.ts

@@ -0,0 +1,72 @@
+/**
+ * fhir-context — FhirContextImpl
+ *
+ * Concrete implementation of the {@link FhirContext} interface.
+ * Integrates the registry, loaders, and inheritance resolver into
+ * a single cohesive entry point.
+ *
+ * Conceptual mapping:
+ * - HAPI `FhirContext` → this class
+ * - HAPI `IValidationSupport` → loader delegation
+ * - HAPI `ValidationSupportChain` → CompositeLoader
+ *
+ * @module fhir-context
+ */
+import type { StructureDefinition, CanonicalProfile } from '../model/index.js';
+import type { FhirContext, FhirContextOptions, ContextStatistics } from './types.js';
+import { StructureDefinitionRegistry } from './registry.js';
+import { InheritanceChainResolver } from './inheritance-resolver.js';
+/**
+ * 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;
+}
+//# sourceMappingURL=fhir-context.d.ts.map

package/dist/lib/context/fhir-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fhir-context.d.ts","sourceRoot":"","sources":["../../../src/context/fhir-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,2BAA2B,EAAqB,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAYrE;;;;;;;;;;;;;;GAcG;AACH,qBAAa,eAAgB,YAAW,WAAW;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuC;IACnE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAuC;IAC1E,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,EAAE,kBAAkB;IAuBjC,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAgCxE,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAKpE,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKtC,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAO7D,2BAA2B,CAAC,EAAE,EAAE,mBAAmB,GAAG,IAAI;IAWpD,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAY7C,aAAa,IAAI,iBAAiB;IAIlC,wBAAwB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAYzD,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAK5D,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAKvC,OAAO,IAAI,IAAI;IAkBf;;OAEG;IACH,OAAO,CAAC,4BAA4B;IASpC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;OAEG;IACH,IAAI,QAAQ,IAAI,2BAA2B,CAE1C;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,wBAAwB,CAEvC;CACF"}

package/dist/lib/context/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * fhir-context — Public API Barrel Exports
+ *
+ * Re-exports all public types, classes, and functions from the
+ * context module. Internal implementation details (registry,
+ * resolver) are NOT re-exported here.
+ *
+ * @module fhir-context
+ */
+export type { FhirContext, FhirContextOptions, StructureDefinitionLoader, LoaderOptions, ContextStatistics, } from './types.js';
+export { createEmptyStatistics } from './types.js';
+export { FhirContextImpl } from './fhir-context.js';
+export { MemoryLoader } from './loaders/memory-loader.js';
+export { FileSystemLoader } from './loaders/file-loader.js';
+export { CompositeLoader } from './loaders/composite-loader.js';
+export { ContextError, ResourceNotFoundError, CircularDependencyError, LoaderError, InvalidStructureDefinitionError, } from './errors.js';
+export type { BundleLoadOptions, BundleLoadResult, BundleLoadError, } from './bundle-loader.js';
+export { loadBundleFromObject, loadBundleFromFile, loadBundlesFromFiles, } from './bundle-loader.js';
+export { extractInnerTypes, buildTypeName, isBackboneElementType, } from './inner-type-extractor.js';
+export { BASE_RESOURCES, PRIMITIVE_TYPES, COMPLEX_TYPES, CORE_RESOURCES, ALL_CORE_DEFINITIONS, loadAllCoreDefinitions, loadCoreDefinition, loadCoreDefinitionSync, getCoreDefinitionsDir, } from './core-definitions/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,yBAAyB,EACzB,aAAa,EACb,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGnD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAGhE,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,uBAAuB,EACvB,WAAW,EACX,+BAA+B,GAChC,MAAM,aAAa,CAAC;AAGrB,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC"}

package/dist/lib/context/inheritance-resolver.d.ts

@@ -0,0 +1,98 @@
+/**
+ * fhir-context — Inheritance Chain Resolver
+ *
+ * Resolves the `baseDefinition` inheritance chain for a FHIR
+ * StructureDefinition, walking from a child profile up to the root
+ * resource type (e.g., `Resource`).
+ *
+ * Features:
+ * - Recursive resolution with on-demand loading
+ * - Circular dependency detection via an "in-flight" Set
+ * - Resolved chain caching with explicit invalidation
+ *
+ * @module fhir-context
+ */
+import type { StructureDefinition } from '../model/index.js';
+/**
+ * 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.
+ */
+export interface DefinitionProvider {
+    /**
+     * Load a StructureDefinition by canonical URL.
+     *
+     * Must throw {@link ResourceNotFoundError} if the URL cannot be resolved.
+     */
+    loadStructureDefinition(url: string): Promise<StructureDefinition>;
+}
+/**
+ * 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']
+ * ```
+ */
+export 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;
+}
+//# sourceMappingURL=inheritance-resolver.d.ts.map

package/dist/lib/context/inheritance-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inheritance-resolver.d.ts","sourceRoot":"","sources":["../../../src/context/inheritance-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAO7D;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACpE;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAE/C,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IAEtD,yBAAyB;IACzB,OAAO,CAAC,gBAAgB,CAAK;gBAEjB,QAAQ,EAAE,kBAAkB;IAQxC;;;;;;;;;;OAUG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA2B7C;;;;;;;OAOG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAS7B;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAMD;;;;;;OAMG;YACW,iBAAiB;CA2ChC"}

package/dist/lib/context/inner-type-extractor.d.ts

@@ -0,0 +1,80 @@
+/**
+ * fhir-context — InnerType Extractor
+ *
+ * Extracts inner types (BackboneElement sub-types) from a {@link CanonicalProfile}.
+ * These inner types represent nested complex structures within a FHIR resource,
+ * such as `Patient.contact` → `PatientContact`.
+ *
+ * Inspired by Medplum's `StructureDefinitionParser.enterInnerType()` and
+ * `buildTypeName()` from `@medplum/core/src/typeschema/types.ts`.
+ *
+ * ## Algorithm
+ *
+ * 1. Traverse all elements in the profile's `elements` Map
+ * 2. Identify elements whose `types` include `BackboneElement` or `Element`
+ * 3. For each such element, collect all direct child elements (path prefix match)
+ * 4. Build a new `CanonicalProfile` for the inner type with a generated name
+ *
+ * ## Naming Convention
+ *
+ * Path segments are PascalCase-joined:
+ * - `Patient.contact` → `PatientContact`
+ * - `Bundle.entry.request` → `BundleEntryRequest`
+ * - `Observation.component` → `ObservationComponent`
+ *
+ * @module fhir-context
+ */
+import type { CanonicalProfile, CanonicalElement } from '../model/canonical-profile.js';
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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>;
+//# sourceMappingURL=inner-type-extractor.d.ts.map

package/dist/lib/context/inner-type-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inner-type-extractor.d.ts","sourceRoot":"","sources":["../../../src/context/inner-type-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAMxF;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAK1D;AAeD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAIxE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,gBAAgB,GACxB,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CA0D/B"}

package/dist/lib/context/loaders/composite-loader.d.ts

@@ -0,0 +1,47 @@
+/**
+ * fhir-context — CompositeLoader
+ *
+ * Chains multiple {@link StructureDefinitionLoader} instances using the
+ * chain-of-responsibility pattern. Each loader is tried in order until
+ * one returns a non-null result.
+ *
+ * Conceptually equivalent to HAPI's `ValidationSupportChain`.
+ *
+ * @module fhir-context
+ */
+import type { StructureDefinition } from '../../model/index.js';
+import type { StructureDefinitionLoader } from '../types.js';
+/**
+ * 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;
+}
+//# sourceMappingURL=composite-loader.d.ts.map

package/dist/lib/context/loaders/composite-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite-loader.d.ts","sourceRoot":"","sources":["../../../../src/context/loaders/composite-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAG7D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,eAAgB,YAAW,yBAAyB;IAC/D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAEhE;;;OAGG;gBACS,OAAO,EAAE,yBAAyB,EAAE;IAO1C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IA4B5D,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI7B,aAAa,IAAI,MAAM;IAKvB;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;CACF"}