dry-validation-rust 0.1.0.pre5-aarch64-linux

data/docs/SUPPORT_MATRIX.md

@@ -0,0 +1,66 @@
+# Support matrix
+
+This matrix describes the public support target for each planned gem line. It
+does not widen the implemented API surface; feature support remains documented
+in [COMPATIBILITY.md](COMPATIBILITY.md).
+
+## Versioned targets
+
+| Gem line | Ruby    | Rust MSRV | Platforms                                          | Upstream reference                           | Status |
+| -------- | ------- | --------- | -------------------------------------------------- | -------------------------------------------- | ------ |
+| 0.1.x    | 3.3-3.5 | 1.75      | Source build; all CI workflows use the pinned MSRV | `dry-validation` 1.11.1, `dry-schema` 1.16.0 | alpha  |
+| 0.2.x    | TBD     | TBD       | Native gems under evaluation                       | pinned before beta                           | beta   |
+
+## Support policy
+
+- `Dry::Validation::Rust::Contract` is the primary supported API for the
+  `0.1.x` line.
+- Familiar dry-validation-style syntax is supported only for the compatible
+  subset covered by tests and documented in [COMPATIBILITY.md](COMPATIBILITY.md).
+- Exact compatibility mode owns upstream-like require paths and constants. It
+  is experimental, opt-in, and must run in a process isolated from upstream
+  `dry-validation` and `dry-schema`.
+- Runtime support means source builds and test coverage for the listed matrix,
+  not precompiled native gems unless a later row explicitly says so.
+
+## Semantic versioning policy
+
+Releases follow [Semantic Versioning 2.0.0](https://semver.org/). The version
+in `Dry::Validation::Rust::VERSION` is authoritative for the Ruby gem. A
+release must use at least the bump shown below; multiple changes use the
+largest applicable bump.
+
+Before 1.0, a breaking change to a supported surface requires the next minor
+line (for example, `0.1.x` to `0.2.0`). From 1.0 onward, it requires the next
+major line. This preserves the `0.1.x` side-by-side API promise while keeping
+the eventual stable-release policy conventional.
+
+| Change type                                                                                      | Minimum version bump                         |
+| ------------------------------------------------------------------------------------------------ | -------------------------------------------- |
+| Backwards-compatible bug fix, documentation correction, or internal native implementation change | Patch (`0.x.y`)                              |
+| New backwards-compatible Ruby predicate or schema feature                                        | Minor (`0.x.0`)                              |
+| Addition of a supported precompiled platform gem                                                 | Minor (`0.x.0`)                              |
+| Increase to the documented Rust MSRV                                                             | Minor (`0.x.0`)                              |
+| Removal of a supported platform, Ruby version, or precompiled platform gem                       | Next minor before 1.0; major from 1.0 onward |
+| Incompatible change or removal in the documented public side-by-side Ruby API                    | Next minor before 1.0; major from 1.0 onward |
+| Native ABI-incompatible change, including an incompatible Magnus or CRuby ABI support change     | Next minor before 1.0; major from 1.0 onward |
+
+The compatibility shim is experimental and excluded from the public API
+compatibility guarantee. Changes to its documented support status still follow
+this policy when they remove a listed runtime or platform target. A change to
+the Rust crate's internal implementation is not an ABI break by itself; the
+ABI rule applies when it changes which CRuby/Magnus ABI combinations the gem
+supports or requires users to rebuild incompatible native artifacts.
+
+## Product architecture note
+
+The current gem contains both the safe namespace and the exact compatibility
+shim. If the exact shim becomes expensive to maintain or its collision surface
+creates user confusion, the intended split is:
+
+```text
+dry-validation-rust
+dry-validation-rust-compat
+```
+
+No split is planned for `0.1.x` without concrete maintenance evidence.

data/docs/VERIFICATION.md

@@ -0,0 +1,128 @@
+# Verification Guide
+
+Status: living document.
+Last updated: 2026-07-29.
+
+This document describes how to verify the claims made in the project
+documentation. Every claim in ARCHITECTURE.md, COMPATIBILITY.md, and the
+README should be traceable to a command or test described here.
+
+## Quick Verification
+
+Run the full verification suite:
+
+    script/verify
+
+This executes:
+
+1. Ruby unit and integration tests (`bundle exec rake test`).
+2. Differential compatibility tests against pinned upstream.
+3. RuboCop lint.
+4. Package metadata audit.
+
+## Milestone Verification Status
+
+| Milestone                | Verification Method                                                                | Status      |
+| ------------------------ | ---------------------------------------------------------------------------------- | ----------- |
+| A — Trustworthy Baseline | `script/verify`, CI workflows, package audit                                       | ✅ Verified |
+| B — Common Schema Subset | Differential corpus (80+ cases), Rust unit tests (28), malformed-input corpus (64) | ✅ Verified |
+| C — Ordinary Rules       | `rules_test.rb`, differential rule cases                                           | 🔵 Partial  |
+| D — Performance Proof    | `benchmark/schema_throughput.rb` (no published results yet)                        | ⚪ Pending  |
+| E–G                      | Not yet applicable                                                                 | ⚪ Pending  |
+
+## Ruby-Side Evidence
+
+### Unit Tests
+
+    bundle exec rake test
+
+Covers: schema definition, coercion, predicates, rules, result API, messages,
+config, contract DSL, evaluator, path, failures, values.
+
+### Differential Compatibility
+
+    bundle exec ruby test/differential_compatibility_test.rb
+
+Runs each fixture case in an isolated subprocess against both this gem and
+pinned upstream `dry-validation` 1.11.1. Compares:
+
+- Output values (deep equality).
+- Error messages (deep equality).
+- Unsupported constructs raise the expected error class.
+
+Fixtures live in `test/fixtures/differential/`.
+
+### Unsupported Constructs
+
+Six cases verify that unsupported upstream features (hints, i18n, monads,
+macros, each with complex blocks, dry-schema composition) raise
+`UnsupportedFeatureError` rather than silently producing wrong results.
+
+## Rust-Side Evidence
+
+### Unit Tests
+
+    cd ext/dry_validation_rust && cargo test
+
+21 tests covering:
+
+- Plan deserialization and version checking (`plan.rs`).
+- Coercion edge cases: `"Infinity"`, `"NaN"`, `"1_000"`, empty strings,
+  overflow, unicode (`coercion.rs`).
+- Predicate evaluation: boundary values, type mismatches (`predicates.rs`).
+- Message interpolation: token substitution, missing tokens (`messages.rs`).
+
+### MSRV
+
+The repository pins Rust 1.75.0 in `rust-toolchain.toml`; all CI workflows use
+that exact toolchain. Verify the locked crate and its test suite explicitly
+with:
+
+    cargo +1.75.0 check --locked --manifest-path ext/dry_validation_rust/Cargo.toml
+    cargo +1.75.0 test --locked --manifest-path ext/dry_validation_rust/Cargo.toml
+
+### Clippy
+
+    cd ext/dry_validation_rust && cargo clippy -- -D warnings
+
+### Malformed-Input Resilience
+
+64-input seeded corpus in `test/malformed_input_test.rb` exercises the Rust
+engine with:
+
+- Deeply nested structures (up to depth 200, guarded by recursion limit).
+- Oversized strings (1 MB+).
+- Mixed-type arrays.
+- Null bytes and invalid UTF-8 sequences.
+- Extreme numeric values (MAX_INT, MIN_INT, MAX_FLOAT, NaN, Infinity).
+
+## Compatibility Matrix
+
+See `COMPATIBILITY.md` for the feature-by-feature matrix. Each row marked
+"✅ implemented and covered" must have at least one differential fixture case.
+
+## Benchmarks
+
+See `benchmark/schema_throughput.rb`. No published results yet — Milestone D
+will produce `docs/BENCHMARKS.md`.
+
+## CI Workflows
+
+| Workflow            | Trigger          | Purpose                                           |
+| ------------------- | ---------------- | ------------------------------------------------- |
+| `ci.yml`            | push, PR         | Tests + lint + compile                            |
+| `compatibility.yml` | push, PR, weekly | Differential suite against pinned upstream        |
+| `fuzz.yml`          | weekly, manual   | Five-minute `cargo fuzz` plan-deserialization run |
+| `package.yml`       | push, PR         | Gemspec/Cargo metadata audit                      |
+| `security.yml`      | push, PR, weekly | `cargo audit` + `bundle audit`                    |
+
+## Reproducing a Specific Claim
+
+| Claim                            | Command                                                           |
+| -------------------------------- | ----------------------------------------------------------------- |
+| "80+ differential cases pass"    | `bundle exec ruby test/differential_compatibility_test.rb`        |
+| "21 Rust unit tests pass"        | `cd ext/dry_validation_rust && cargo test`                        |
+| "MSRV build and tests pass"      | `cargo +1.75.0 check --locked … && cargo +1.75.0 test --locked …` |
+| "64 malformed inputs handled"    | `bundle exec ruby test/malformed_input_test.rb`                   |
+| "Package metadata is consistent" | `script/verify` (package audit step)                              |
+| "RuboCop clean"                  | `bundle exec rubocop`                                             |

data/dry-validation-rust.gemspec

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative 'lib/dry/validation/rust/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'dry-validation-rust'
+  spec.version = Dry::Validation::Rust::VERSION
+  spec.authors = ['Alexey Tomilov']
+
+  spec.summary = 'Experimental Rust-backed validation contracts with a dry-validation-like API'
+  spec.description = <<~DESCRIPTION
+    A hybrid Ruby/Rust validation gem that compiles a documented subset of
+    dry-validation's declarative schema DSL into a native Rust execution plan
+    while retaining Ruby rule blocks and Ruby-owned dynamic behavior.
+  DESCRIPTION
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.3'
+  spec.homepage = 'https://github.com/alex-tomilov/dry-validation-rust'
+
+  spec.files = [
+    'CHANGELOG.md',
+    'LICENSE',
+    'NOTICE.md',
+    'predicates.yml',
+    'README.md',
+    'dry-validation-rust.gemspec',
+    'rust-toolchain.toml',
+    'docs/ARCHITECTURE.md',
+    'docs/COMPATIBILITY.md',
+    'docs/FEASIBILITY.md',
+    'docs/SUPPORT_MATRIX.md',
+    'docs/VERIFICATION.md',
+    Dir['lib/**/*.rb'],
+    'ext/dry_validation_rust/Cargo.lock',
+    'ext/dry_validation_rust/Cargo.toml',
+    'ext/dry_validation_rust/extconf.rb',
+    Dir['ext/dry_validation_rust/benches/**/*.rs'],
+    Dir['ext/dry_validation_rust/src/**/*.rs']
+  ].flatten.sort
+  spec.require_paths = ['lib']
+  spec.extensions = ['ext/dry_validation_rust/extconf.rb']
+  spec.add_dependency 'bigdecimal', '>= 3.1', '< 5.0'
+  spec.add_dependency 'rb_sys', '~> 0.9'
+  spec.add_development_dependency 'memory_profiler', '~> 1.1'
+  spec.add_development_dependency 'minitest', '~> 6.0'
+  spec.add_development_dependency 'mutex_m', '~> 0.2'
+  spec.add_development_dependency 'ostruct', '~> 0.6'
+  spec.add_development_dependency 'rake', '~> 13.1'
+  spec.add_development_dependency 'rake-compiler', '~> 1.3'
+  spec.add_development_dependency 'rake-compiler-dock', '~> 1.12'
+  spec.add_development_dependency 'yard', '~> 0.9'
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+  spec.metadata['source_code_uri'] = 'https://github.com/alex-tomilov/dry-validation-rust'
+  spec.metadata['changelog_uri'] = 'https://github.com/alex-tomilov/dry-validation-rust/blob/main/CHANGELOG.md'
+  spec.metadata['documentation_uri'] = 'https://github.com/alex-tomilov/dry-validation-rust/blob/main/README.md'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/alex-tomilov/dry-validation-rust/issues'
+end

data/lib/dry/schema.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# The experimental replacement ships only the minimal schema factories needed
+# by its contract DSL. Loading this entrypoint also loads exact compatibility
+# mode; it is not the full upstream dry-schema gem.
+require 'dry/validation'

data/lib/dry/validation/rust/block_keyword_parameters.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Dry
+  module Validation
+    module Rust
+      # @api private
+      module BlockKeywordParameters
+        EMPTY = [].freeze
+
+        module_function
+
+        def extract(block)
+          block.parameters.filter_map do |kind, name|
+            name if %i[key keyreq].include?(kind)
+          end.freeze
+        end
+      end
+    end
+  end
+end

data/lib/dry/validation/rust/config.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Dry
+  module Validation
+    module Rust
+      # Configures the message backend used by compiled schemas.
+      class MessageConfig
+        BACKENDS = { yaml: YamlBackend, i18n: I18nBackend }.freeze
+
+        # @return [:yaml, :i18n, Class] the selected built-in identifier or custom backend class.
+        attr_reader :backend
+        attr_accessor :default_locale, :top_namespace, :load_paths
+
+        def initialize
+          @backend = :yaml
+          @default_locale = :en
+          @top_namespace = :dry_validation
+          @load_paths = []
+        end
+
+        # Selects a built-in backend or a custom {MessageBackend} subclass.
+        #
+        # @param backend [:yaml, :i18n, Class] backend identifier or adapter class.
+        # @raise [ArgumentError] if the backend is unsupported.
+        def backend=(backend)
+          @backend = BACKENDS.key?(backend) ? backend : validate_backend_class(backend)
+        end
+
+        def dup
+          copy = super
+          copy.load_paths = load_paths.dup
+          copy
+        end
+
+        # @api private
+        def backend_class
+          BACKENDS.fetch(backend, backend)
+        end
+
+        private
+
+        def validate_backend_class(backend)
+          return backend if backend.is_a?(Class) && backend < MessageBackend
+
+          raise ArgumentError, backend_error(backend)
+        end
+
+        def backend_error(backend)
+          "messages.backend must be :yaml, :i18n, or a MessageBackend subclass; got #{backend.inspect}"
+        end
+      end
+
+      class Config
+        attr_reader :validate_keys
+        attr_accessor :messages
+
+        def initialize
+          @validate_keys = false
+          @messages = MessageConfig.new
+        end
+
+        def validate_keys=(value)
+          @validate_keys = !!value
+        end
+
+        def dup
+          copy = super
+          copy.messages = messages.dup
+          copy
+        end
+      end
+    end
+  end
+end

data/lib/dry/validation/rust/contract/result.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Dry
+  module Validation
+    module Rust
+      class Contract
+        # The outcome of calling a {Contract}.
+        #
+        # A result contains coerced output, schema and rule failures, and the
+        # context supplied to the call. Use {#success?} or {#failure?} to check
+        # the outcome, {#to_h} to read the output, and {#errors} to inspect
+        # failures.
+        #
+        # @example Validating input and matching the output
+        #   result = UserContract.new.call(name: "Ada")
+        #
+        #   case result
+        #   in { name: String => name }
+        #     name # => "Ada"
+        #   end
+        #
+        # @see Contract#call
+        class Result
+          # @return [Schema::Result] structural validation outcome.
+          attr_reader :schema_result
+          # @return [Hash] context supplied to the contract call.
+          attr_reader :context
+
+          # Creates a result from a schema result and call context.
+          #
+          # @param schema_result [Schema::Result] structural validation outcome
+          # @param context [Hash] context supplied to the contract call
+          # @return [Result]
+          def initialize(schema_result, context = {})
+            @schema_result = schema_result
+            @context = context
+            @rule_messages = []
+          end
+
+          # Returns validated output wrapped in a Values object.
+          #
+          # @return [Values] coerced output with key and path access
+          def values
+            @values ||= Values.new(schema_result.to_h)
+          end
+
+          # Returns schema and rule errors, optionally with display options.
+          #
+          # Call {MessageSet#messages} on the returned set for its immutable
+          # message-object view, or {MessageSet#to_h} for nested error hashes.
+          #
+          # @param options [Hash] message rendering options; pass `full: true`
+          #   to include full message text
+          # @return [MessageSet] combined schema and rule errors
+          def errors(options = {})
+            set = MessageSet.new([*schema_result.messages, *@rule_messages], options)
+            options.empty? ? set : set.with(options)
+          end
+
+          # Adds a rule message before finalization and returns this result.
+          #
+          # @param message [Message] rule failure to add
+          # @return [Result] this result
+          def add_error(message)
+            @rule_messages << message
+            self
+          end
+
+          # Returns true when no schema or rule messages exist.
+          #
+          # @return [Boolean]
+          def success?
+            errors.empty?
+          end
+
+          # Returns true when at least one schema or rule message exists.
+          #
+          # @return [Boolean]
+          def failure?
+            !success?
+          end
+
+          # Returns whether a message exists at or below a path.
+          #
+          # @param key [Symbol, String, Array, Hash] key or supported path specification
+          # @return [Boolean]
+          def error?(key)
+            path = Path.parse(key)
+            errors.any? { |message| Path.prefix?(message.path, path) }
+          end
+
+          # Returns whether a schema message exists at or below a path.
+          #
+          # @param key [Symbol, String, Array, Hash] key or supported path specification
+          # @return [Boolean]
+          def schema_error?(key)
+            schema_result.error?(key)
+          end
+
+          # Returns whether a rule message exists at or below a path.
+          #
+          # @param key [Symbol, String, Array, Hash] key or supported path specification
+          # @return [Boolean]
+          def rule_error?(key)
+            path = Path.parse(key)
+            @rule_messages.any? { |message| Path.prefix?(message.path, path) }
+          end
+
+          # Returns whether a base-level rule message exists.
+          #
+          # @return [Boolean]
+          def base_rule_error?
+            @rule_messages.any?(&:base?)
+          end
+
+          # Reads a validated value by key or path.
+          #
+          # @param key [Symbol, String, Array] key or supported path specification
+          # @return [Object, nil] coerced value, if present
+          def [](key)
+            values[key]
+          end
+
+          # Returns whether validated output contains a key or path.
+          #
+          # @param key [Symbol, String, Array] key or supported path specification
+          # @return [Boolean]
+          def key?(key)
+            values.key?(key)
+          end
+
+          # Returns validated output as a Hash.
+          #
+          # @return [Hash] coerced output
+          def to_h
+            values.to_h
+          end
+
+          # Returns a diagnostic representation of output, errors, and context.
+          #
+          # @return [String]
+          def inspect
+            if context.empty?
+              "#<#{self.class}#{to_h.inspect} errors=#{errors.to_h.inspect}>"
+            else
+              "#<#{self.class}#{to_h.inspect} errors=#{errors.to_h.inspect} context=#{context.inspect}>"
+            end
+          end
+
+          # Deconstructs coerced output for Hash pattern matching.
+          #
+          # This lets a result match as though it were its output hash, such as
+          # `in { name: String => name }`. The call context is not included in
+          # this matching form; use {#deconstruct} for positional matching.
+          #
+          # @param keys [Array<Symbol>, nil] requested keys, or +nil+ for all keys
+          # @return [Hash] output entries available to the pattern
+          def deconstruct_keys(keys)
+            values.deconstruct_keys(keys)
+          end
+
+          # Supports tuple pattern matching as values and context.
+          #
+          # @return [Array<(Values, Hash)>] coerced output and call context
+          def deconstruct
+            [values, context]
+          end
+
+          # Prevents further rule-message mutation and returns this result.
+          #
+          # @return [Result] this finalized result
+          def finalize!
+            @rule_messages.freeze
+            self
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dry/validation/rust/contract/values.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Dry
+  module Validation
+    module Rust
+      class Contract
+        class Values
+          include Enumerable
+
+          # @return [Hash] validated output data.
+          attr_reader :data
+
+          # Wraps validated output data for rule and result access.
+          def initialize(data)
+            @data = data
+          end
+
+          # Reads a value by key, path, or supported multi-path specification.
+          def [](*args)
+            return data.dig(*args) if args.length > 1
+
+            spec = args.fetch(0)
+            if spec.is_a?(Hash) && spec.values.first.is_a?(Array)
+              head = spec.keys.first
+              return spec.values.first.map { |tail| Path.fetch(data, [head, *Path.parse(tail)], nil) }
+            end
+
+            value = Path.fetch(data, spec)
+            value.equal?(Path::Undefined) ? nil : value
+          end
+
+          # Returns whether data contains a key or path.
+          def key?(key)
+            Path.key?(data, key)
+          end
+
+          # Iterates through the underlying output Hash.
+          def each(&)
+            data.each(&)
+          end
+
+          # Fetches a value using Hash#fetch semantics.
+          def fetch(*, &)
+            data.fetch(*, &)
+          end
+
+          # Returns the underlying output Hash.
+          def to_h
+            data
+          end
+
+          # Supports Hash pattern matching against output data.
+          def deconstruct_keys(keys)
+            keys ? data.slice(*keys) : data
+          end
+
+          # Reports public Hash methods delegated to underlying data.
+          def respond_to_missing?(name, include_private = false)
+            data.respond_to?(name, include_private) || super
+          end
+
+          private
+
+          def method_missing(name, ...)
+            return data.public_send(name, ...) if data.respond_to?(name)
+
+            super
+          end
+        end
+      end
+    end
+  end
+end