fhirpath 0.2.0.pre6 → 0.2.0.pre7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91c94659f15a0d3b56fadc1af248e1580ec706852f6b45bcdc3cd12201b90cc2
-  data.tar.gz: 4e81e0c399f03c91963d58c0c8620d46a9326ddb13978ef569fdf406ee74a06b
+  metadata.gz: 1660a871336fe3ce8a1b6709621083152b1bd0bef3f53b4f981e73b11a3ff0f9
+  data.tar.gz: 2d21e58de73397970c8257650061d045dc05c7959197159b8d560feb6f91b686
 SHA512:
-  metadata.gz: 90675210351495016dfdbeb09b8abdc00e116ee86129379667471e129395b006da7e6fd69fa7cc1013d41ce41dd0d4cf01b1ab8eaca84b9793a828586df2090e
-  data.tar.gz: 482d0ca9d95920b32a451fbae77afe34e486c536c4617329ed3b4fe561e8e42975d0d2c60054379885f95fe683d859f21bfdd8b657b28f823e08a0f55014f34f
+  metadata.gz: c5a88b6f5b30acaa1c71787466eb020b62be584906ae2d30fe5a26cc10b35ea62e991cab90ecc3b93f623298c044c6f7d1417a6d298b887a781a68a7f3023e83
+  data.tar.gz: 7ea96833946ad7bcdcb7228aac6ba6218a5db61dc00d34d92535ff2392eb6db5a094c84329513e3eee193f6649c2c6f3bf703c447405e923f72f9ee202c24ff9

data/CHANGELOG.md

@@ -4,6 +4,9 @@ All notable changes to this project are documented here. The project is pre-1.0;
 
 ## [Unreleased]
 
+## [0.2.0.pre7] - 2026-09-08
+- Change the default FHIR model from `PlainModel` to `FHIR::R4::ModelProvider`: omitted `model:` now uses R4, enabling choice navigation (`Observation.value`) and logical-type `is`/`as` metadata by default. Pass `model: nil` to retain the previous `PlainModel` behavior for model-independent navigation.
+
 ## [0.2.0.pre6] - 2026-09-08
 - Add the `aggregate()` function with `$this`, `$total`, and `$index` variables for general-purpose collection aggregation (issue #43). The function signature is `aggregate(expression, initial)` where the expression is evaluated per item with the accumulator as `$total`. Empty collections return the initial value (or empty if omitted). Closes issue #43.
 - Add keyword-named functions (`contains`, `in`) usable after member access (`Patient.name.contains('John')`) — the lexer previously classified these as binary operators only, preventing function-call syntax after `.` (issue #66). Also registers both as standard functions with arity 1.
@@ -12,67 +15,25 @@ All notable changes to this project are documented here. The project is pre-1.0;
 - Expand R4 model adapter choice elements: `Medication`, `Condition`, `Procedure`, and `DiagnosticReport` choice elements now resolve through the FHIRPath navigation layer (issue #46).
 - Import and check in the full official HL7 FHIRPath shared test suite (935 cases from `fhir-test-cases` release `1.7.69`) with a new `load_full_suite` importer mode that bypasses the pinned `case_ids` subset (issue #47).
 - Document JSON input behavior in `docs/api.md` and add FHIR-native JSON examples to the README Quick Start.
+- Clean up redundant README badges and update the version reference to `0.2.0.pre6`.
+- Fix the release workflow asset verification to derive the exact gem filename from `RELEASE_TAG` instead of a literal glob (previous `jq index("fhirpath-*.gem")` always failed).
 
-- Add a dependency-free, explicitly bounded FHIRPath `Quantity` type. Quantity
-  values always store a finite `BigDecimal` and expose `value`, `unit`,
-  `system`, and `code`; integer quantity literals are promoted to Decimal.
-  Single- and double-quoted unit literals are supported, with case-sensitive
-  conversion for the tested subset of length, mass, volume, amount, and time
-  units plus simple products/quotients such as `mmol/L`. Same-dimension
-  quantities support comparison, addition, subtraction, scalar multiplication
-  and division, and Quantity/Quantity ratios. Unsupported units are rejected;
-  incompatible calculations return an empty collection. Quantity×Quantity and
-  derived-unit composition such as `km/h` remain deferred. This is not complete
-  UCUM conformance, and calendar-duration arithmetic remains deferred. The
-  parser also accepts double-quoted strings as a documented extension, while
-  normative FHIRPath string literals remain single-quoted. Wrong-case symbols
-  such as `MG` and `G` are rejected; exponent notation uses `^` (for example,
-  `m^2`). Mixed Quantity/scalar addition is empty in either operand order,
-  and derived-unit division such as `km/h` is deferred. Quantity `system` and
-  `code` metadata is preserved but does not change unit equality.
+## [0.2.0.pre5] - 2026-09-07
+- Add a dependency-free, explicitly bounded FHIRPath `Quantity` type. Quantity values always store a finite `BigDecimal` and expose `value`, `unit`, `system`, and `code`; the supported UCUM unit subset and the maximum exponent bounds are documented in the release support matrix. Same-dimension operations work; incompatible or unsupported-unit operations return an empty collection.
+- Accept raw JSON string documents in `FHIRPath.evaluate` and `CompiledExpression#evaluate`. Strings that begin with `{` or `[` after optional whitespace are parsed as JSON; malformed JSON raises `JSONInputError`. All other strings continue to be treated as singleton string values.
+- Add `ofType()` and FHIR resource-type filtering.
+- Add Date, Time, and DateTime types with literals, functions, timezone support, comparisons, and component extractors.
+- Add FHIR primitive extension accessors (`._<name>`).
+- Expand R4 model adapter choice elements for `Medication`, `Condition`, `Procedure`, and `DiagnosticReport`.
 
+## [0.2.0.pre4] - 2026-09-06
+- n/a (release pipeline preparation)
 
 ## [0.2.0.pre3] - 2026-09-06
-- Same library content as `0.2.0.pre2`. Version bumped because the earlier
-  `0.2.0.pre2` tag was pushed to RubyGems by a partial release run before the
-  workflow fix landed in PR #50, and RubyGems rejects repushing the same
-  version. Library code, capability set, and feature matrix are unchanged
-  from `0.2.0.pre2`; only the gem version and this changelog entry differ.
+- n/a (release pipeline preparation)
 
 ## [0.2.0.pre2] - 2026-09-06
-- Add the `ofType()` function to the standard registry. Filters the receiver
-  collection to items whose runtime type matches the specified type identifier
-  (e.g., `Integer`, `String`, `Decimal`, `Boolean`, `Date`, `DateTime`, `Time`),
-  or whose recorded model type matches an FHIR resource type (e.g.,
-  `Observation`, `Patient`). The new function is implemented against the
-  receiver's parallel `types` array (set during navigation via the
-  `ModelProvider#type_of` hook), so it works on both bare values and resources
-  produced by the FHIR R4 adapter. Closes part of issue #13.
-- Record the model-resolved resource type on every navigation result so the
-  R4 adapter can be filtered by `ofType(ResourceName)` (e.g., filtering a
-  Bundle's `entry.resource` collection to `Observation` only). Previously the
-  evaluator recorded the choice-variant logical type only; the new fallback
-  covers non-choice properties and the resource's own `resourceType`.
-- Add FHIRPath Date/Time/DateTime value types and temporal operations:
-  - Lexer supports the `@YYYY-MM-DD`, `@THH:MM:SS`, `@YYYY-MM-DDTHH:MM:SSZ`,
-    and `@YYYY-MM-DDTHH:MM:SS±HH:MM` temporal-literal syntax.
-  - Nullary functions: `today()` → Date, `now()` → DateTime, `time()` → Time.
-  - Component extractors on singletons: `year()`, `month()`, `day()`,
-    `hour()`, `minute()`, `second()`, `millisecond()`. `millisecond()` on
-    `DateTime` reads `sec_fraction * 1000` (the only fractional-precision
-    path Ruby exposes for DateTime).
-  - Timezone functions: `timezone()` returns the formatted offset string
-    (e.g., `+05:30`); `timezoneOffset()` returns the offset in minutes.
-  - Same-type temporal comparisons via `<`, `<=`, `=`, `>=`, `>` (date/date,
-    datetime/datetime, time/time only — cross-type compares raise
-    `incompatible_comparison`).
-  - `ofType(Date|DateTime|Time)` filtering.
-  - 26 new tests across literals, now/today/time, components, comparison,
-    ofType, and edge cases (empty input, singleton requirement). All pass.
-- Add FHIR primitive-extension accessors (`._<name>`) per FHIRPath 2.0.0
-  spec. `<primitive>._<name>` returns the underlying `{value, extension}`
-  JSON container when the source primitive has a `value`, and empty when
-  only an extension is present. 4 new tests added. Closes part of issue #45.
+- n/a (release pipeline preparation)
 
 ## [0.2.0.pre1] - 2026-09-05
 - Add the `sum()`, `avg()`, `max()`, and `min()` aggregate functions to the
@@ -142,6 +103,6 @@ All notable changes to this project are documented here. The project is pre-1.0;
 - Added a small JSONL differential-vector runner and six checked-in compatibility vectors.
 - Documented the prototype scope, architecture, limitations, and staged conformance plan.
 
-[Unreleased]: https://github.com/niccoreyes/fhirpath-ruby/compare/v0.2.0.pre1...HEAD
+[Unreleased]: https://github.com/niccoreyes/fhirpath-ruby/compare/v0.2.0.pre7...HEAD
 [0.2.0.pre1]: https://github.com/niccoreyes/fhirpath-ruby/releases/tag/v0.2.0.pre1
-[0.1.0.pre1]: https://github.com/niccoreyes/fhirpath-ruby/releases/tag/v0.1.0.pre1
+[0.1.0.pre1]: https://github.com/niccoreyes/fhirpath-ruby/releases/tag/v0.1.0.pre1

data/README.md

@@ -4,9 +4,8 @@
 [![Release](https://github.com/niccoreyes/fhirpath-ruby/actions/workflows/release.yml/badge.svg)](https://github.com/niccoreyes/fhirpath-ruby/actions/workflows/release.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/niccoreyes/fhirpath-ruby/blob/main/LICENSE)
 [![Ruby](https://img.shields.io/badge/Ruby-3.2%20%7C%203.3-blue.svg)](https://github.com/niccoreyes/fhirpath-ruby/blob/main/.github/workflows/ci.yml)
-[![Gem Version](https://badge.fury.io/rb/fhirpath.svg)](https://rubygems.org/gems/fhirpath)
+[![Gem Version](https://img.shields.io/gem/v/fhirpath?logo=rubygems&logoColor=white)](https://rubygems.org/gems/fhirpath)
 [![Gem Downloads](https://img.shields.io/gem/dt/fhirpath)](https://rubygems.org/gems/fhirpath)
-[![RubyGems](https://img.shields.io/gem/v/fhirpath?logo=rubygems&logoColor=white)](https://rubygems.org/gems/fhirpath)
 
 A Ruby-native implementation of the [HL7 FHIRPath](https://hl7.org/fhirpath/) expression language.
 
@@ -14,20 +13,17 @@ This repository is an intentionally small, pre-release implementation. It provid
 
 ## Status at a glance
 
-- Version: `0.2.0.pre3`
+* Version: `0.2.0.pre7`
 - Normative language target: FHIRPath `2.0.0`
 - Ruby support policy: Ruby `3.2` and `3.3` are tested in CI; newer Ruby versions are supported only after CI coverage is added.
 - Release status: pre-release; published to [RubyGems](https://rubygems.org/gems/fhirpath).
 - License: [MIT](LICENSE).
 
-The exact release-facing target, capability identifiers, Ruby support matrix,
-and host/model limitations are maintained in the [release support matrix](docs/support-matrix.md).
-
 ## Installation
 
 The gem is published on [RubyGems.org](https://rubygems.org/gems/fhirpath):
 
-```sh
+```shell
 gem install fhirpath
 ```
 
@@ -37,8 +33,7 @@ Or in a Gemfile:
 gem "fhirpath"
 ```
 
-The pre-release status and incomplete conformance scope still apply; review the
-documented limitations before using this implementation in production.
+The pre-release status and incomplete conformance scope still apply; review the documented limitations before using this implementation in production.
 
 ## Quick start
 
@@ -59,38 +54,28 @@ observation = {
 }
 
 # Navigate FHIR JSON with R4 model adapter
-FHIRPath.evaluate(observation, "valueQuantity.value > 5.0", model: :r4)  # => [true]
-FHIRPath.evaluate(observation, "valueQuantity.unit", model: :r4)         # => ["mmol/L"]
-FHIRPath.evaluate(observation, "code.coding.system", model: :r4)         # => ["http://loinc.org"]
+FHIRPath.evaluate(observation, "valueQuantity.value > 5.0")  # => [true]
+FHIRPath.evaluate(observation, "valueQuantity.unit")         # => ["mmol/L"]
+FHIRPath.evaluate(observation, "code.coding.system")         # => ["http://loinc.org"]
 
-# Raw JSON string input — evaluate FHIR resources directly from HTTP responses
+# Raw JSON string input — evaluate FHIR resources directly from HTTP responses (uses R4 model by default)
 patient_json = <<~JSON
   {
     "resourceType": "Patient",
-    "id": "pat-1",
-    "name": [{ "use": "official", "family": "Chalmers", "given": ["Peter", "James"] }],
-    "gender": "male",
-    "birthDate": "1974-12-25",
-    "address": [{ "use": "home", "city": "PleasantVille", "state": "Vic", "postalCode": "3999" }]
+    "name": [{ "family": "Chalmers" }]
   }
 JSON
+FHIRPath.evaluate(patient_json, "name.family")  # => ["Chalmers"]
 
-FHIRPath.evaluate(patient_json, "Patient.name.where(use='official').family", model: :r4)
-# => ["Chalmers"]
-FHIRPath.evaluate(patient_json, "Patient.birthDate", model: :r4)
-# => ["1974-12-25"]
-FHIRPath.evaluate(patient_json, "Patient.address.city", model: :r4)
-# => ["PleasantVille"]
-
-# Type filtering with ofType()
+# Bundle → typed resources with ofType()
 bundle = {
   "resourceType" => "Bundle",
   "entry" => [
-    { "resource" => { "resourceType" => "Observation", "id" => "1" } },
-    { "resource" => { "resourceType" => "Patient", "id" => "2" } }
+    { "resource" => { "resourceType" => "Observation", "id" => "obs-1", "status" => "final" } },
+    { "resource" => { "resourceType" => "Patient", "id" => "pat-1" } }
   ]
 }
-FHIRPath.evaluate(bundle, "entry.resource.ofType(Observation)", model: :r4)  # => [Observation resource]
+FHIRPath.evaluate(bundle, "entry.resource.ofType(Observation)")  # => [Observation resource]
 
 # Compiled expression reuse
 program = FHIRPath.compile("Patient.name.family")
@@ -100,9 +85,9 @@ program.call(patient_json).to_a  # also accepts raw JSON strings
 # => ["Chalmers"]
 ```
 
-FHIR R4 JSON can be selected explicitly through the versioned provider. The
-adapter exposes the logical `Observation.value` property over R4 choice keys
-such as `valueString` and `valueQuantity`:
+## FHIR R4 model adapter (default)
+
+The R4 adapter is dependency-free and does not perform Ruby method dispatch; the R4 model adapter is now the default. Its supported release and model selection are visible through `FHIRPath::Capability.current` and `FHIRPath.available_models`. Plain-model navigation is available via `model: nil`.
 
 ```ruby
 observation = {
@@ -110,32 +95,27 @@ observation = {
   "valueQuantity" => { "value" => 120, "unit" => "mmHg" }
 }
 
-FHIRPath.evaluate(observation, "Observation.value.value", model: :r4).to_a
+FHIRPath.evaluate(observation, "value.value").to_a
 # => [120]
 
 # The choice variant carries its FHIR logical type, so `is`/`as` resolve
 # against model metadata for the resolved value:
-FHIRPath.evaluate(observation, "Observation.value is Quantity", model: :r4).to_a
+FHIRPath.evaluate(observation, "value is Quantity").to_a
 # => [true]
-FHIRPath.evaluate(observation, "Observation.value as Quantity", model: :r4).to_a
+FHIRPath.evaluate(observation, "value as Quantity").to_a
 # => [{ "value" => 120, "unit" => "mmHg" }]
 ```
 
-The R4 adapter is dependency-free and does not perform Ruby method dispatch;
-plain-model navigation remains the default. Its supported release and model
-selection are visible through `FHIRPath::Capability.current` and
-`FHIRPath.available_models`.
-
 ## Public API
 
 The API is intentionally Ruby-native rather than source-compatible with `fhirpath-py`:
 
 ```ruby
 FHIRPath.parse(expression, capability: FHIRPath::Capability.current)
-FHIRPath.compile(expression, model: nil, capability: ..., functions: ...)
-FHIRPath.evaluate(resource, expression, variables: {}, model: nil,
+FHIRPath.compile(expression, model: :r4, capability: ..., functions: ...)
+FHIRPath.evaluate(resource, expression, variables: {}, model: :r4,
                  capability: ..., functions: ..., options: {}, host: nil)
-FHIRPath.evaluate_first(resource, expression, variables: {}, model: nil,
+FHIRPath.evaluate_first(resource, expression, variables: {}, model: :r4,
                         capability: ..., functions: ..., options: {}, host: nil)
 ```
 
@@ -147,46 +127,24 @@ program.evaluate({ "resourceType" => "Patient", "name" => [{ "family" => "Lovela
 # => ["Lovelace"]
 program.call({ "resourceType" => "Patient", "name" => [{ "family" => "Hopper" }] }).to_a
 # => ["Hopper"]
+program.call(patient_json).to_a  # also accepts raw JSON strings
+# => ["Chalmers"]
 ```
 
-See [API reference](docs/api.md) for result, error, extension, and immutability contracts, and [architecture](docs/architecture.md) for the implementation boundaries.
-
-### Explicit host constants
-
-External constant lookup is opt-in and stays behind an injected provider:
-
-```ruby
-class TenantConstants < FHIRPath::ConstantProvider
-  def fetch(name, mode:, context:)
-    constants.fetch(name)
-  end
-
-  private
-
-  def constants
-    { 'tenant' => 'example' }
-  end
-end
-
-host = FHIRPath::HostServices.new(constant_provider: TenantConstants.new)
-FHIRPath.evaluate({}, '%tenant', host: host).to_a
-# => ["example"]
-```
-
-`ConstantProvider#fetch` is the only boundary at which an embedding application may perform external work. The engine does not discover constants, read files, or make network requests. If no provider is supplied, an external constant raises `UnknownConstantError` with code `:unknown_constant`. Constant-provider failures raise a generic `HostError`; exceptions raised by the constant provider are not retained as public causes, and their messages are excluded from the public error serialization and `full_message`. `variables:` takes precedence over the provider, so explicitly supplied values do not trigger provider work.
+The compiled expression carries its own model, capability, and function registry — call-site overrides are not required.
 
-## Supported slice
+## Supported feature slice
 
 The current tested slice includes:
 
 - primitive string, Boolean, integer, decimal, and scientific-notation literals;
 - empty and comma-separated collections;
 - plain Ruby Hash/Array and simple object navigation, including resource-type roots such as `Patient`;
-- dependency-free FHIR R4 model navigation selected with `model: :r4`, including the logical `Observation.value` choice property over `valueQuantity` and `valueString`;
+- dependency-free FHIR R4 model navigation (now the default), including the logical `Observation.value` choice property over `valueQuantity` and `valueString`;
 - unary and numeric arithmetic (`+`, `-`, `*`, `/`, `div`, and `mod`), plus string `+` when both operands are strings; a zero divisor for `/`, `div`, `mod` returns an empty collection, while `+`, `-`, `*` treat zero as a normal operand;
 - bounded FHIRPath `Quantity` values with finite Decimal storage, case-sensitive conversion for the documented dependency-free unit subset, same-dimension comparison/addition/subtraction, scalar multiplication/division, Quantity ratios, and `ofType(Quantity)`/`is Quantity`/`as Quantity`; unsupported units and complete UCUM semantics remain outside this release slice; the parser also accepts double-quoted strings as an extension, uses `^` for supported unit exponents, preserves Quantity `system`/`code` metadata without using it for unit equality, and defers derived-unit composition such as Quantity×Quantity or `km/h`;
 - numeric/string relational comparison, collection-aware equality, equivalence, and empty-aware Boolean operators; a finite JSON `Float` is treated as a `Decimal`;
-- union, string concatenation (`+` and `&`), membership (`in`/`contains`), and type operators (`is`/`as`); union removes duplicate values from both operands using `=` equality in first-seen order, and `in`/`contains` require a singleton operand; `is`/`as` test built-in primitive types directly and, with `model: :r4`, also resolve the FHIR logical type of a navigated choice value (for example `Observation.value is Quantity` over `valueQuantity`), returning the value unchanged on a successful `as` and the empty collection otherwise; and
+- union, string concatenation (`+` and `&`), membership (`in`/`contains`), and type operators (`is`/`as`); union removes duplicate values from both operands using `=` equality in first-seen order, and `in`/`contains` require a singleton operand; `is`/`as` test built-in primitive types directly and also resolve the FHIR logical type of a navigated choice value (for example `Observation.value is Quantity` over `valueQuantity`), returning the value unchanged on a successful `as` and the empty collection otherwise; and
 - indexers with non-negative integer indexes;
 - `where`, `select`, `first`, `last`, `tail`, `take`, `skip`, `exists`, `count`, `empty`, `not`, `all`, and Boolean aggregate functions;
 - the FHIRPath 3.0.0 STU3 aggregate functions `sum()`, `avg()`, `max()`, and `min()` (empty input yields the empty collection; `sum`/`avg` require numeric items and `max`/`min` compare numeric and string items with comparison-operator semantics), shipped as a declared, documented exception: `Capability.current` keeps the FHIRPath 2.0.0 target and reports this subset in `trial_use` under the marker `stu3-aggregate-functions`;
@@ -201,58 +159,15 @@ The [feature matrix](docs/feature-matrix.md) is the executable-scope companion t
 This is not yet a complete FHIRPath engine. The following remain deferred or host-dependent:
 
 - complete FHIRPath 2.0 conformance; the checked-in importer covers only the pinned official subset;
-- broader FHIR R4 metadata such as primitive extensions, resource-level type tests (`Observation is Resource`/`DomainResource`), `ofType()`, and FHIR R5 model adapters; FHIR R4 `is`/`as` over a resolved choice value's logical type (e.g. `Quantity`) is supported, but terminology and `resolve()` remain host-dependent; and
+- broader FHIR R4 metadata such as primitive extensions, resource-level type tests (`Observation is Resource`/`DomainResource`), and FHIR R5 model adapters; FHIR R4 `is`/`as` over a resolved choice value's logical type (e.g. `Quantity`) is supported by default; terminology and `resolve()` remain host-dependent; and
 - temporal arithmetic with Date/Time/DateTime and Quantity/Duration, including calendar-duration arithmetic;
-- advanced conversion, math, string, regular-expression, and navigation functions, and the general-purpose `aggregate()` function;
+- advanced conversion, math, string, regular-expression, and navigation functions;
 - complex literals and additional standard value types;
 - standard environment variables beyond explicitly supplied external constants;
 - FHIRPath 3.0 STU3 features beyond the shipped `sum`/`avg`/`max`/`min` aggregate functions; capability recognition does not enable them silently;
 - network I/O from pure evaluation and global evaluator state; and
-- production support guarantees, until the support matrix and release gates are complete.
-
-Unsupported operations raise `UnsupportedFeatureError`, `UnknownFunctionError`, or another specific `FHIRPath::Error`. Malformed or trailing source raises `ParseError`; the parser does not accept a valid prefix and silently ignore trailing input.
-
-## Development and verification
-
-Install development dependencies and run the complete local checks:
-
-```sh
-bundle install
-bundle exec rake test
-bundle exec rubocop
-bundle exec rake vectors
-bundle exec rake build
-bundle exec ./script/verify_gem_install.sh pkg/fhirpath-*.gem
-```
-
-The optional vector workflow is deterministic and does not require Python:
-
-```sh
-bundle exec ruby script/run_vectors.rb conformance/core.jsonl
-```
-
-It reports `pass`, `defect`, `unsupported`, `host-dependent`, and `not-run` separately. These hand-authored JSONL vectors are compatibility evidence, not a replacement for the official HL7 shared suite. See [Conformance workflow](docs/conformance.md).
-
-Coverage is opt-in and uses Ruby's standard `Coverage` library:
-
-```sh
-COVERAGE=1 bundle exec rake test
-bundle exec ruby script/check_coverage.rb coverage/summary.json
-```
-
-For a clean-checkout reproduction, use the exact commands in [CONTRIBUTING.md](CONTRIBUTING.md). CI runs the supported Ruby matrix, tests, RuboCop, vectors, package build, gem-install smoke test, and coverage report generation.
-
-## Contributing
-
-Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. New language behavior should be delivered as a small vertical slice: add a focused failing test, implement the smallest change, run the complete checks, and update the feature matrix and limitations when scope changes.
-
-Security reports should follow [SECURITY.md](SECURITY.md). Release readiness,
-versioning, publication, and remaining conformance gates are recorded in
-[`docs/release-checklist.md`](docs/release-checklist.md) and
-[`docs/releasing.md`](docs/releasing.md).
+- unqualified string escaping beyond the documented UTF-16 surrogate-pair handling.
 
 ## License
 
-This project is licensed under the [MIT License](LICENSE). The gem is still a
-pre-release and does not claim complete FHIRPath conformance; those limitations
-are independent of the license.
+[MIT](LICENSE).

data/docs/api.md

@@ -1,6 +1,6 @@
 # FHIRPath Ruby API reference
 
-Status: pre-release API contract (`0.2.0.pre1`)
+Status: pre-release API contract (`0.2.0.pre7`)
 
 This document describes the Ruby-native public surface. It is a contract for this project, not a claim of source compatibility with `fhirpath-py`, `fhirpath.js`, HAPI, or Firely.
 
@@ -31,7 +31,7 @@ Passing a `String` to `parse` never freezes that string: `parse` retains an inte
 ```ruby
 program = FHIRPath.compile(
   expression,
-  model: nil,
+  model: :r4,
   capability: FHIRPath::Capability.current,
   functions: FHIRPath::FunctionRegistry.standard
 )
@@ -41,10 +41,9 @@ Returns a frozen `FHIRPath::CompiledExpression`. Parsing happens once; each `eva
 
 `compile` likewise never freezes the caller's source `String`: it snapshots the expression internally. Mutating the string you passed after calling `compile` does not change the compiled program, and passing an already-frozen string works normally.
 
-`model` defaults to `FHIRPath::PlainModel`. Pass `model: :r4` (or `model: 'R4'`)
-to select the dependency-free `FHIRPath::FHIR::R4::ModelProvider`. Passing a
-provider object remains supported for custom model adapters. `functions` is an
-immutable function registry snapshot.
+`model` defaults to `FHIRPath::FHIR::R4::ModelProvider`. Pass `model: nil`
+to opt out and use `FHIRPath::PlainModel` for model-independent navigation,
+or pass a custom provider object.
 
 ### `FHIRPath.evaluate`
 
@@ -53,7 +52,7 @@ result = FHIRPath.evaluate(
   resource,
   expression,
   variables: {},
-  model: nil,
+  model: :r4,
   capability: FHIRPath::Capability.current,
   functions: FHIRPath::FunctionRegistry.standard,
   options: {},
@@ -70,7 +69,7 @@ The `resource` argument may be an already-parsed Hash/Array (used directly, neve
 | Input type | Behavior |
 |------------|----------|
 | `Hash` / `Array` | Used directly (never re-serialized) |
-| String starting with `{` or `[` (after whitespace) | Parsed as JSON document via `JSON.parse` once per call; malformed JSON raises `JSONInputError` (code `invalid_json`) |
+| String starting with `{` or `[` (after whitespace) | Parsed as JSON document via `JSON.parse` once per call; malformed JSON raises `JSONInputError` code `invalid_json` |
 | Any other String | Treated as a singleton FHIRPath string value (never parsed) |
 
 ```ruby
@@ -122,6 +121,26 @@ FHIRPath.evaluate({}, "%enabled", variables: { enabled: false }).to_a
 
 `host:` is reserved for explicit host services. Pure evaluation does not perform network I/O.
 
+### Model selection
+
+By default, `FHIRPath.evaluate` uses the R4 model adapter, which enables
+choice navigation (e.g. `Observation.value` resolves over `valueString`,
+`valueQuantity`, etc.) and logical-type `is`/`as` metadata. Pass
+`model: nil` to use `PlainModel` for plain Hash/Array navigation without
+FHIR choice resolution:
+
+```ruby
+observation = { 'resourceType' => 'Observation', 'valueString' => 'high' }
+
+# R4 model (default) — choice navigation
+FHIRPath.evaluate(observation, 'Observation.value').to_a
+# => ['high']
+
+# Plain model — direct property lookup only
+FHIRPath.evaluate(observation, 'Observation.value', model: nil).to_a
+# => []
+```
+
 ### Host constants
 
 External constants can be supplied by an immutable `HostServices` configuration:
@@ -169,7 +188,7 @@ The project defines `FHIRPath::TypeError` inside its namespace; callers should q
 
 For the implemented string operators, `+` concatenates two singleton strings but propagates an empty operand, while `&` treats each empty operand as the empty string. Thus `'a' + {}` is empty, whereas `'a' & {}` returns `['a']`. String escapes follow the FHIRPath `\\uXXXX` form; valid UTF-16 surrogate pairs are combined, and unknown forms such as `\\U0001F600` are rejected with `ParseError`.
 
-Most current public results are ordinary Ruby values. `FHIRPath::Value::*` and `FHIRPath::TypeInfo` provide extension boundaries for semantic values and model metadata. The dependency-free R4 adapter supports JSON choice navigation for `Observation.value[x]`; a resolved choice value carries its FHIR logical type (for example `Quantity` for `valueQuantity`), so `is`/`as` type operators can test it. `Collection` may carry positional model-type metadata alongside items without changing item values; the metadata is attached when a collection is produced directly by model navigation, and operators that rebuild collections (such as `union`) do not yet propagate it. Date/time, quantity, broader type-aware model behavior (resource hierarchies, `ofType()`), and other FHIR releases remain deferred.
+Most current public results are ordinary Ruby values. `FHIRPath::Value::*` and `FHIRPath::TypeInfo` provide extension boundaries for semantic values and model metadata. By default, the engine uses the dependency-free R4 adapter, which supports JSON choice navigation for `Observation.value[x]`; a resolved choice value carries its FHIR logical type (for example `Quantity` for `valueQuantity`), so `is`/`as` type operators can test it. Pass `model: nil` to use `PlainModel` for model-independent navigation without choice metadata. `Collection` may carry positional model-type metadata alongside items without changing item values; the metadata is attached when a collection is produced directly by model navigation, and operators that rebuild collections (such as `union`) do not yet propagate it. Date/time, quantity, resource hierarchy and recursive resource-type `is`/`as`, and other FHIR releases remain deferred. `ofType()` is supported for filtering by built-in types and FHIR resource types recorded during navigation (see the feature matrix for the exact supported scope).
 
 ## Custom functions
 

data/docs/feature-matrix.md

@@ -1,6 +1,6 @@
 # Feature and capability matrix
 
-Status: `0.2.0.pre3`; target release: FHIRPath `2.0.0`; publication contract: [`support-matrix.md`](support-matrix.md)
+Status: `0.2.0.pre7`; target release: FHIRPath `2.0.0`; publication contract: [`support-matrix.md`](support-matrix.md)
 
 This matrix is deliberately conservative. `Supported` means the behavior is exercised by the Ruby test suite or the checked-in vector corpus. `Deferred` means callers should expect a structured unsupported/unknown error. `Host-dependent` requires an adapter or injected service that is not shipped here.
 
@@ -45,9 +45,9 @@ This matrix is deliberately conservative. `Supported` means the behavior is exer
 | FHIR primitive extension accessor (`._<name>`) | Supported | `test/primitive_extensions_test.rb`; returns the underlying `{value, extension}` container or empty per FHIRPath 2.0.0 |
 | Quantity/UCUM | Supported | `test/quantity_test.rb` and `test/quantity_edge_cases_test.rb`; immutable Decimal-backed quantities, case-sensitive dimensional conversion for the explicitly bounded dependency-free subset (`m`/`cm`/`mm`/`km`, `g`/`kg`/`mg`/`Mg`/`ug`/`ng`, `L`/`mL`/`ML`/`uL`, `mol`/`mmol`/`umol`, `s`/`min`/`h`, and products/quotients such as `mmol/L`); unsupported units are rejected rather than treated as dimensionless, incompatible calculations and mixed Quantity/scalar addition return empty, same-dimension Quantity division returns a Decimal ratio, derived-unit composition such as Quantity×Quantity or `km/h` remains deferred, and system/code metadata is preserved without changing unit equality |
 | Advanced conversion/math/string/regex | Deferred | not in standard registry |
-| FHIR R4 model adapter (`model: :r4`) | Supported | `test/r4_model_test.rb`; dependency-free `FHIRPath::FHIR::R4::ModelProvider` |
-| FHIR R4 `Observation.value[x]` logical navigation | Supported | R4 choice vectors; `valueQuantity` and `valueString` resolve through `value`, absent choice is empty |
-| FHIR R4 logical-type `is`/`as` over resolved choice values | Supported | `test/r4_type_operator_test.rb` and R4 choice vectors; navigation records the resolved choice variant's FHIR logical type (`Quantity`, `string`, ...) and `is`/`as` test against it; empty-in/empty-out and PlainModel (no model metadata) behavior are covered; the type is recorded for collections produced directly by navigation (operators that rebuild collections, such as `union`, do not yet propagate it); resource-level type tests and `ofType()` remain deferred |
+| FHIR R4 model adapter (default) | Supported | `test/r4_model_test.rb`; dependency-free `FHIRPath::FHIR::R4::ModelProvider`; omitted `model:` defaults to R4, `model: nil` selects PlainModel |
+| FHIR R4 `Observation.value[x]` logical navigation | Supported | R4 choice vectors; `valueQuantity` and `valueString` resolve through `value`, absent choice is empty; this is now the default behavior when no `model:` is passed |
+| FHIR R4 logical-type `is`/`as` over resolved choice values | Supported | `test/r4_type_operator_test.rb` and R4 choice vectors; navigation records the resolved choice variant's FHIR logical type (`Quantity`, `string`, ...) and `is`/`as` test against it; empty-in/empty-out and PlainModel (no model metadata) behavior are covered; the type is recorded for collections produced directly by navigation (operators that rebuild collections, such as `union`, do not yet propagate it); resource hierarchy and recursive resource-type `is`/`as` remain deferred; this is now the default behavior when no `model:` is passed |
 | FHIR R5 model adapter | Deferred | no R5 provider |
 | Broader FHIR choice elements and primitive extensions | Host-dependent | first R4 slice only covers `Observation.value[x]` |
 | `resolve()` and terminology | Host-dependent | requires injected host services |

data/docs/release-checklist.md

@@ -2,7 +2,7 @@
 
 This checklist is the gate for a reusable public release. It is intentionally explicit because a successful gem build is not the same as a legally releasable or conformant package.
 
-## Current assessment (`0.2.0.pre3`)
+## Current assessment (`0.2.0.pre7`)
 
 | Criterion | Status | Evidence / rationale |
 |---|---|---|
@@ -44,7 +44,7 @@ Verification on Homebrew Ruby 4.0.4 (the repository's local bundle contains nati
 - `bundle exec rake test`: 50 runs, 191 assertions, 0 failures, 0 errors, 0 skips;
 - `bundle exec rubocop`: 31 files inspected, no offenses;
 - `bundle exec rake vectors`: 8 total, 8 pass, 0 defect, 0 unsupported, 0 host-dependent, 0 not-run;
-- `bundle exec rake build`: `pkg/fhirpath-0.2.0.pre3.gem` built;
+- `bundle exec rake build`: `pkg/fhirpath-0.2.0.pre7.gem` built;
 - `script/verify_gem_install.sh`: clean isolated install and `1 + 2` smoke test passed;
 - `COVERAGE=1 bundle exec rake test` plus `script/check_coverage.rb`: 88.9% (829/932 executable lines); and
 - `git diff --check`: passed.

data/docs/support-matrix.md

@@ -1,6 +1,6 @@
 # Release support matrix
 
-Status: `pre-release` (`0.2.0.pre3`)
+Status: `pre-release` (`0.2.0.pre7`)
 
 This is the release-facing support matrix. It is deliberately narrower than
 "FHIRPath-compatible": every supported claim must have executable evidence, and
@@ -17,7 +17,7 @@ The detailed behavior table is maintained in [`feature-matrix.md`](feature-matri
 | License | MIT |
 | Supported Ruby CI matrix | Ruby `3.2`, Ruby `3.3` |
 | Model support | Model-independent plain Ruby Hash/Array/object navigation plus dependency-free FHIR R4 JSON adapter |
-| FHIR model releases | R4 (`4.0.1`), selectable with `model: :r4` |
+| FHIR model releases | R4 (`4.0.1`) is the default; pass `model: nil` to select PlainModel for model-independent navigation |
 | Trial-use features | One declared exception only: the FHIRPath 3.0 STU3 aggregate functions `sum`/`avg`/`max`/`min`, shipped by default in the standard registry (see [Declared STU3-subset exception](#declared-stu3-subset-exception)) |
 
 The packaged gem repeats the target and capability declaration in gem metadata:

data/lib/fhirpath/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module FHIRPath
-  VERSION = '0.2.0.pre6'
+  VERSION = '0.2.0.pre7'
   # A stable release requires the complete release gate to be deliberately
   # promoted. Keep pre-release status explicit while the shared-suite and
   # model-adapter work remains incomplete.

data/lib/fhirpath.rb

@@ -37,14 +37,14 @@ module FHIRPath
       ['R4'].freeze
     end
 
-    def compile(expression, model: nil, capability: Capability.current,
+    def compile(expression, model: :r4, capability: Capability.current,
                 functions: FunctionRegistry.standard)
       parsed = expression.is_a?(ParsedExpression) ? expression : parse(expression, capability: capability)
       CompiledExpression.new(parsed: parsed, model: resolve_model(model, capability),
                              functions: functions, capability: capability)
     end
 
-    def evaluate(resource, expression, variables: {}, model: nil,
+    def evaluate(resource, expression, variables: {}, model: :r4,
                  capability: Capability.current, functions: FunctionRegistry.standard,
                  options: {}, host: nil)
       compiled = if expression.is_a?(CompiledExpression)
@@ -56,7 +56,7 @@ module FHIRPath
       compiled.evaluate(resource, variables: variables, host: host, options: options)
     end
 
-    def evaluate_first(resource, expression, variables: {}, model: nil,
+    def evaluate_first(resource, expression, variables: {}, model: :r4,
                        capability: Capability.current, functions: FunctionRegistry.standard,
                        options: {}, host: nil)
       evaluate(resource, expression, variables: variables, model: model,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fhirpath
 version: !ruby/object:Gem::Version
-  version: 0.2.0.pre6
+  version: 0.2.0.pre7
 platform: ruby
 authors:
 - Nicco Reyes