fhirpath 0.2.0.pre1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '0759fa82ecea31aef7e8fb5ffc0c8a1fc023d834ffe49eb296d706bf42ff7ed8'
+  data.tar.gz: 0156774a1f73b8099001478f57704e8ee969738454f1019a09d398b9420aa64d
+SHA512:
+  metadata.gz: 0cd68f2b5a80fd409a066965422a067d1a0664a2bd6c65c215b82c19655a8064ec4da47a54bc4b6767d0f65f7f38ee997815d63796a9097d43df3efcfe6ad448
+  data.tar.gz: 42a9413ad029f7a5e77bbfd2e796db4d37debd2152f3f9f1c3e28d4a74100027ef56abb6a63cd2a8bc383c83519546f6d18949f8db38a3dccf73d43aa7b4747b

data/.rubocop.yml

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  Exclude:
+    - "vendor/**/*"
+
+Style/ArgumentsForwarding:
+  Enabled: false
+
+Style/SuperArguments:
+  Enabled: false
+
+Style/ReduceToHash:
+  Enabled: false
+
+Style/SelectByKind:
+  Enabled: false
+
+Style/FormatStringToken:
+  Enabled: false
+
+# The project keeps development dependencies grouped by purpose in Gemfile.
+Bundler/OrderedGems:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+# The public API and context intentionally expose the independently injectable
+# architectural boundaries described in docs/architecture.md.
+Metrics/ParameterLists:
+  Exclude:
+    - "lib/fhirpath.rb"
+    - "lib/fhirpath/evaluation_context.rb"
+    - "lib/fhirpath/conformance/importer.rb"
+
+# Lexer/parser and evaluator are intentionally cohesive in this first scaffold;
+# future slices can split them once their semantics stabilize.
+Metrics/ClassLength:
+  Exclude:
+    - "lib/fhirpath/parser.rb"
+    - "lib/fhirpath/evaluator.rb"
+    - "test/foundation_test.rb"
+    - "test/parser_hardening_test.rb"
+    - "test/subsetting_functions_test.rb"
+    - "lib/fhirpath/conformance/importer.rb"
+    - "test/conformance_pipeline_test.rb"
+
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - "lib/fhirpath/parser.rb"
+    - "lib/fhirpath/evaluator.rb"
+    - "lib/fhirpath/vector_runner.rb"
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - "lib/fhirpath/parser.rb"
+    - "lib/fhirpath/evaluator.rb"
+
+# The conformance test deliberately exercises many cases in one readable block
+# for pass/defect classification; split out per-case helpers later if needed.
+Metrics/BlockLength:
+  Exclude:
+    - "test/conformance_pipeline_test.rb"
+    - "fhirpath.gemspec"

data/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project are documented here. The project is pre-1.0; the API and supported behavior may change between releases.
+
+## [Unreleased]
+
+## [0.2.0.pre1] - 2026-09-05
+- Add the `sum()`, `avg()`, `max()`, and `min()` aggregate functions to the
+  standard registry. These are FHIRPath 3.0.0 STU3 aggregate additions
+  (published 2026-07-28) and the first STU3-subset functions this project
+  ships; they are absent from normative FHIRPath 2.0.0 and from the 3.0.0
+  ballot. Semantics follow the published 3.0.0 text where it applies: empty
+  input returns the empty collection; non-numeric items raise `TypeError` with
+  code `expected_number`; `avg()` converts Integer items to Decimal before
+  dividing and always yields a Decimal; and `max()`/`min()` reuse the
+  comparison-operator semantics so numerics compare across Integer/Decimal and
+  strings order lexicographically, with incompatible item types raising
+  `TypeError` with code `incompatible_comparison`. The 3.0.0 text requires all
+  items to be the same type; this slice records a documented deviation for
+  numeric input instead of an exception: mixed Integer/Decimal input is summed
+  in Decimal, matching the engine's numeric promotion in arithmetic and
+  equality (`1 = 1.0` and `1 + 2.5` both hold), while all-Integer input keeps
+  an Integer `sum()` result. The subset ships by default in the standard
+  registry as a declared exception: `Capability.current` keeps `fhirpath`
+  `2.0.0` and reports the marker `stu3-aggregate-functions` in `trial_use`;
+  `docs/support-matrix.md`, `docs/api.md`, and the feature matrix document the
+  exception. `count()` (normative FHIRPath 2.0.0, existence functions)
+  already existed and now has focused expression tests and checked-in vectors
+  alongside the family. No inputs are mutated and every result is a fresh
+  frozen `Collection`; the general-purpose `aggregate()` function remains
+  deferred.
+
+- Resolve the FHIR logical type of a choice value for the `is`/`as` type
+  operators when a model provider is active. `ModelProvider` gains an optional
+  `property_logical_type` accessor (safe `nil` default on the base class and
+  `PlainModel`); the R4 provider reports the resolved variant's declared type
+  from its choice metadata (`valueQuantity` -> `Quantity`, `valueString` ->
+  `string`). Navigation records that type per item on the produced collection
+  without wrapping or altering the value, so with `model: :r4`,
+  `Observation.value is Quantity` yields `[true]` and
+  `Observation.value as Quantity` passes the value through unchanged (an empty
+  collection when the cast fails). Primitive built-in type tests, empty
+  in/empty out for absent choices, and the plain-model default are unchanged.
+  `Observation is Resource`/`DomainResource` style tests and `ofType()` remain
+  deferred.
+- Add the `tail()`, `take(n)`, and `skip(n)` member functions (FHIRPath 2.0.0, subsetting functions; §5.3.5–5.3.7): `tail()` returns all but the first item and is empty for empty/singleton input; `take(n)` returns the first `min(n, size)` items, empty for `n <= 0` or empty input, and the full collection when `n` exceeds the size; `skip(n)` returns the items after the first `n`, the full collection for `n <= 0`, and empty when no items remain. `take`/`skip` require an integer `n` and raise `TypeError` with code `expected_integer` for a non-integer argument.
+- Add a dependency-free FHIR R4 model provider selectable with `model: :r4`.
+  It maps the R4 `Observation.value[x]` JSON variants `valueQuantity` and
+  `valueString` to logical `Observation.value`; an absent choice evaluates to
+  the empty collection. The provider is exposed as
+  `FHIRPath::FHIR::R4::ModelProvider` and advertised by the capability API.
+  Resource-type and release matching accept symbol/string and any-case forms.
+- Add the `last()` member function (FHIRPath 2.0.0, existence/navigation functions): it returns the last item in the input collection, an empty collection when the input is empty, and requires zero arguments.
+- Harden the external constant boundary with an injectable `ConstantProvider`, predictable `UnknownConstantError` behavior when absent, generic redacted `HostError` messages without retaining constant-provider exceptions as public causes, and no implicit provider I/O; resolve, terminology, tracing, and cache behavior remain deferred.
+- Correct numeric arithmetic with a zero right operand: `+`, `-`, `*` treat zero as a normal operand, while `/`, `div`, `mod` divide and a zero divisor returns an empty collection (never an error).
+- Correct `union` (`|`) to eliminate duplicate values from both operands using `=` equality in first-seen order, including numerically-equal integers and decimals.
+- Accept a finite JSON `Float` as a `Decimal` for comparison, equality, arithmetic, and the `is Decimal` type test; reject `NaN`/`Infinity` as non-numeric.
+- Correct `contains` so a multi-item right operand raises a singleton-required error even when the searched collection is empty, and so an empty right operand yields an empty result.
+- Correct `&` string concatenation to treat empty operands as empty strings, with regression coverage for both operators' empty-collection behavior.
+- Correct parser precedence for relational, union, and type operators to match the FHIRPath grammar.
+- Harden documentation, package verification, CI, coverage reporting, and contributor workflows.
+- Add the release support matrix, exact package capability metadata, versioning policy, and gated RubyGems/GitHub publication workflow.
+- Declare the project under the MIT License and encode the license in gem metadata.
+- Bound parser recursion: excessively nested expressions (parentheses, unary chains, function calls, indexers, and deep AST-building flat expressions) now raise `FHIRPath::ParseError` with code `nesting_depth_exceeded` instead of letting `SystemStackError` escape the `FHIRPath::Error` boundary.
+- Stop freezing the caller-owned source string: `parse`/`compile` retain an internal frozen snapshot of the expression, so mutating the caller's String afterwards does not affect the compiled program.
+
+## [0.1.0.pre1] - 2026-09-04
+
+- Added the Ruby-native parser, immutable AST, collection-first evaluator, plain model boundary, structured errors, capability object, and function registry.
+- Added path navigation, literals, arithmetic, selected comparisons, Boolean operators, indexers, filtering, existence functions, and reusable compiled expressions.
+- Added collection-aware equality/equivalence, normalized string and decimal equivalence, empty/not/all functions, string addition, union, membership, primitive type operators, comments, and strict string-escape handling.
+- 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
+[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

data/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to FHIRPath for Ruby
+
+Thanks for helping improve the Ruby implementation. It is a pre-1.0 project with a deliberately narrow supported slice, so correctness and honest scope are more important than adding a large number of names quickly.
+
+## Development setup
+
+Requirements:
+
+- Ruby 3.2 or 3.3 (the supported CI matrix);
+- Bundler; and
+- Git.
+
+From a fresh checkout:
+
+```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
+```
+
+Optional coverage:
+
+```sh
+COVERAGE=1 bundle exec rake test
+bundle exec ruby script/check_coverage.rb coverage/summary.json
+```
+
+The repository intentionally does not require Python for its runtime or vector workflow.
+
+## Change workflow
+
+1. Open or find an issue describing the behavior or documentation change.
+2. Read `docs/architecture.md`, `docs/feature-matrix.md`, and `docs/conformance.md` before changing evaluator semantics.
+3. For behavior changes, write a focused failing test first (RED), implement the smallest change (GREEN), then run the complete checks above.
+4. Add or update a vector when behavior has an independent reference or specification case.
+5. Update the README, API docs, feature matrix, limitations, and changelog when the public contract changes.
+6. Keep parser, evaluator, model, and host boundaries explicit. Do not add expression-controlled Ruby method dispatch, global evaluator state, or network I/O.
+7. Keep commits focused and do not include build output, credentials, local state, or unrelated work.
+
+## Pull requests
+
+A useful pull request explains:
+
+- the user-visible behavior and the FHIRPath rule it implements;
+- tests added, including expected RED-to-GREEN behavior where relevant;
+- vector/conformance evidence and any host-dependent exclusions;
+- supported Ruby versions exercised; and
+- documentation or compatibility impact.
+
+Before requesting review, verify `git diff --check`, `bundle exec rake test`, `bundle exec rubocop`, `bundle exec rake vectors`, `bundle exec rake build`, and the gem-install smoke test. Do not claim complete FHIRPath conformance unless the official suite and release evidence support that claim.
+
+For release work, also review [`docs/support-matrix.md`](docs/support-matrix.md),
+[`docs/release-checklist.md`](docs/release-checklist.md), and
+[`docs/releasing.md`](docs/releasing.md). Version changes must update
+`lib/fhirpath/version.rb` and the matching `CHANGELOG.md` section; do not push a
+release tag from a dirty or unreviewed checkout.
+
+## Scope and licensing
+
+The repository is licensed under the [MIT License](LICENSE), but remains
+pre-release and does not claim complete FHIRPath conformance. Do not represent
+it as a complete or production-ready engine; document compatibility evidence
+and limitations in every behavior change. See `SECURITY.md` for vulnerability
+reports.

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+# Keep development tooling out of the published gem metadata and use a current
+# RuboCop line compatible with the supported Ruby versions.
+gem 'benchmark', '~> 0.4'
+gem 'minitest', '~> 6.0'
+gem 'rake', '~> 13.0'
+gem 'rubocop', '~> 1.90.0'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicco Reyes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,218 @@
+# FHIRPath for Ruby
+
+[![CI](https://github.com/niccoreyes/fhirpath-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/niccoreyes/fhirpath-ruby/actions/workflows/ci.yml)
+[![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)
+
+A Ruby-native implementation of the [HL7 FHIRPath](https://hl7.org/fhirpath/) expression language.
+
+This repository is an intentionally small, pre-release implementation. It provides a tested compatibility slice with stable boundaries for the public API, lexer/parser, immutable AST, collections, evaluation context, plain-model navigation, a dependency-free FHIR R4 model adapter, values, structured errors, and function registration. It does not claim complete FHIRPath conformance or complete FHIR release-model support.
+
+## Status at a glance
+
+- Version: `0.2.0.pre1`
+- 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; not published to RubyGems.
+- 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 not yet published. To use a checkout:
+
+```sh
+git clone https://github.com/niccoreyes/fhirpath-ruby.git
+cd fhirpath-ruby
+bundle install
+bundle exec rake test
+```
+
+Once a release is published, the intended consumer workflow will be:
+
+```ruby
+# Gemfile
+gem "fhirpath"
+```
+
+The pre-release status and incomplete conformance scope still apply; review the
+documented limitations before using this implementation in production.
+
+## Quick start
+
+```ruby
+require "fhirpath"
+
+patient = {
+  "resourceType" => "Patient",
+  "name" => [
+    { "use" => "official", "family" => "Lovelace", "given" => ["Ada", "Augusta"] },
+    { "use" => "nickname", "given" => ["Addie"] }
+  ]
+}
+
+FHIRPath.evaluate(patient, "Patient.name.where(use = 'official').given").to_a
+# => ["Ada", "Augusta"]
+
+FHIRPath.evaluate_first(patient, "Patient.name.family")
+# => "Lovelace"
+```
+
+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`:
+
+```ruby
+observation = {
+  "resourceType" => "Observation",
+  "valueQuantity" => { "value" => 120, "unit" => "mmHg" }
+}
+
+FHIRPath.evaluate(observation, "Observation.value.value", model: :r4).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
+# => [true]
+FHIRPath.evaluate(observation, "Observation.value as Quantity", model: :r4).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,
+                 capability: ..., functions: ..., options: {}, host: nil)
+FHIRPath.evaluate_first(resource, expression, variables: {}, model: nil,
+                        capability: ..., functions: ..., options: {}, host: nil)
+```
+
+A compiled expression is immutable and reusable:
+
+```ruby
+program = FHIRPath.compile("Patient.name.family")
+program.evaluate({ "resourceType" => "Patient", "name" => [{ "family" => "Lovelace" }] }).to_a
+# => ["Lovelace"]
+program.call({ "resourceType" => "Patient", "name" => [{ "family" => "Hopper" }] }).to_a
+# => ["Hopper"]
+```
+
+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.
+
+## Supported 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`;
+- 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;
+- 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
+- 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`;
+- `$this`, `$index`, and `$total` focus variables;
+- explicitly supplied external constants through `variables:` or an injected `FHIRPath::HostServices` constant provider; and
+- immutable parse/compile boundaries with structured errors and source spans.
+
+The [feature matrix](docs/feature-matrix.md) is the executable-scope companion to this list, and the [release support matrix](docs/support-matrix.md) is the publication contract. If a behavior is not listed as supported, callers should handle a specific `FHIRPath::Error` rather than assume permissive fallback.
+
+## Explicit limitations
+
+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
+- date/time and quantity/UCUM values;
+- advanced conversion, math, string, regular-expression, and navigation functions, and the general-purpose `aggregate()` function;
+- 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).
+
+## 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.

data/Rakefile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |task|
+  task.libs << 'lib'
+  task.libs << 'test'
+  task.pattern = 'test/**/*_test.rb'
+  task.verbose = true
+end
+
+desc 'Run the checked-in compatibility vectors'
+task :vectors do
+  ruby 'script/run_vectors.rb', 'conformance/core.jsonl'
+  ruby 'script/run_vectors.rb', 'conformance/r4.jsonl'
+end
+
+task default: :test

data/SECURITY.md

@@ -0,0 +1,20 @@
+# Security policy
+
+## Scope
+
+This project evaluates expressions against caller-supplied Ruby data. The supported pure-evaluation boundary does not perform network I/O and the plain model intentionally does not dispatch arbitrary Ruby methods selected by an expression.
+
+Do not provide production credentials, personal data, or live clinical data in issues, vectors, fixtures, or pull requests.
+
+## Reporting a vulnerability
+
+Please do not disclose an exploitable vulnerability in a public issue. Use GitHub's private vulnerability reporting or security-advisory channel for this repository when available. If that channel is unavailable, contact the repository owner through GitHub and provide only the minimum reproducible details needed to triage the issue.
+
+Reports should include the affected version/commit, Ruby version, expression and fixture reduced to synthetic data, impact, and a suggested mitigation if known. Please allow time for investigation before public disclosure.
+
+## Supported versions
+
+The project is MIT-licensed but pre-release. Security fixes are evaluated
+against the current `main` branch and the latest published version, if any.
+The gem is not yet published as a production release; see
+`docs/release-checklist.md` for the remaining release gates.

data/conformance/core.jsonl

@@ -0,0 +1,39 @@
+{"id":"collection-equality-001","target":"2.0.0","expression":"left = same","resource":{"left":[1,2],"same":[1,2]},"variables":{},"expected":[true],"origin":{"suite":"fhirpath-py","commit":"19f6316","case":"manual"}}
+{"id":"collection-equivalence-001","target":"2.0.0","expression":"left ~ permuted","resource":{"left":[1,2],"permuted":[2,1]},"variables":{},"expected":[true],"origin":{"suite":"fhirpath-py","commit":"19f6316","case":"manual"}}
+{"id":"string-equivalence-001","target":"2.0.0","expression":"'ab c' ~ 'Ab  C'","resource":{},"variables":{},"expected":[true],"origin":{"suite":"fhirpath-py","commit":"19f6316","case":"manual"}}
+{"id":"empty-function-001","target":"2.0.0","expression":"{}.empty()","resource":{},"variables":{},"expected":[true],"origin":{"suite":"fhirpath-py","commit":"19f6316","case":"manual"}}
+{"id":"string-addition-001","target":"2.0.0","expression":"'a' + 'b'","resource":{},"variables":{},"expected":["ab"],"origin":{"suite":"fhirpath-py","commit":"19f6316","case":"manual"}}
+{"id":"type-operator-001","target":"2.0.0","expression":"1 as integer","resource":{},"variables":{},"expected":[1],"origin":{"suite":"fhirpath-py","commit":"19f6316","case":"manual"}}
+{"id":"string-concat-empty-001","target":"2.0.0","expression":"'a' & {}","resource":{},"variables":{},"expected":["a"],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"string-concatenation"}}
+{"id":"type-union-precedence-001","target":"2.0.0","expression":"1 as integer | 2","resource":{},"variables":{},"expected":[1,2],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"operator-precedence"}}
+{"id":"union-dedupe-001","target":"2.0.0","expression":"(1 | 1) | 2","resource":{},"variables":{},"expected":[1,2],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"union-distinct"}}
+{"id":"union-numeric-equality-001","target":"2.0.0","expression":"(1 | 1.0)","resource":{},"variables":{},"expected":[1],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"union-numeric-equality"}}
+{"id":"division-by-zero-empty-001","target":"2.0.0","expression":"5 div 0","resource":{},"variables":{},"expected":[],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"division-by-zero"}}
+{"id":"membership-empty-001","target":"2.0.0","expression":"1 in {}","resource":{},"variables":{},"expected":[false],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"membership-empty"}}
+{"id":"membership-both-empty-001","target":"2.0.0","expression":"{} in {}","resource":{},"variables":{},"expected":[],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"membership-empty-singleton"}}
+{"id":"contains-both-empty-001","target":"2.0.0","expression":"{} contains {}","resource":{},"variables":{},"expected":[],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"membership-empty-singleton"}}
+{"id":"float-as-decimal-001","target":"2.0.0","expression":"value > 1","resource":{"value":1.5},"variables":{},"expected":[true],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"decimal-literal"}}
+{"id":"last-function-001","target":"2.0.0","expression":"(1 | 2 | 3).last()","resource":{},"variables":{},"expected":[3],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"last-function"}}
+{"id":"last-function-empty-001","target":"2.0.0","expression":"{}.last()","resource":{},"variables":{},"expected":[],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"last-function"}}
+{"id":"tail-function-001","target":"2.0.0","expression":"(1 | 2 | 3).tail()","resource":{},"variables":{},"expected":[2,3],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"tail-function"}}
+{"id":"tail-function-empty-001","target":"2.0.0","expression":"{}.tail()","resource":{},"variables":{},"expected":[],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"tail-function"}}
+{"id":"take-function-001","target":"2.0.0","expression":"(1 | 2 | 3).take(2)","resource":{},"variables":{},"expected":[1,2],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"take-function"}}
+{"id":"take-function-empty-001","target":"2.0.0","expression":"{}.take(2)","resource":{},"variables":{},"expected":[],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"take-function"}}
+{"id":"skip-function-001","target":"2.0.0","expression":"(1 | 2 | 3).skip(1)","resource":{},"variables":{},"expected":[2,3],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"skip-function"}}
+{"id":"skip-function-empty-001","target":"2.0.0","expression":"{}.skip(2)","resource":{},"variables":{},"expected":[],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"skip-function"}}
+{"id":"count-function-001","target":"2.0.0","expression":"(1 | 2 | 3).count()","resource":{},"variables":{},"expected":[3],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"count-function"}}
+{"id":"count-function-empty-001","target":"2.0.0","expression":"{}.count()","resource":{},"variables":{},"expected":[0],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"count-function"}}
+{"id":"count-function-navigation-001","target":"2.0.0","expression":"g.count()","resource":{"g":[1,2,3]},"variables":{},"expected":[3],"origin":{"suite":"HL7-FHIRPath","commit":"master","case":"count-function"}}
+{"id":"sum-decimals-001","target":"3.0.0","expression":"(1.0 | 2.0 | 3.0 | 4.0 | 5.0).sum()","resource":{},"variables":{},"expected":[15.0],"origin":{"suite":"FHIRPath-3.0.0","commit":"2026-07-28","case":"sum-spec-example"}}
+{"id":"sum-integers-001","target":"3.0.0","expression":"(1 | 2 | 3).sum()","resource":{},"variables":{},"expected":[6],"origin":{"suite":"FHIRPath-3.0.0","commit":"2026-07-28","case":"sum-integers"}}
+{"id":"sum-mixed-numeric-001","target":"3.0.0","expression":"(1 | 2.5).sum()","resource":{},"variables":{},"expected":[3.5],"origin":{"suite":"FHIRPath-3.0.0","commit":"2026-07-28","case":"sum-mixed-numeric-decision"}}
+{"id":"sum-empty-001","target":"3.0.0","expression":"{}.sum()","resource":{},"variables":{},"expected":[],"origin":{"suite":"FHIRPath-3.0.0","commit":"2026-07-28","case":"sum-empty-decision"}}
+{"id":"avg-decimals-001","target":"3.0.0","expression":"(5.5 | 4.7 | 4.8).avg()","resource":{},"variables":{},"expected":[5.0],"origin":{"suite":"FHIRPath-3.0.0","commit":"2026-07-28","case":"avg-spec-example"}}
+{"id":"avg-integers-001","target":"3.0.0","expression":"(1 | 2 | 3 | 4).avg()","resource":{},"variables":{},"expected":[2.5],"origin":{"suite":"FHIRPath-3.0.0","commit":"2026-07-28","case":"avg-integers-as-decimal"}}
+{"id":"avg-empty-001","target":"3.0.0","expression":"{}.avg()","resource":{},"variables":{},"expected":[],"origin":{"suite":"FHIRPath-3.0.0","commit":"2026-07-28","case":"avg-empty"}}
+{"id":"min-numeric-001","target":"3.0.0","expression":"(2 | 4 | 8 | 6).min()","resource":{},"variables":{},"expected":[2],"origin":{"suite":"FHIRPath-3.0.0","commit":"2026-07-28","case":"min-spec-example"}}
+{"id":"min-strings-001","target":"3.0.0","expression":"('b' | 'a' | 'c').min()","resource":{},"variables":{},"expected":["a"],"origin":{"suite":"FHIRPath-3.0.0","commit":"2026-07-28","case":"min-strings"}}
+{"id":"min-empty-001","target":"3.0.0","expression":"{}.min()","resource":{},"variables":{},"expected":[],"origin":{"suite":"FHIRPath-3.0.0","commit":"2026-07-28","case":"min-empty"}}
+{"id":"max-numeric-001","target":"3.0.0","expression":"(2 | 4 | 8 | 6).max()","resource":{},"variables":{},"expected":[8],"origin":{"suite":"FHIRPath-3.0.0","commit":"2026-07-28","case":"max-spec-example"}}
+{"id":"max-strings-001","target":"3.0.0","expression":"('b' | 'a' | 'c').max()","resource":{},"variables":{},"expected":["c"],"origin":{"suite":"FHIRPath-3.0.0","commit":"2026-07-28","case":"max-strings"}}
+{"id":"max-empty-001","target":"3.0.0","expression":"{}.max()","resource":{},"variables":{},"expected":[],"origin":{"suite":"FHIRPath-3.0.0","commit":"2026-07-28","case":"max-empty"}}

data/conformance/official-r4-core.json

@@ -0,0 +1,15 @@
+{
+  "schema": "fhirpath-conformance-v1",
+  "suite": "FHIR/fhir-test-cases",
+  "suite_commit": "2d595a506a91eeb311ab787f5fe2c8806be3cfd1",
+  "target": "2.0.0",
+  "model": "plain",
+  "source": "r4/fhirpath/tests-fhir-r4.xml",
+  "fixture_root": "r4",
+  "cases": [
+    "testPrecedence2",
+    "testUnion1",
+    "testPlus4",
+    "testLiteralTrue"
+  ]
+}

data/conformance/r4.jsonl

@@ -0,0 +1,6 @@
+{"id":"r4-observation-value-string-001","target":"2.0.0","model":"R4","expression":"Observation.value","resource":{"resourceType":"Observation","status":"final","valueString":"high"},"variables":{},"expected":["high"],"origin":{"suite":"HL7-FHIR","commit":"R4","case":"Observation.value[x]","url":"https://hl7.org/fhir/R4/observation.html"}}
+{"id":"r4-observation-value-quantity-001","target":"2.0.0","model":"R4","expression":"Observation.value.value","resource":{"resourceType":"Observation","status":"final","valueQuantity":{"value":120,"unit":"mmHg"}},"variables":{},"expected":[120],"origin":{"suite":"HL7-FHIR","commit":"R4","case":"Observation.value[x]","url":"https://hl7.org/fhir/R4/observation.html"}}
+{"id":"r4-observation-value-absent-001","target":"2.0.0","model":"R4","expression":"Observation.value","resource":{"resourceType":"Observation","status":"final"},"variables":{},"expected":[],"origin":{"suite":"HL7-FHIR","commit":"R4","case":"Observation.value[x] absent","url":"https://hl7.org/fhir/R4/observation.html"}}
+{"id":"r4-observation-value-quantity-is-001","target":"2.0.0","model":"R4","expression":"Observation.value is Quantity","resource":{"resourceType":"Observation","status":"final","valueQuantity":{"value":120,"unit":"mmHg"}},"variables":{},"expected":[true],"origin":{"suite":"HL7-FHIR","commit":"R4","case":"Observation.value is Quantity (type operator over choice logical type)","url":"https://hl7.org/fhir/R4/observation.html"}}
+{"id":"r4-observation-value-quantity-as-001","target":"2.0.0","model":"R4","expression":"Observation.value as Quantity","resource":{"resourceType":"Observation","status":"final","valueQuantity":{"value":120,"unit":"mmHg"}},"variables":{},"expected":[{"value":120,"unit":"mmHg"}],"origin":{"suite":"HL7-FHIR","commit":"R4","case":"Observation.value as Quantity passes the value through (type operator over choice logical type)","url":"https://hl7.org/fhir/R4/observation.html"}}
+{"id":"r4-observation-value-absent-type-001","target":"2.0.0","model":"R4","expression":"Observation.value as Quantity","resource":{"resourceType":"Observation","status":"final"},"variables":{},"expected":[],"origin":{"suite":"HL7-FHIR","commit":"R4","case":"Observation.value as Quantity empty in empty out (absent choice)","url":"https://hl7.org/fhir/R4/observation.html"}}