dry-validation-rust 0.1.0.pre5

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