fhir-runtime 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-03-07
+
+### Added
+
+#### Provider Abstraction Layer (STAGE-1)
+
+- **New module: `src/provider/`** — Provider abstraction interfaces and default implementations
+  - `TerminologyProvider` interface — `validateCode()`, `expandValueSet()`, `lookupCode()`
+  - `ReferenceResolver` interface — `resolve()`, `exists()`
+  - `NoOpTerminologyProvider` — default implementation, accepts all codes
+  - `NoOpReferenceResolver` — default implementation, assumes all references exist
+  - `OperationOutcomeBuilder` — converts `ValidationResult`, `ParseResult`, `SnapshotResult` to FHIR R4 OperationOutcome
+  - `OperationOutcome`, `OperationOutcomeIssue`, `OperationOutcomeIssueType` types
+
+- **Validator integration** — `ValidationOptions` extended with optional `terminologyProvider` and `referenceResolver` fields (backward compatible)
+
+- **New exports in `src/index.ts`** — 12 type exports + 5 value exports from provider module
+
+#### Testing
+
+- 97 new tests across 6 test files in `src/provider/__tests__/`
+  - `noop-terminology-provider.test.ts` (16 tests)
+  - `noop-reference-resolver.test.ts` (11 tests)
+  - `terminology-provider-interface.test.ts` (8 tests)
+  - `reference-resolver-interface.test.ts` (10 tests)
+  - `operation-outcome-builder.test.ts` (33 tests — 18 validation + 7 parse + 8 snapshot)
+  - `validator-provider-integration.test.ts` (19 tests)
+- All v0.2.0 tests remain 100% passing (backward compatibility verified)
+
+### Notes
+
+- This release enables `fhir-server` to begin development using NoOp providers as placeholders
+- Provider interfaces use `Promise`-based async API; actual terminology validation will be implemented in STAGE-2 (v0.4.0)
+- OperationOutcome types are self-contained in `src/provider/types.ts`, not added to the model module
+- This release remains backward compatible with v0.2.0 because all provider integration points are optional
+
+---
+
 ## [0.2.0] - 2026-03-04
 
 ### Changed
@@ -158,6 +196,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Release Notes
 
+### v0.3.0 Highlights
+
+This release focuses on **provider abstraction and integration readiness** for downstream services:
+
+- ✅ **Provider contracts released** — `TerminologyProvider` and `ReferenceResolver` are now public APIs
+- ✅ **NoOp defaults included** — Higher-level projects can integrate immediately without live terminology or persistence backends
+- ✅ **OperationOutcome builders added** — Engine result objects can now be translated into FHIR-native response payloads
+- ✅ **Validator hooks prepared** — Optional provider fields are available without breaking existing validation flows
+- ✅ **Ready for STAGE-2** — Terminology binding validation can now build on stable provider abstractions
+
 ### v0.2.0 Highlights
 
 This release focuses on **production readiness** through extensive testing and documentation improvements:
@@ -174,7 +222,7 @@ Initial release providing complete FHIR R4 structural capabilities:
 
 - ✅ **Parsing** — Full FHIR R4 JSON support
 - ✅ **Validation** — 9 structural rules + FHIRPath invariants
-- ✅ **Snapshot generation** — HAPI-equivalent differential expansion
+- ✅ **Snapshot generation** — HAPI-semantically-equivalent differential expansion
 - ✅ **FHIRPath** — 60+ functions with Pratt parser
 - ✅ **Context management** — Registry, loaders, inheritance resolution
 
@@ -182,12 +230,13 @@ Initial release providing complete FHIR R4 structural capabilities:
 
 ## Roadmap
 
-### Planned for v0.3.0
+### Planned for v0.4.0
 
-- Terminology service integration (ValueSet expansion, code validation)
-- Additional IG support (more Implementation Guides verified)
-- Performance optimizations
-- Enhanced error messages
+- Binding strength validation (`required`, `extensible`, `preferred`, `example`)
+- In-memory terminology provider for tests and embedded scenarios
+- CodeSystem / ValueSet registry support in context
+- Inline ValueSet membership checks
+- US Core terminology integration tests
 
 ### Planned for v1.0.0
 
@@ -200,12 +249,13 @@ Initial release providing complete FHIR R4 structural capabilities:
 
 ## Links
 
-- **Repository**: https://github.com/medxaidev/medxai
-- **Issues**: https://github.com/medxaidev/medxai/issues
+- **Repository**: https://github.com/medxaidev/fhir-runtime
+- **Issues**: https://github.com/medxaidev/fhir-runtime/issues
 - **Documentation**: [docs/](docs/)
 - **License**: [MIT](LICENSE)
 
 ---
 
-[0.2.0]: https://github.com/medxaidev/medxai/compare/v0.1.0...v0.2.0
-[0.1.0]: https://github.com/medxaidev/medxai/releases/tag/v0.1.0
+[0.3.0]: https://github.com/medxaidev/fhir-runtime/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/medxaidev/fhir-runtime/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/medxaidev/fhir-runtime/releases/tag/v0.1.0

package/README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green)](https://nodejs.org/)
-[![Tests](https://img.shields.io/badge/Tests-2400%2B%20passing-brightgreen)]()
+[![Tests](https://img.shields.io/badge/Tests-2847%20passing-brightgreen)]()
 
 `fhir-runtime` is a **structural FHIR R4 engine** that provides comprehensive capabilities for parsing, validating, and manipulating FHIR resources — without requiring a running FHIR server, database, or external terminology service.
 
@@ -13,26 +13,28 @@ Designed as a pure runtime layer with **zero dependencies**, it's suitable for e
 
 ---
 
-## ✨ Features
+## Features
 
 ### Core Capabilities
 
-- **🔍 FHIR R4 JSON Parsing** — Full support for primitives, choice types, extensions
-- **✅ Profile-Based Validation** — 9 structural validation rules + FHIRPath invariants
-- **📸 Snapshot Generation** — HAPI-equivalent differential expansion
-- **🧮 FHIRPath Engine** — 60+ functions, Pratt parser with AST caching
-- **📦 Bundle Loading** — Load FHIR specification bundles and IGs
-- **🔄 Context Management** — Registry, loaders, inheritance resolution
-- **🎯 InnerType Extraction** — BackboneElement schema for UI/validation
+- FHIR R4 JSON Parsing — Full support for primitives, choice types, extensions
+- Profile-Based Validation — 9 structural validation rules + FHIRPath invariants
+- Provider Abstraction Layer (STAGE-1) — Terminology and reference contracts with default NoOp implementations
+- Snapshot Generation — HAPI-equivalent differential expansion
+- FHIRPath Engine — 60+ functions, Pratt parser with AST caching
+- Bundle Loading — Load FHIR specification bundles and IGs
+- Context Management — Registry, loaders, inheritance resolution
+- InnerType Extraction — BackboneElement schema for UI/validation
+- OperationOutcomeBuilder — Convert validation, parse, and snapshot results to FHIR R4 `OperationOutcome`
 
 ### Quality & Testing
 
-- **2,400+ tests** across 45 test files — 100% passing
-- **US Core IG verified** — 70 StructureDefinitions, 55 profiles validated
-- **HAPI-equivalent** — 35/35 snapshot fixtures match HAPI output
-- **Stress tested** — Malformed input, deep nesting, large payloads, concurrency
-- **Zero dependencies** — Pure TypeScript, no external runtime deps
-- **Type-safe** — Full TypeScript definitions for all FHIR R4 types
+- 2,847 tests across 51 test files — 100% passing
+- US Core IG verified — 70 StructureDefinitions, 55 profiles validated
+- HAPI-equivalent — 35/35 snapshot fixtures match HAPI output
+- Stress tested — Malformed input, deep nesting, large payloads, concurrency
+- Zero dependencies — Pure TypeScript, no external runtime deps
+- Type-safe — Full TypeScript definitions for all FHIR R4 types
 
 ---
 
@@ -49,6 +51,21 @@ npm install fhir-runtime
 
 ---
 
+## 🎮 Try it Online
+
+**[FHIR Runtime Playground](https://medxai.com.cn/fhir-runtime-playground/)** — Interactive browser-based playground to experiment with fhir-runtime capabilities:
+
+- 🔍 **Parse FHIR Resources** — Test JSON parsing with real-time feedback
+- ✅ **Validate Resources** — Validate against profiles and see detailed issues
+- 📸 **Generate Snapshots** — Visualize differential expansion
+- 🧮 **Evaluate FHIRPath** — Interactive FHIRPath expression testing
+- 📚 **Example Library** — Pre-loaded examples and profiles
+- 💾 **Share & Export** — Save and share your experiments
+
+**Playground Repository:** [github.com/medxaidev/fhir-runtime-playground](https://github.com/medxaidev/fhir-runtime-playground)
+
+---
+
 ## 🚀 Quick Start
 
 ### Parse a FHIR Resource
@@ -132,8 +149,9 @@ const hasOfficial = evalFhirPathBoolean(
 ## 📚 Documentation
 
 - **[Technical Overview](docs/overview/fhir-runtime-overview.md)** — Architecture, design principles, capabilities
-- **[API Reference](docs/api/fhir-runtime-api-v0.2.md)** — Complete API documentation (211 exports)
-- **[Capability Contract](docs/specs/engine-capability-contract-v0.2.md)** — Behavioral guarantees, error semantics
+- **[API Reference](docs/api/fhir-runtime-api-v0.3.md)** — Public API reference for the v0.3.0 release surface
+- **[Capability Contract](docs/specs/engine-capability-contract-v0.3.md)** — Behavioral guarantees and release contract for v0.3.0
+- **[STAGE-1 Provider Abstraction](devdocs/stage/STAGE-1-provider-abstraction.md)** — Completed v0.3.0 provider abstraction delivery plan
 
 ---
 
@@ -142,9 +160,19 @@ const hasOfficial = evalFhirPathBoolean(
 ### Test Coverage
 
 ```
-✅ 2,400+ tests across 45 test files
+✅ 2,847 tests across 51 test files
 ✅ 100% pass rate on HAPI snapshot fixtures (35/35)
-✅ All 6 modules fully tested (parser, context, profile, validator, fhirpath, model)
+✅ All 7 modules fully tested (model, parser, context, profile, validator, fhirpath, provider)
+```
+
+### v0.3.0 Provider Abstraction Coverage
+
+```
+✅ 97 new tests across 6 provider-focused test files
+✅ TerminologyProvider and ReferenceResolver interface contracts verified
+✅ NoOp providers validated for backward-compatible default behavior
+✅ OperationOutcomeBuilder conversions covered for validation, parse, and snapshot flows
+✅ Validator integration verified with optional provider hooks
 ```
 
 ### US Core IG Verification
@@ -182,7 +210,8 @@ src/
 ├── context/      ← SD registry, loaders, inheritance resolution, bundle loading
 ├── profile/      ← Snapshot generation, canonical builder, constraint merging
 ├── validator/    ← Structural validation (9 rules + FHIRPath invariants)
-└── fhirpath/     ← FHIRPath expression engine (Pratt parser, 60+ functions)
+├── fhirpath/     ← FHIRPath expression engine (Pratt parser, 60+ functions)
+└── provider/     ← Terminology/reference abstractions, NoOp providers, OperationOutcomeBuilder
 ```
 
 ### HAPI FHIR Equivalence
@@ -200,6 +229,7 @@ src/
 ## 🎯 Use Cases
 
 - **FHIR Servers** — Validation layer for REST operations
+- **FHIR Server Foundations** — Start `fhir-server` development with NoOp providers before terminology is implemented
 - **CLI Tools** — Parse, validate, generate snapshots, evaluate FHIRPath
 - **Web Applications** — Client-side FHIR processing without server dependency
 - **IG Publishers** — Profile validation and snapshot generation
@@ -214,35 +244,37 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 ---
 
-## 🤝 Contributing
-
-Contributions are welcome! This project maintains:
-
-- **Zero runtime dependencies** — Keep it that way
-- **100% test pass rate** — All tests must pass
-- **Type safety** — Full TypeScript coverage
-- **HAPI equivalence** — Snapshot generation must match HAPI output
-
----
-
 ## 📊 Package Details
 
 | Property                 | Value                           |
 | ------------------------ | ------------------------------- |
 | Package name             | `fhir-runtime`                  |
-| Version                  | 0.2.0                           |
+| Version                  | 0.3.0                           |
 | License                  | MIT                             |
 | FHIR Version             | R4 (4.0.1)                      |
 | Module formats           | ESM + CJS                       |
 | Runtime dependencies     | None (zero dependencies)        |
 | Bundled core definitions | 73 FHIR R4 StructureDefinitions |
-| Public exports           | 211 symbols across 6 modules    |
-| Test coverage            | 2,400+ tests across 45 files    |
+| Public exports           | 228+ symbols across 7 modules   |
+| Test coverage            | 2,847 tests across 51 files     |
+
+---
+
+## 🆕 Release Highlights
+
+### v0.3.0
+
+- **Provider Abstraction Layer landed** — `TerminologyProvider` and `ReferenceResolver` are now part of the public API
+- **Default NoOp implementations** — Safe placeholders for higher-level services and integration work
+- **OperationOutcomeBuilder support** — Convert structured engine results into FHIR-native error payloads
+- **Backward compatible** — Existing validation flows continue to work with optional provider hooks
+- **Ready for STAGE-2** — Terminology binding validation can now build on the released provider contracts
 
 ---
 
 ## 🔗 Related Projects
 
+- **[FHIR Runtime Playground](https://medxai.com.cn/fhir-runtime-playground/)** — Interactive online playground ([GitHub](https://github.com/medxaidev/fhir-runtime-playground))
 - **[HAPI FHIR](https://hapifhir.io/)** — Reference Java implementation
 - **[HL7 FHIR Specification](https://hl7.org/fhir/R4/)** — Official FHIR R4 spec
 - **[US Core IG](https://www.hl7.org/fhir/us/core/)** — US Core Implementation Guide

package/dist/cjs/index.cjs

@@ -34,6 +34,8 @@ __export(index_exports, {
   InvalidStructureDefinitionError: () => InvalidStructureDefinitionError,
   LoaderError: () => LoaderError,
   MemoryLoader: () => MemoryLoader,
+  NoOpReferenceResolver: () => NoOpReferenceResolver,
+  NoOpTerminologyProvider: () => NoOpTerminologyProvider,
   PRIMITIVE_TYPES: () => PRIMITIVE_TYPES,
   ProfileError: () => ProfileError,
   ProfileNotFoundError: () => ProfileNotFoundError,
@@ -47,6 +49,9 @@ __export(index_exports, {
   buildCanonicalElement: () => buildCanonicalElement,
   buildCanonicalProfile: () => buildCanonicalProfile,
   buildInvariants: () => buildInvariants,
+  buildOperationOutcome: () => buildOperationOutcome,
+  buildOperationOutcomeFromParse: () => buildOperationOutcomeFromParse,
+  buildOperationOutcomeFromSnapshot: () => buildOperationOutcomeFromSnapshot,
   buildSlicingDefinition: () => buildSlicingDefinition,
   buildTypeConstraints: () => buildTypeConstraints,
   buildTypeName: () => buildTypeName,
@@ -4285,7 +4290,9 @@ function resolveValidationOptions(options) {
     validateFixed: options?.validateFixed ?? true,
     maxDepth: options?.maxDepth ?? 50,
     failFast: options?.failFast ?? false,
-    skipInvariants: options?.skipInvariants ?? false
+    skipInvariants: options?.skipInvariants ?? false,
+    terminologyProvider: options?.terminologyProvider ?? void 0,
+    referenceResolver: options?.referenceResolver ?? void 0
   };
 }
 function hasValidationErrors(issues) {
@@ -7271,6 +7278,182 @@ var StructureValidator = class {
     }
   }
 };
+
+// src/provider/noop-terminology-provider.ts
+var NoOpTerminologyProvider = class {
+  /**
+   * Always returns `{ result: true }`.
+   *
+   * No actual code validation is performed.
+   */
+  async validateCode(_params) {
+    return { result: true };
+  }
+  /**
+   * Always returns an empty expansion `{ contains: [] }`.
+   *
+   * No actual ValueSet expansion is performed.
+   */
+  async expandValueSet(_params) {
+    return { contains: [] };
+  }
+  /**
+   * Always returns `{ found: false }`.
+   *
+   * No actual code lookup is performed.
+   */
+  async lookupCode(_params) {
+    return { found: false };
+  }
+};
+
+// src/provider/noop-reference-resolver.ts
+var NoOpReferenceResolver = class {
+  /**
+   * Always returns `undefined`.
+   *
+   * No actual reference resolution is performed.
+   */
+  async resolve(_reference) {
+    return void 0;
+  }
+  /**
+   * Always returns `true`.
+   *
+   * Assumes all reference targets exist without checking.
+   */
+  async exists(_reference) {
+    return true;
+  }
+};
+
+// src/provider/operation-outcome-builder.ts
+var VALIDATION_ISSUE_TYPE_MAP = {
+  CARDINALITY_MIN_VIOLATION: "structure",
+  CARDINALITY_MAX_VIOLATION: "structure",
+  TYPE_MISMATCH: "value",
+  INVALID_CHOICE_TYPE: "value",
+  REQUIRED_ELEMENT_MISSING: "required",
+  FIXED_VALUE_MISMATCH: "value",
+  PATTERN_VALUE_MISMATCH: "value",
+  SLICING_NO_MATCH: "structure",
+  SLICING_CARDINALITY_VIOLATION: "structure",
+  SLICING_ORDER_VIOLATION: "structure",
+  REFERENCE_TARGET_MISMATCH: "value",
+  PROFILE_NOT_FOUND: "not-found",
+  RESOURCE_TYPE_MISMATCH: "invalid",
+  UNKNOWN_ELEMENT: "structure",
+  INVARIANT_NOT_EVALUATED: "not-supported",
+  INVARIANT_VIOLATION: "invariant",
+  INVARIANT_EVALUATION_ERROR: "processing",
+  INTERNAL_ERROR: "processing"
+};
+function validationIssueToOutcomeIssue(issue) {
+  const outcomeIssue = {
+    severity: issue.severity,
+    code: VALIDATION_ISSUE_TYPE_MAP[issue.code] ?? "processing",
+    details: { text: `[${issue.code}] ${issue.message}` },
+    ...issue.diagnostics !== void 0 ? { diagnostics: issue.diagnostics } : {},
+    ...issue.path !== void 0 || issue.expression !== void 0 ? { expression: [issue.expression ?? issue.path] } : {}
+  };
+  return outcomeIssue;
+}
+function buildOperationOutcome(result) {
+  if (result.issues.length === 0) {
+    return {
+      resourceType: "OperationOutcome",
+      issue: [
+        {
+          severity: "information",
+          code: "informational",
+          details: { text: "Validation successful" }
+        }
+      ]
+    };
+  }
+  return {
+    resourceType: "OperationOutcome",
+    issue: result.issues.map(validationIssueToOutcomeIssue)
+  };
+}
+var PARSE_ISSUE_TYPE_MAP = {
+  INVALID_JSON: "structure",
+  MISSING_RESOURCE_TYPE: "required",
+  UNKNOWN_RESOURCE_TYPE: "not-found",
+  INVALID_PRIMITIVE: "value",
+  INVALID_STRUCTURE: "structure",
+  INVALID_CHOICE_TYPE: "value",
+  MULTIPLE_CHOICE_VALUES: "structure",
+  ARRAY_MISMATCH: "structure",
+  UNEXPECTED_NULL: "value",
+  UNEXPECTED_PROPERTY: "informational"
+};
+function parseIssueToOutcomeIssue(issue) {
+  return {
+    severity: issue.severity === "error" ? "error" : "warning",
+    code: PARSE_ISSUE_TYPE_MAP[issue.code] ?? "processing",
+    details: { text: `[${issue.code}] ${issue.message}` },
+    expression: [issue.path]
+  };
+}
+function buildOperationOutcomeFromParse(result) {
+  if (result.issues.length === 0) {
+    return {
+      resourceType: "OperationOutcome",
+      issue: [
+        {
+          severity: "information",
+          code: "informational",
+          details: { text: "Parsing successful" }
+        }
+      ]
+    };
+  }
+  return {
+    resourceType: "OperationOutcome",
+    issue: result.issues.map(parseIssueToOutcomeIssue)
+  };
+}
+var SNAPSHOT_ISSUE_TYPE_MAP = {
+  CIRCULAR_DEPENDENCY: "processing",
+  BASE_NOT_FOUND: "not-found",
+  BASE_MISSING_SNAPSHOT: "not-found",
+  DIFFERENTIAL_NOT_CONSUMED: "structure",
+  CARDINALITY_VIOLATION: "business-rule",
+  TYPE_INCOMPATIBLE: "value",
+  BINDING_VIOLATION: "business-rule",
+  SLICING_ERROR: "structure",
+  PATH_NOT_FOUND: "not-found",
+  INVALID_CONSTRAINT: "business-rule",
+  INTERNAL_ERROR: "processing"
+};
+function snapshotIssueToOutcomeIssue(issue) {
+  return {
+    severity: issue.severity,
+    code: SNAPSHOT_ISSUE_TYPE_MAP[issue.code] ?? "processing",
+    details: { text: `[${issue.code}] ${issue.message}` },
+    ...issue.details !== void 0 ? { diagnostics: issue.details } : {},
+    ...issue.path !== void 0 ? { expression: [issue.path] } : {}
+  };
+}
+function buildOperationOutcomeFromSnapshot(result) {
+  if (result.issues.length === 0) {
+    return {
+      resourceType: "OperationOutcome",
+      issue: [
+        {
+          severity: "information",
+          code: "informational",
+          details: { text: "Snapshot generation successful" }
+        }
+      ]
+    };
+  }
+  return {
+    resourceType: "OperationOutcome",
+    issue: result.issues.map(snapshotIssueToOutcomeIssue)
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ALL_CORE_DEFINITIONS,
@@ -7287,6 +7470,8 @@ var StructureValidator = class {
   InvalidStructureDefinitionError,
   LoaderError,
   MemoryLoader,
+  NoOpReferenceResolver,
+  NoOpTerminologyProvider,
   PRIMITIVE_TYPES,
   ProfileError,
   ProfileNotFoundError,
@@ -7300,6 +7485,9 @@ var StructureValidator = class {
   buildCanonicalElement,
   buildCanonicalProfile,
   buildInvariants,
+  buildOperationOutcome,
+  buildOperationOutcomeFromParse,
+  buildOperationOutcomeFromSnapshot,
   buildSlicingDefinition,
   buildTypeConstraints,
   buildTypeName,