haveapi-rust-client 0.30.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 21033d06951c8de41c052be7cf6d615912ba7fb83e450ed07d360d46691fc880
+  data.tar.gz: ace71e7005ca64d911730b47a67795ec64338097bcc3f4116976460c70d5de6b
+SHA512:
+  metadata.gz: a0de1d3a4d6c2d282e4b68012a43147e3ca865251fe03f179853db9d9b6fe3963fc9950b1a7585457c274a08bb351cc4d073f33385e764649ce4d81e15b96743
+  data.tar.gz: 55cebb5a66f6592549da6ccfdb9384d83812373485656e2c2f907da4c3e33618686e5f0fec2b36c2b29af79d1b6fefa7d6d3e126fea6827b719e5d3abbf98226

data/Gemfile.lock

@@ -0,0 +1,200 @@
+PATH
+  remote: ../ruby
+  specs:
+    haveapi-client (0.30.0)
+      activesupport (>= 7.0)
+      highline (~> 3.1)
+      json
+      require_all (~> 2.0.0)
+      rest-client (~> 2.1.0)
+      ruby-progressbar (~> 1.13.0)
+
+PATH
+  remote: .
+  specs:
+    haveapi-rust-client (0.30.0)
+      haveapi-client (~> 0.30.0)
+      tomlrb (~> 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (8.1.4)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.1.3)
+    concurrent-ruby (1.3.8)
+    connection_pool (3.0.2)
+    diff-lcs (1.6.2)
+    domain_name (0.7.20261007)
+    drb (2.2.3)
+    hana (1.3.7)
+    highline (3.1.2)
+      reline
+    http-accept (1.7.0)
+    http-cookie (1.1.6)
+      domain_name (~> 0.5)
+    i18n (1.15.2)
+      concurrent-ruby (~> 1.0)
+    io-console (0.9.4)
+    json (2.21.2)
+    json_schemer (2.5.0)
+      bigdecimal
+      hana (~> 1.3)
+      regexp_parser (~> 2.0)
+      simpleidn (~> 0.2)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    mcp (0.25.0)
+      json_schemer (>= 2.4)
+    mime-types (3.7.0)
+      logger
+      mime-types-data (~> 3.2025, >= 3.2025.0507)
+    mime-types-data (3.2026.1013)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    netrc (0.11.0)
+    parallel (1.28.0)
+    parser (3.3.12.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    regexp_parser (2.13.1)
+    reline (0.7.0)
+      io-console (~> 0.5)
+    require_all (2.0.0)
+    rest-client (2.1.0)
+      http-accept (>= 1.7.0, < 2.0)
+      http-cookie (>= 1.0.2, < 2.0)
+      mime-types (>= 1.16, < 4.0)
+      netrc (~> 0.8)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    simpleidn (0.3.0)
+    tomlrb (2.0.5)
+      racc (~> 1.4)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.3.0)
+      unicode-emoji (~> 4.3)
+    unicode-emoji (4.3.0)
+    uri (1.1.2)
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  haveapi-client!
+  haveapi-rust-client!
+  rake
+  rspec
+  rubocop (~> 1.85.0)
+  rubocop-rspec
+
+CHECKSUMS
+  activesupport (8.1.4) sha256=891dd3fe43c4fc8391934b237b1189bb1f661c932a84a840043db9d46a4e80df
+  ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  bigdecimal (4.1.3) sha256=61ebe1e5e559bdc3cc6f2c0ee7f427321fc838f59611c294356eb04d6e21cf66
+  bundler (4.0.23) sha256=407ba8a1d928f412847f819aa5f8b6aef7c59fb51feb517112af8a165487287b
+  concurrent-ruby (1.3.8) sha256=b2f1be836e968ccc78ccfce277ea79c72a88633f22306782c16ff23fb415d1e1
+  connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  domain_name (0.7.20261007) sha256=0976c6ab837dbde991b433d03acc38fdb91fa8839df31a1ed75ce0318dc0441c
+  drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
+  hana (1.3.7) sha256=5425db42d651fea08859811c29d20446f16af196308162894db208cac5ce9b0d
+  haveapi-client (0.30.0)
+  haveapi-rust-client (0.30.0)
+  highline (3.1.2) sha256=67cbd34d19f6ef11a7ee1d82ffab5d36dfd5b3be861f450fc1716c7125f4bb4a
+  http-accept (1.7.0) sha256=c626860682bfbb3b46462f8c39cd470fd7b0584f61b3cc9df5b2e9eb9972a126
+  http-cookie (1.1.6) sha256=ba4b82be64de61dc281243dac70e3c382c45142f20268ed9276a3670c93feaa9
+  i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
+  io-console (0.9.4) sha256=a403304f32928ee85e56d457b4612ca43f2703b561a3258844992bd24085fbb1
+  json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
+  json_schemer (2.5.0) sha256=2f01fb4cce721a4e08dd068fc2030cffd0702a7f333f1ea2be6e8991f00ae396
+  language_server-protocol (3.17.0.6) sha256=5ef2c0c138f8267e1bc631d3328347d354f96724b0af22f2c79516120443b7f0
+  lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  mcp (0.25.0) sha256=8acf3a5f3b60b6fd6e5d9b8ac5eb85ac504766976cbadaca182d2ffe7d795d98
+  mime-types (3.7.0) sha256=dcebf61c246f08e15a4de34e386ebe8233791e868564a470c3fe77c00eed5e56
+  mime-types-data (3.2026.1013) sha256=370f152f2a47e54e58829766492ea2cbe130a45358374b8788a6a8ad4e961c96
+  minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
+  netrc (0.11.0) sha256=de1ce33da8c99ab1d97871726cba75151113f117146becbe45aa85cb3dabee3f
+  parallel (1.28.0) sha256=33e6de1484baf2524792d178b0913fc8eb94c628d6cfe45599ad4458c638c970
+  parser (3.3.12.0) sha256=21a6d7f755d5a24dfbdc6e6b772e4e879a52e7631a88bc5a3a134606052c9828
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
+  rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
+  regexp_parser (2.13.1) sha256=5aedb6b7c35688f51e86eef17a15374dfd287c83f4ca644b2c5f3ec50a33b44b
+  reline (0.7.0) sha256=5b012d8e55dbf9d450f12bde2cf7d15ff546ae80b3f8f3b30e570d431815583d
+  require_all (2.0.0) sha256=68d7b944b0f1c9898a16f9f102b448897c06fd2781d30efec19cbcf6e2164e6a
+  rest-client (2.1.0) sha256=35a6400bdb14fae28596618e312776c158f7ebbb0ccad752ff4fa142bf2747e3
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-mocks (3.13.8) sha256=086ad3d3d17533f4237643de0b5c42f04b66348c28bf6b9c2d3f4a3b01af1d47
+  rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
+  rubocop (1.85.1) sha256=3dbcf9e961baa4c376eeeb2a03913dca5e3987033b04d38fa538aa1e7406cc77
+  rubocop-ast (1.50.0) sha256=b9ca88300da0803ee222ad20cdb30494c0a784eed06fdc35d254b06d662788db
+  rubocop-rspec (3.9.0) sha256=8fa70a3619408237d789aeecfb9beef40576acc855173e60939d63332fdb55e2
+  ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
+  securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
+  simpleidn (0.3.0) sha256=12ca730bed2f3db04d11e9bfd1bca3e11fb37f55b21eb2e9793fb5814bf54d03
+  tomlrb (2.0.5) sha256=6e9a5e70a94a723842e770fcd14c49867703500d07cd03ebb6c343138a7b4477
+  tzinfo (2.0.6) sha256=8daf828cc77bcf7d63b0e3bdb6caa47e2272dcfaf4fbfe46f8c3a9df087a829b
+  unicode-display_width (3.3.0) sha256=4b7aa66a4b11db50f6f7e98411215cd0dd10eaecb665d36eec5bcacb3fa0b613
+  unicode-emoji (4.3.0) sha256=11c02fa73290378c066bb0562cd4c87d8e1b706fbbe0059ca12746a4244de8ce
+  uri (1.1.2) sha256=89292e98eabbef6248b0a0ed5e7e398e152f83f17560023a6d94a7f492b169fb
+
+BUNDLED WITH
+  4.0.23

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Jakub Skokan
+
+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,81 @@
+# Rust client generator
+
+This Ruby generator turns a saved HaveAPI protocol 2 description into a typed,
+self-contained Rust client for one explicit API version. The generated client
+uses async reqwest by default and offers the same actions through the optional
+`blocking` feature. Ruby and HaveAPI are generation tools, not dependencies of
+the resulting Rust crate.
+
+The client contract uses edition 2024, Rust 1.95 or newer, Serde, url 2.5,
+and reqwest 0.13.5 with verified rustls TLS. Generation requires the exact
+formatter version recorded in the client configuration. New test fixtures use
+the formatter from the HaveAPI Nix shell; existing clients retain their own
+recorded formatter. A separate acceptance check verifies Rust 1.95 because the
+development compiler is newer.
+
+## Development
+
+From the HaveAPI root:
+
+```sh
+nix develop .#client-rust
+cd clients/rust
+bundle exec rspec spec/unit
+bundle exec rubocop lib bin spec/unit spec/spec_helper.rb haveapi-rust-client.gemspec
+```
+
+The component shell installs the dependencies frozen in the tracked
+`clients/rust/Gemfile.lock`. Use its Ruby interpreter with those gems; native
+gems installed by this shell cannot be loaded by a different ambient Ruby.
+The root Git hooks also need the root shell's dependencies: prepare them with
+`nix develop --command true` before committing, then commit with the declared
+Overcommit hooks enabled. Do not install gems concurrently in the same gem home.
+
+`make test-rust-unit` runs the generator specs. `make test-rust` additionally
+runs both runtime feature configurations and the generated-client protocol
+harness. Compilation, linting Rust, server integration, MSRV and packaging can
+take longer; use the development workspace's verification procedure when
+working there. Unit specs never start a server or invoke Cargo.
+
+## Generate a client
+
+Keep acquisition separate from generation:
+
+```sh
+bundle exec haveapi-rust-client fetch https://api.example.test/v1.0/ \
+  --api-version 1.0 --profile public --output schema/api-1.0.json
+bundle exec haveapi-rust-client generate --schema schema/api-1.0.json \
+  --api-version 1.0 --config generator.toml --output src/generated
+bundle exec haveapi-rust-client generate --schema schema/api-1.0.json \
+  --api-version 1.0 --config generator.toml --output src/generated --check
+```
+
+Run these commands from the consuming project with this generator available in
+its Bundler environment. The explicit URL includes the selected version.
+Neither command selects the server's default API version. Offline generation
+uses only the saved schema, generator configuration, locked Ruby dependencies,
+maintained runtime source and pinned formatter.
+
+The handwritten crate entry point is:
+
+```rust
+mod generated;
+pub use generated::*;
+```
+
+A generated action looks like
+`api.vps().update(123).hostname("example").send().await?`. The blocking client
+uses `blocking::Client` and ends the same chain in `.send()?`. Construct, use and
+drop a blocking client outside an async runtime, or put its entire lifecycle
+inside `tokio::task::spawn_blocking`. See the [runtime contract](runtime/README.md)
+for authentication, errors, deadlines and blocking restrictions.
+
+Read the [integration harness guide](spec/integration/README.md) for fixture
+setup and acceptance commands.
+
+Read [generation and snapshots](docs/generation.md) for configuration, naming,
+metadata fidelity and ownership rules, and [packaging](docs/releasing.md) before
+preparing a generator or generated-client release.
+
+The [server documentation adapter](docs/documentation.md) provides optional
+async and blocking examples for a configured published SDK profile.

data/bin/haveapi-rust-client

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+require 'haveapi/rust_client/cli'
+exit HaveAPI::RustClient::Cli.run

data/docs/documentation.md

@@ -0,0 +1,103 @@
+# Rust examples in server documentation
+
+The optional `HaveAPI::RustClient::Documentation` adapter maps a published Rust
+SDK's saved snapshot and TOML configuration to server documentation. It uses the same
+Snapshot validation, complete IR, naming scopes and types as the generator.
+Construction and rendering make no network requests and run no generator, compiler
+or formatter. The server loads its trusted local files at startup.
+
+An API operator installs the matching `haveapi-rust-client` gem and configures a
+profile before mounting the server:
+
+```ruby
+api.documentation_clients(
+  '1.0',
+  rust: {
+    snapshot_path: '/srv/api/sdk/schema/api-1.0.json',
+    generator_config_path: '/srv/api/sdk/generator.toml',
+    generator_version: HaveAPI::RustClient::VERSION
+  }
+)
+```
+
+Use the exact generator version that produced the published SDK. The profile's
+package name and package version come from `crate_name` and `crate_version` in
+that SDK's existing [generator config](generation.md). They are independent of
+the API and HaveAPI package versions. Rust imports normalize crate-name hyphens
+to underscores. Configure a profile only for an SDK that users can install; the
+examples do not publish or generate that package.
+
+The server hides both Rust variants when that API version has no Rust profile.
+Invalid configured profiles fail at startup. A configured profile can still serve examples after unrelated additions to the
+live API. Each rendered sample must match the saved route,
+HTTP method, input and output layouts, and the contracts of the parameters it
+uses. The adapter
+checks the full SDK map against the current user's filtered help and sample;
+it never recomputes names from a reduced schema or prints hidden saved defaults.
+An unavailable action, changed parameter or unsupported value produces a short
+limitation in place of code. Filesystem paths remain outside rendered output.
+
+Both variants show a complete program and Cargo dependency comments. Async
+programs use Tokio and `.send().await?`. Blocking programs enable the SDK's
+`blocking` feature and construct, use and drop the client in a synchronous
+`main`, outside async runtime threads. `HAVEAPI_BASE_URL` can override the shown
+mounted root. Authenticated actions use advertised existing credentials from
+`HAVEAPI_USER`/`HAVEAPI_PASSWORD` or `HAVEAPI_TOKEN`; authentication examples never
+invent an OAuth acquisition flow or automatically follow token challenges.
+
+Object setters preserve null, zero, false and empty strings, and leave omitted
+fields unset.
+Lists use generated `Input` structs with `InputValue` fields and
+`..Default::default()` for omitted values. GET lists and nested Custom query
+values produce limitations. The example DSL has no metadata input channel, so actions requiring metadata
+show a limitation. Responses expose
+`output`, typed `meta` and `http_status`. Fields accessed in examples must occur
+in the authorized sample. Rust provides explicit action-state calls rather
+than an automatic operation-wait helper. Request success and timeouts do not
+establish whether a server-side operation finished or was rolled back.
+
+## Verification
+
+The pure adapter specs and server renderer bridge specs run before compilation:
+
+```sh
+nix develop .#client-rust --command bash -c \
+  'cd clients/rust && bundle exec rspec spec/unit/documentation_spec.rb spec/unit/documentation_harness_spec.rb'
+nix develop .#server-ruby --command bash -c \
+  'cd servers/ruby && bundle exec rspec spec/client_examples/rust_client_spec.rb'
+```
+
+The acceptance runner extracts actual `RustAsyncClient.render` and
+`RustBlockingClient.render` source. It generates a matching temporary fixture
+SDK, compiles the emitted imports, paths, methods and types, and executes the
+programs against the existing disposable HaveAPI fixture at `/` and
+`/mounted/api/`. It adds output assertions without replacing emitted requests.
+Authentication checks compose the emitted authentication builder with the
+emitted action body. It tests both modes with the development compiler and
+Rust 1.95, including zero/false/empty/null/omitted inputs, nested Custom, lists,
+nested resources, failure branches, metadata, existing credentials and an
+action-state reference. The fixture uses local test credentials and in-memory
+data.
+
+Prepare the Rust/server environments as described in the
+[integration guide](../spec/integration/README.md). Supply absolute paths to
+the independently selected Rust 1.95 Cargo and compiler executables:
+
+```sh
+HAVEAPI_RUST_DOCUMENTATION=1 \
+HAVEAPI_RUST_MSRV_CARGO=/path/to/rust-1.95/bin/cargo \
+HAVEAPI_RUST_MSRV_RUSTC=/path/to/rust-1.95/bin/rustc \
+HAVEAPI_RUST_DOCUMENTATION_EVIDENCE=/path/to/new-evidence-directory \
+nix develop .#client-rust --command ruby clients/rust/spec/documentation/run.rb
+```
+
+The optional `HAVEAPI_RUST_DOCUMENTATION_EVIDENCE` directory retains separate
+`root` and `mounted-api` receipts: snapshot, generator TOML, Cargo manifest and
+lockfile, generated source and ownership manifest, emitted programs and selected
+tool paths/versions. Choose a fresh directory; existing mount receipts cause an
+error. Build outputs and caches remain temporary. A failed run retains whichever
+fixture artifacts were available before the failure.
+
+Ordinary unit specs do not start this runner. Temporary generated SDK/source,
+Cargo outputs and the owned server are removed by their native runner cleanup;
+failed server startup retains the integration launcher's private diagnostic log.

data/docs/generation.md

@@ -0,0 +1,149 @@
+# Snapshots and generation
+
+Each snapshot describes the surface visible to its capture profile for a single
+API version. It cannot establish that permission-filtered or plugin-specific
+resources are complete. Inventory the captured resources, actions and parameters
+and record unknown coverage explicitly. Do not combine unrelated users' schemas
+or add fixture-only descriptions to a production snapshot.
+
+## Snapshot format
+
+The saved JSON envelope contains exactly these keys:
+
+| Key | Meaning |
+| --- | --- |
+| `schema_format` | Snapshot format, currently `1` |
+| `api_version` | Explicit API version string |
+| `protocol_version` | HaveAPI protocol version, currently major `2` |
+| `source_url` | Credential-free URL of the explicit version endpoint |
+| `profile` | Non-secret capture profile label |
+| `mount_path` | Server mount root, including leading and trailing `/` |
+| `description` | Sanitized HaveAPI description |
+
+`Snapshot.canonical` sorts object keys, indents by two spaces and writes UTF-8
+with LF endings and a terminal newline. Array order remains meaningful. The
+schema SHA-256 covers those exact bytes; it identifies the generated interface
+in addition to the API version.
+
+The sanitizer removes examples, labels, descriptions, validator messages and
+protected default values. It preserves parameter and choice keys, machine
+validators, ordinary defaults, metadata, auth headers, public OAuth discovery
+and token action schemas. A field named `default`, `description` or `token`
+remains a field. Protected defaults produce diagnostics without their values;
+callers save these in separate provenance. Review remaining defaults before
+publishing a snapshot. Never save credentials, HTTP headers/cookies or login
+responses in a snapshot or provenance record.
+
+The library entry points are:
+
+```ruby
+snapshot = HaveAPI::RustClient::Snapshot.fetch(
+  url: 'https://api.example.test/v1.0/', api_version: '1.0', profile: 'public'
+)
+snapshot = HaveAPI::RustClient::Snapshot.load('schema/api-1.0.json')
+inventory = HaveAPI::RustClient::IR.new(snapshot).inventory
+HaveAPI::RustClient::Generator.new(schema: snapshot, config: config)
+  .generate(output: 'src/generated', check: true)
+```
+
+Capture tools that already hold an OPTIONS envelope can use
+`Snapshot.from_envelope(envelope, api_version:, source_url:, profile:,
+mount_path: '/', diagnostics: [])`. This applies the same sanitizer used by
+fetch. Pass a diagnostics array to retain removal notices in provenance.
+Acquisition timestamps, raw capture hashes, the source revision, resolved
+Ruby/Cargo locks and exact Rust toolchain belong in separate provenance.
+The generated ownership manifest records schema, runtime and generator-source
+digests, Ruby lock digest, configuration and the owned file inventory.
+
+## Configuration and crate scaffold
+
+`generator.toml` has these root keys:
+
+```toml
+crate_name = "example-client"
+crate_version = "0.1.0"
+license = "MIT"
+edition = "2024"
+rust_version = "1.95"
+rustfmt_version = "rustfmt 1.9.0"
+```
+
+The crate version is independent of the API version. This generator supports
+the displayed license, edition and MSRV. The formatter version above is an
+example; record the exact `rustfmt --version` output for the client's chosen
+formatter. `RUSTFMT` can select its executable. Generation rejects a version
+that differs from the configuration.
+
+`Generator#manifest_requirements` renders the initial Cargo manifest template.
+It declares serde 1 with derive, serde_json 1, url 2.5, and reqwest 0.13.5 with
+`default-features = false` and `features = ["json", "rustls"]`. Features are
+`default = []` and `blocking = ["reqwest/blocking"]`. Tokio 1 with macros and
+rt-multi-thread supports tests/examples. Commit the consuming crate's Cargo.lock.
+Regeneration checks these requirements when the output is `src/generated`
+inside an existing crate. It reports mismatches and never replaces Cargo.toml
+or other handwritten package files.
+
+## Generated interface
+
+Resource components normalize to snake_case and join with double underscores.
+For example, nested `project/task` becomes `project__task`, while the top-level
+resource `project_task` keeps that name. A flat accessor binds ancestor path
+arguments: `api.project__task(project_id).show(task_id)`. Arguments follow the
+path template's order and accept values implementing `ToString`; the runtime
+encodes each value as a single path segment. All remaining name collisions fail
+with both original schema paths. Rust keywords receive a trailing underscore.
+Action aliases use the same request and models.
+
+Action modules live at `resources::<resource_path>::<action>`. They expose
+`Input`, `Output`, `Meta` and `SPEC` where applicable. Object/hash input has a
+unique defaultable struct with public `InputValue<T>` fields. Its initial state
+is Unset. Value setters preserve zero, false and empty strings; nullable fields
+also have `_null()` setters. Omitted fields stay omitted so server defaults can
+apply. List input uses `Vec<Input>` through `.input(...)`, rather than setters
+that could ambiguously apply to multiple items.
+
+The request validates input before JSON serialization, then the runtime checks
+required, nullable and typed values before dispatch. Datetime inputs are strings
+validated using HaveAPI's ISO forms. Resource input is a nonnegative numeric ID;
+portable metadata does not describe arbitrary string primary keys. Server-side
+validators remain authoritative; the generator retains their metadata without
+attempting to translate arbitrary Ruby regular expressions into Rust.
+
+All ordinary output fields are optional, including fields marked required in
+the description, because authorization can hide them. Missing and null output
+fields both become `None`; wrong field types remain decoding errors. Extra
+fields and metadata are retained. Custom values use `serde_json::Value`.
+Associations retain their partial JSON maps and documented ID/label keys; they
+do not imply a complete Show response or trigger a network request.
+
+GET uses bracketed scalar query inputs. Explicit nullable null becomes an empty
+query value, so nullable empty strings cannot always be distinguished from null
+in GET requests. Nested Custom values and list layouts in GET queries fail
+locally. DELETE, POST, PUT and PATCH send JSON object bodies, preserving input
+and metadata namespaces. Body input supports objects and named lists, including
+nested Custom values and explicit JSON null; an empty assembled body is `{}`.
+Ordinary output `namespace=false` and unnamespaced list input are rejected
+rather than guessed. Named empty object/hash output permits the server's
+`response: {}` shortcut; missing namespaces remain errors for nonempty or list
+outputs.
+
+## Owned output and recovery
+
+The generator owns only the requested output directory. It stages and formats
+files before installation and records ownership in `.haveapi-generated.json`.
+Existing nonempty output needs this marker; foreign files and symlinks are
+refused. Regeneration removes obsolete owned files and preserves siblings such
+as the handwritten facade and Cargo.toml. Never put handwritten files inside
+the generated directory.
+
+First installation uses an atomic directory rename. Replacing nonempty output
+uses Linux `renameat2` directory exchange; hosts without that operation receive
+an error before replacement. `--check` compares a temporary candidate without
+writing the destination, its parent, or package files. A stale check exits with
+an error and leaves existing contents and timestamps intact.
+
+Keep runtime fixes in HaveAPI, regenerate each affected client from its retained
+snapshot, and release that client through its own workflow. Copied runtime
+source matches `runtime/src/runtime` byte-for-byte and has no path or Git runtime
+dependency. Reverting a client revision restores its previous generated surface;
+it cannot undo API actions that a newer client already sent.

data/docs/releasing.md

@@ -0,0 +1,61 @@
+# Packaging the Rust generator and generated clients
+
+The Ruby gem is `haveapi-rust-client` and follows HaveAPI's shared VERSION.
+`make version` updates its version, client dependency and tracked generator lock
+alongside existing components. The top-level release build includes this gem,
+and the protected publishing job uploads it after `haveapi-client`. Configure
+its RubyGems publisher before release; a new gem can use a pending publisher
+without a manual seed upload. Follow the
+[shared release procedure](../../../doc/agent-instructions/releases.md) for
+registry setup, approval, retained artifacts and recovery.
+
+Prepare its package from `clients/rust` in the component Nix shell:
+
+```sh
+bundle exec rake build
+```
+
+The gem includes Ruby/ERB sources, the executable, documentation, Ruby dependency
+lock and maintained runtime source. It excludes the private Cargo harness and
+integration fixtures. The top-level `make release` builds and inspects this gem,
+retains its checksum and source in the shared manifest, and runs an isolated
+installed-package generation check. To repeat that check against retained
+artifacts in the root Nix shell:
+
+```sh
+ruby utils/release/rust_smoke.rb dist
+```
+
+The check loads the generator from the package and verifies its copied runtime.
+Run the broader generator, runtime and generated-client checks as well.
+`make test-rust-unit` runs the quick generator specs; `make test-rust` covers
+those specs, both runtime feature configurations
+and generated-client protocol acceptance. Top-level `make test` includes that
+Rust target. Publishing a new gem version requires separate authorization and
+approval in the protected release environment; `make publish` exits without
+publishing.
+
+Generated Rust crates have their own SemVer and Cargo.lock. Their API-version
+constant and schema digest identify the target independently of the crate
+version. Adding required input, changing public types or removing actions can
+require a breaking crate release; increasing the MSRV is a deliberate release
+decision. Extra response fields and unknown choice values remain compatible
+through optional fields and open string values.
+
+The embedded runtime has no separate registry release. Its `haveapi-runtime-tests`
+Cargo package is a private development harness with `publish = false`, not an
+artifact of HaveAPI's shared version. No crates.io token is needed to release
+the generator gem. Publish a generated crate through its consuming project's
+own release procedure and registry identity.
+
+Before shipping a generated client, verify deterministic offline regeneration
+and read-only `--check`, formatting, async and blocking library/examples, protocol
+fixtures, the declared minimum Rust version and `cargo package`. Inspect the
+archive for copied runtime source and ordinary registry dependencies. No Ruby,
+HaveAPI checkout or private runtime crate should be needed to build it.
+
+A runtime source fix reaches consumers only after regeneration and release of
+each affected generated crate. Keep the prior schema, generator revision,
+lockfiles and generated revision available for recovery. Pinning a previous
+crate version can restore software behavior but cannot reverse server changes
+made by an API action.