haveapi 0.30.1 → 0.31.0

data/benchmarks/shell.nix

@@ -0,0 +1,21 @@
+let
+  pkgs = import (builtins.fetchTree {
+    type = "github";
+    owner = "NixOS";
+    repo = "nixpkgs";
+    rev = "02c087f3fe673c9e317f206a627cb6b910336dbe";
+    narHash = "sha256-IoNisKcGbUjdd45qCqywGMCYmZ5EnkxezvLII0FWwNA=";
+  }) { };
+in
+pkgs.mkShell {
+  name = "haveapi-benchmarks";
+  packages = with pkgs; [ ruby_3_4 git gnumake pkg-config openssl libffi ];
+  LD_LIBRARY_PATH = pkgs.lib.makeLibraryPath [ pkgs.stdenv.cc.cc.lib ];
+  shellHook = ''
+    for name in ''${!BUNDLE@}; do unset "$name"; done
+    unset RUBYOPT RUBYLIB RUBYGEMS_GEMDEPS
+    export GEM_HOME="''${HAVEAPI_BENCHMARK_GEM_HOME:-${toString ./.}/.gems}"
+    export GEM_PATH="$GEM_HOME:${pkgs.ruby_3_4}/lib/ruby/gems/3.4.0"
+    export PATH="$GEM_HOME/bin:$PATH"
+  '';
+}

data/doc/client-examples.md

@@ -2,20 +2,23 @@
 
 The Ruby server renders examples from the current user's API description.
 JavaScript and TypeScript examples cover callback and async clients; Python
-examples cover sync and async clients. These clients need no server configuration.
+examples cover sync and async clients. These clients need no server
+configuration.
 Ruby, PHP, CLI, curl and HTTP examples are also available. A sample
 that a client cannot represent shows a limitation instead of dropping input or
 inventing a successful result.
 
-Go and Rust tabs require a profile for a generated SDK. Their package versions
-are independent of HaveAPI and the API version. Without a profile, the server
+Go, Rust and generated TypeScript tabs require a profile for a generated SDK.
+Their package versions are independent of HaveAPI and the API version. Without a
+profile, the server
 hides those clients from the overview and all initialization, authentication and
 action panels. Install the matching generator gem only when configuring its
-profile; ordinary servers do not depend on either generator.
+profile; ordinary servers do not depend on these generators.
 
 ## Configure a generated SDK
 
-Register profiles before mounting the server. For an SDK that matches the current
+Register profiles before mounting the server. For an SDK that matches the
+current
 API, configure its package identity:
 
 ```ruby
@@ -25,25 +28,34 @@ api.documentation_clients('1.0',
   },
   rust: {
     crate_name: 'widget-client'
+  },
+  typescript: {
+    package_name: '@example/widget-client'
   }
 )
 api.mount('/api/')
 ```
 
 `generator_version` defaults to the server's `HaveAPI::VERSION`. Install the
-optional `haveapi-go-client` or `haveapi-rust-client` generator gem at that
-version. An explicit `generator_version` requires the installed generator to
-report that version; it never downloads one. It is independent of the SDK and
-API versions.
-
-At the end of mount, the server builds one private structural model per configured
-API version. The model includes authentication resources, routes and changes from
+matching generator in the server's Ruby environment: `haveapi-go-client`,
+`haveapi-rust-client`, or the source-distributed `haveapi-typescript-client`.
+See the [TypeScript generator guide](../clients/typescript/README.md) for its
+setup. An explicit `generator_version` requires the installed generator to
+report
+that version; the server never downloads one. This version is independent of the
+SDK and API versions.
+
+At the end of mount, the server builds one private structural model per
+configured
+API version. The model includes authentication resources, routes and changes
+from
 post-mount hooks, so canonical names and parent arguments use the complete API
 declaration. The private copy excludes examples, prose and parameter defaults.
 HTML requests use the current user's authorized description, fields and samples;
 they never expose the private model or its initialization diagnostics. Without
-a configured profile, the server loads no optional generator and shows no Go or
-Rust panels.
+a configured profile, the server loads no optional generator and hides the Go,
+Rust and generated TypeScript panels. The callback and async TypeScript
+examples remain separate and need no profile.
 
 Automatic profiles assume that the installed SDK matches the current server's
 generation contract. A package name or version does not prove its contents.
@@ -53,8 +65,9 @@ schema override below when the SDK represents an older or restricted API.
 
 ### Optional SDK versions and sources
 
-Set `module_version: 'v1.2.3'` for Go or `crate_version: '1.2.3'` for Rust when a
-specific package version is needed. Omit the field or use nil to let the user's
+Set `module_version: 'v1.2.3'` for Go, `crate_version: '1.2.3'` for Rust or
+`package_version: '1.2.3'` for TypeScript when a specific package version is
+needed. Omit the field or use nil to let the user's
 package manager select a release. The server does not query a registry or claim
 to have resolved a version. Omitted versions produce these installation hints:
 
@@ -63,15 +76,25 @@ go get example.org/widget/client@latest
 cargo add widget-client
 # Blocking Rust variant:
 cargo add widget-client --features blocking
+npm install @example/widget-client haveapi-client@0.30.2
 ```
 
 Go resolves `@latest` by its normal rules. Cargo selects a compatible release
 according to its resolver, manifest and toolchain; existing lockfiles still
 apply. Explicit Cargo versions remain version requirements, without an added
-exact `=` pin. Latest selection can change over time; supply a version to control
+exact `=` pin. Latest selection can change over time; supply a version to
+control
 the selection. Cargo never receives a literal `version = "latest"`. Rust
 examples also show their Tokio and serde_json requirements.
 
+TypeScript accepts ordinary lowercase npm package names, including scoped names,
+and optional concrete SemVer versions. Tags, version ranges, Git URLs, local
+paths
+and custom factories are not profile options. Configure a package that users can
+install; the server does not check its availability or publish it. Generated
+snippets use the package's public `createClient` export and the published
+`haveapi-client` 0.30.2 runtime.
+
 For an unpublished Rust SDK, supply an HTTPS Git URL and a full commit SHA:
 
 ```ruby
@@ -118,13 +141,20 @@ api.documentation_clients('1.0',
     snapshot_path: '/srv/widget-sdk/api-1.0.snapshot.json',
     generator_config_path: '/srv/widget-sdk/generator.toml',
     generator_version: '0.30.0'
+  },
+  typescript: {
+    package_name: '@example/widget-client',
+    package_version: '1.2.3',
+    snapshot_path: '/srv/widget-sdk/api-1.0.snapshot.json',
+    generator_version: '0.30.0'
   }
 )
 ```
 
 Paths name trusted absolute local files. `description_path` is Go's saved
-machine-readable description, not HTML. `snapshot_path` is Rust's saved schema
-and capture metadata. They select an exact SDK shape in place of the current
+machine-readable description, not HTML. For Rust and TypeScript, `snapshot_path`
+selects the saved schema and capture metadata. These files select an exact SDK
+shape in place of the current
 server declaration. Keep the files private and retain them with the SDK release.
 
 Rust's legacy `generator_config_path` supplies the crate name/version and full
@@ -138,7 +168,8 @@ Saved files are read and validated during registration. Automatic models are
 initialized at the end of mount. Missing files or generators, actual generator
 version mismatches, unknown fields, conflicting identities and invalid schemas
 fail startup. Mounting also rejects unavailable API versions and mismatched Rust
-snapshot versions. Failed mounting publishes no profiles and leaves no usable
+and TypeScript snapshot versions. Failed mounting publishes no profiles and
+leaves no usable
 server application. An older explicitly pinned generator can serve a suitable
 legacy file profile, but automatic/inline Rust mode requires the new factory
 interface and never guesses a fallback.
@@ -161,8 +192,21 @@ Existing renderer positional constructors and `init`, `auth(method, desc)` and
 The registry binds a request-local `HaveAPI::ClientExample::Context` through
 `with_context`. It holds the selected version, URLs including the API mount,
 the filtered description, and the current resource, action and sample.
-`context.with(...)` creates another frozen copy without freezing the server's
-shared description.
+Construction copies and freezes Hash, Array and String data without freezing
+the caller's containers. Each request owns its description snapshot.
+`context.with(...)` creates a distinct frozen context, sharing unchanged fields
+by identity and normalizing only explicitly supplied fields. A shallow-frozen
+input container still needs copying; explicitly supplying an existing owned
+Hash,
+Array or String also copies it. Renderers must treat context-owned data as
+read-only.
+
+The profile is a shared reference; registered profiles and their adapters are
+frozen separately. Other object types retain their existing reference semantics,
+so context construction is not an arbitrary-object deep-freezing contract.
+Subclasses of `Context` continue deriving through their constructors, preserving
+custom initialization and extra keywords; the sharing optimization applies to
+the exact base class.
 
 Renderers may return a String or nil through their existing methods. New
 renderers return either `{status: :code, code: source}` or
@@ -173,13 +217,21 @@ overview and every panel before rendering.
 
 Generated-client adapters belong to their generator gems and consume context
 readers without depending on the server gem. They resolve names using the
-complete private generator model and never run a compiler, formatter or generator
-in an HTML request. Keep adapter rendering read-only: configured adapters are frozen
-and shared, while filtered contexts are copied per request.
+complete private generator model and never run a compiler, formatter or
+generator
+in an HTML request. Keep adapter rendering read-only: configured adapters are
+frozen
+and shared, while authorized description snapshots belong to individual
+requests.
+Derived contexts within one request share unchanged owned data. Supplying a
+resource, action or sample still copies that supplied subtree, so a resource
+with
+many actions can remain costly to render.
 
 ## Verification
 
-`make test-documentation` checks renderers, contexts, profiles, rendered HTML and
+`make test-documentation` checks renderers, contexts, profiles, rendered HTML
+and
 local assets. Prepare the component bundles and JavaScript development
 dependencies with `make release-deps` first. The target builds the JavaScript
 package before compiling TypeScript examples against its public declarations;
@@ -190,6 +242,107 @@ against the real request encoder. It requires the locked Python environment
 prepared by `make release-deps` and is included in `make test`. The ordinary
 Ruby renderer checks run without the Python package environment.
 
+Deterministic context and HTML regressions run in the ordinary server suite.
+They check description sharing, allocation growth and isolation between users
+without a wall-clock threshold. The Rust adapter suite separately checks that
+normalization avoids unrelated description descendants.
+
+### Documentation benchmark
+
+Prepare the server bundle in its declared Nix environment, then run the opt-in
+harness from the repository root:
+
+```sh
+nix develop .#server-ruby --command bash -c \
+  'make --no-print-directory benchmark-documentation > /tmp/documentation.json'
+```
+
+The target synchronizes shared documentation before running the harness.
+Standard
+output is JSON; shell/dependency preparation happens before the redirected
+command.
+No network server, database, generated SDK compilation or formatter is involved.
+The synthetic fixture uses Basic users `admin` and `member`, both with the local
+test password `fixture-only`.
+
+Defaults measure two shapes with eight ordinary actions each: eight resources
+with one action, and one resource with eight actions. Each ordinary action also
+has a privileged sample; the first resource has an additional admin-only action.
+Context lanes derive a prepared parent with a changed profile or a constant
+small
+sample. The HTML lane performs one real Rack request per trial, with all
+available
+dynamic renderer panels. Use a minimal smoke run or a larger repeated campaign:
+
+```sh
+make benchmark-documentation \
+  BENCHMARK_DOCUMENTATION_ARGS='--shape resources --size 1 --warmup 0 --trials 1 --iterations 1'
+make benchmark-documentation \
+  BENCHMARK_DOCUMENTATION_ARGS='--shape both --size 64 --samples 2 --parameters 8 --warmup 2 --trials 7 --iterations 500' \
+  > /tmp/documentation-large.json
+```
+
+Run these `make` commands inside the prepared shell. `--shape custom --resources
+N --actions N` controls both dimensions independently; `--lanes context`
+isolates
+derivation and `--lanes html` isolates requests. `--user member` selects
+restricted
+help. `--help` lists all options. `--rust` enables the fixture's matching Rust
+profile, includes both Rust variants in HTML, and adds separate async/blocking
+action and authentication adapter lanes. It requires the optional generator's
+Ruby dependencies to be available; ordinary benchmark runs need none of them.
+Prepare both component environments using `nix develop .#server-ruby` and
+`nix develop .#client-rust`. The server bundle alone does not activate the Rust
+dependencies. In the top-level Nix shell, combine the prepared local gem stores:
+
+```sh
+env -u RUBYOPT -u RUBYLIB -u BUNDLE_BIN_PATH -u BUNDLE_GEMFILE \
+  -u BUNDLE_LOCKFILE -u BUNDLE_PATH -u BUNDLE_FROZEN -u BUNDLER_SETUP \
+  GEM_PATH="$PWD/.gems:$PWD/clients/rust/.gems:$(ruby -e 'puts Gem.default_dir')" \
+  make benchmark-documentation BENCHMARK_DOCUMENTATION_RUBY=ruby \
+  BENCHMARK_DOCUMENTATION_ARGS='--rust --shape both --size 8 --warmup 1 --trials 3 --iterations 100' \
+  > /tmp/documentation-rust.json
+```
+
+This command runs outside Bundler and records the gem versions actually
+activated. Retain that list alongside both component locks and use the same
+prepared inputs for both revisions. Missing optional dependencies fail the run;
+Rust lanes are never silently omitted. See the
+[Rust adapter guide](../clients/rust/docs/documentation.md#verification).
+
+Every lane reports each trial and the median wall seconds, process CPU seconds
+and allocated objects, with the operation count per trial. Wall time uses a
+monotonic clock. A full GC runs before each trial, outside its timer; GC
+triggered
+by the measured work remains included. Mount/profile construction has separate
+setup metrics. Ownership construction, description selection, warmups, output
+validation, hashing and JSON serialization are outside lane measurements.
+Reports include fixture dimensions, renderer IDs, profile mode, Ruby runtime,
+host, Git HEAD/status/diff digest, loaded source digests, dependency versions
+and
+available lockfile/harness/fixture digests. HTML and Rust outputs include
+status, bytes and
+SHA-256; failed or missing output causes a nonzero exit.
+
+For a before/after comparison, retain one exact harness and fixture and point
+them at each implementation with `--source-root /absolute/checkout`. Set up
+equivalent dependencies and runtime first. An explicit `--source-revision LABEL`
+can supplement the detected HEAD and is required for an exported source tree.
+Retain exact heads, commands, raw JSON, lock/input identities and host identity.
+Compare dimensions, renderer modes, statuses, bytes and body digests before
+comparing medians. Context `description_shared` deliberately distinguishes the
+old copying implementation. Investigate any output difference; record exact
+volatile-field normalization if needed rather than silently dropping mismatches.
+
+These measurements describe the synthetic workload on the recorded host. They
+do not establish production latency. The opt-in harness has no timing threshold;
+the [paired endpoint performance suite](performance.md) supplies required
+quick/weekly CI timing, allocation and query gates, including documentation
+OPTIONS and both HTML shapes. It retains baseline/self noise and blocks
+inconclusive results. Ownership, traversal and allocation regressions cover this
+failure class, while concentrated-resource costs and other future regressions
+still need representative measurements.
+
 Each client also has acceptance commands that check executable snippets against
 installed packages or a generated SDK. These use
 rendered source against disposable fixtures; syntax checks alone do not

data/doc/performance.md

@@ -0,0 +1,310 @@
+# Endpoint performance checks
+
+The Ruby performance suite sends real Rack requests through routing,
+authentication, authorization, typed validation and serialization. It covers
+public, Basic and token requests, valid and invalid typed input, nested resources,
+lists, SQLite pagination and eager loading, and documentation OPTIONS/HTML.
+Deterministic specs check response contracts, isolation, allocation growth and
+query/authorization counts. Paired timing runs compare exact baseline and
+candidate sources with one neutral harness and third-party dependency graph.
+
+These are synthetic in-process workloads. SQLite results describe the fixture's
+query behavior; they do not measure production database, network server or
+vpsAdmin latency. The checks detect specific regressions and do not guarantee
+every future performance characteristic.
+
+## Local commands
+
+The benchmark has its own third-party tool bundle and pinned Nix shell in
+`servers/ruby/benchmarks/`. This keeps contributor Nix updates separate from the
+calibrated measurement runtime. Prepare the ordinary frozen bundle once:
+
+```sh
+export HAVEAPI_BENCHMARK_GEM_HOME="$PWD/servers/ruby/benchmarks/.gems"
+nix-shell servers/ruby/benchmarks/shell.nix --run '
+  set -e
+  gem install bundler --version 4.0.23 --no-document
+  BUNDLE_IGNORE_CONFIG=1 BUNDLE_FROZEN=1 BUNDLE_PATH__SYSTEM=1 \
+    BUNDLE_GEMFILE="$PWD/servers/ruby/benchmarks/Gemfile" bundle _4.0.23_ install
+'
+```
+
+The tool Gemfile installs no HaveAPI package. Its tracked lock is an application
+lock; component library locks remain local contributor inputs. Launch the runner
+outside Bundler so both exported sources use the same Ruby and gem paths. The
+shell clears inherited Bundler settings, `RUBYOPT`, `RUBYLIB` and
+`RUBYGEMS_GEMDEPS`.
+
+Run deterministic specs in the prepared contributor shell with
+`make test-performance`. For a comparison, keep the neutral harness in a candidate
+checkout containing both exact Git objects. Export the baseline and candidate
+separately, retain their archive hashes and manifests, and run `make doc` in each
+exported root. Then run from the candidate checkout:
+
+```sh
+nix-shell servers/ruby/benchmarks/shell.nix --run '
+  make performance PERFORMANCE_ARGS="--baseline-root /absolute/baseline --baseline-sha BASELINE_FULL_SHA --candidate-root /absolute/candidate --candidate-sha CANDIDATE_FULL_SHA --profile quick --budgets servers/ruby/benchmarks/performance_budgets.json --output /absolute/new-evidence-directory"
+'
+```
+
+Replace paths and full 40-character lowercase SHAs. Use `--profile weekly` for
+the expanded workload. The runner checks the exact calibrated Ruby and available
+dependency versions before timing, then requires each worker's complete activated
+graph to match the weekly calibration. Source and loaded-file checks and
+response validation must also pass. An unsupported declaration or runtime change
+requires a separately reviewed environment migration; it does not update the
+reference or budgets.
+
+To reclassify retained samples without making requests:
+
+```sh
+make performance-compare \
+  PERFORMANCE_ARGS='--input /absolute/evidence/samples.json --budgets servers/ruby/benchmarks/performance_budgets.json --output /absolute/new-comparison-directory'
+```
+
+The commands invoke `servers/ruby/benchmarks/endpoints.rb run` and `compare`
+directly. `run` retains `samples.json`, `report.json` and process diagnostics.
+`compare` reads compact samples format version 2; unsupported versions are
+rejected without conversion. `report.json` retains the original measurement's
+`harness_sha256`. Its `comparison` metadata identifies policy
+`per-revision-response-stability-v1`, the loaded comparator file's SHA-256 and
+the SHA-256 of the exact consumed `samples.json` bytes. Error reports retain
+these identities when available; they omit unavailable measurement/input fields
+instead of identifying old measurements with the current harness. The existing
+`budget_sha256` identifies the budget. Replaying samples classifies the recorded
+measurements under the identified comparison policy. It makes no requests and
+leaves the original result unchanged.
+`report.json` contains source/profile identity, overall outcome and per-workload
+results, without raw samples or response bodies.
+Exit codes are 0 for a pass
+or an inconclusive timing result, 1 for a regression and 3 for errors, including
+missing workloads, invalid or unstable responses, inputs or provenance. An
+inconclusive report remains explicitly inconclusive; a successful process exit
+does not establish a measured performance pass. Deterministic failures and regressions block CI.
+Keep the original evidence and diagnose failures or insufficient timing signal;
+there is no automatic retry loop or baseline update.
+
+## Timing and work gates
+
+Quick workloads include seven API cases, SQLite page/includes cases, and
+documentation OPTIONS plus both HTML shapes at size 8. List and includes quick
+cases use 32 rows; pagination uses page size 32 over 128 rows. Weekly adds
+member/admin variants, larger payloads, list/includes output up to 1,024 rows,
+page size 32 over up to 10,000 SQLite rows, documentation shapes at size 16 and
+Rust async/blocking action/authentication examples. An output of 1,024 rows uses
+an unpaginated relation; it is not an invalid request above the pagination limit.
+
+Both profiles also render complete Rust-enabled HTML pages for admin and member
+users. Quick uses 16 resources; weekly uses 32. Each resource has four actions,
+two samples per action and four parameters. These cases validate the full page,
+Rust panels, authorization boundaries and operation counts. They use relative
+allocation and deterministic checks without inventing fixed-reference allocation
+ceilings for the new shapes. Existing calibrated workload budgets remain intact.
+
+These shapes exercise complete pages with several megabytes of HTML, so a
+single request provides substantial measurement work. The weekly shape doubles
+the resource count. Actual batch durations and output sizes belong in each
+run's evidence; these synthetic shapes do not define production latency targets.
+
+| Measurement policy | Quick | Weekly |
+| --- | --- | --- |
+| Baseline request work per batch | 1 second | 2 seconds |
+| Minimum adequate observed batch | 750 ms | 1.5 seconds |
+| Baseline/self pairs | 3 | 3 |
+| Baseline/candidate pairs | 5 | 7 |
+| Required agreement | 4 of 5 | 6 of 7 |
+| Relative wall/CPU regression budget | 20% | 10% |
+| Minimum detectable batch increase | 50 ms | 50 ms |
+
+A baseline pilot selects a common count of 1–100,000 requests for both revisions.
+One bounded calibration adjustment can increase an undersized baseline batch.
+Reports retain observed duration, chosen count, adjustment and any cap limitation;
+a capped batch below the adequacy threshold is insufficient timing evidence.
+Cheap workloads have two warmup batches of about 100 ms each, outside the
+measurement. If the baseline pilot already meets the profile's work target with
+one expensive request, both revisions use count 1 and no extra request warmups.
+That case measures the first complete request after equivalent fixture setup;
+the candidate cannot choose a different warmup policy.
+
+Wall and process CPU time are compared separately after normalization per request.
+The minimum detectable increase is the larger of the profile's relative budget
+and 50 ms divided by the common request count. Paired baseline/self observations
+retain the measured noise. A consistent increase beyond the budget and noise
+fails. Reports distinguish ordinary variation from insufficient timing signal.
+Inconclusive timing remains labeled as such; it does not trigger automatic
+workflow retries. The agreement rules are engineering thresholds, not statistical
+confidence levels.
+
+Candidate order alternates. Setup, mount, schema, seeds, token issuance, reset,
+response parsing/digests and counter checks stay outside the timed loop. GC
+remains enabled, including collections triggered by measured requests. A
+30-second watchdog surrounds each request batch, including pilot and warmups.
+This also bounds every individual request without instrumenting the cheap request
+loop. It is supplementary runaway protection, not a regression budget. Setup has
+a separate 120-second timeout. Supervision records source, workload and phase and terminates
+and reaps stuck workers.
+
+Within each measurement or warmup, the worker validates each distinct raw body
+once for that scenario and retains an immutable proof of its parsed values and
+output semantics. Every operation still checks the raw digest and exact bytes,
+HTTP status and content type, called index, and execution/authorization/query
+records. A hash collision cannot reuse a proof. Proofs are discarded at the
+sample boundary and never shared between users, scenarios or source revisions.
+Samples retain metrics, one uniform validated counter record with its operation
+count, and distinct response examples with occurrence counts and raw bodies.
+Replay checks those counts, counters, examples and raw/canonical identities,
+including comparison mode, verified own version and source/environment/inputs.
+It compares canonical response identities and occurrence totals across samples
+from the same verified source SHA. Both columns of a baseline/self pair belong
+to the baseline SHA. JSON map order may vary; raw byte stability is not required.
+It does not retain request order or independently reprove each live
+authorization/counter check.
+The compact artifact is a summary, not an execution transcript.
+
+Responses may differ between baseline and candidate without failing or skipping
+the performance comparison. Each workload reports `raw_changed` and
+`canonical_changed`, together with baseline/candidate bytes per request and
+their byte and percentage changes. These diagnostics use the
+occurrence-weighted output distributions from baseline/candidate pairs only;
+baseline/self pairs do not affect the size comparison. Reports retain no raw
+bodies. Response growth alone does not fail the comparison or change its timing
+and allocation limits. Equal response lengths do not prove correctness. The CI
+step summary shows these diagnostics beside wall, CPU, allocation and overall
+outcomes, including regressions and inconclusive timing.
+
+Allocation growth above baseline median plus the larger of 10% or 32 objects
+per request fails. Additional fixed-reference ceilings use measured accepted
+counts with 25% headroom plus 32 objects/request. Exact SQL query and required
+authorization counts prevent a fast but incomplete operation from passing.
+Scaling bounds reflect actual output work; growing responses need not allocate
+a constant amount. Budget changes require measured justification and review.
+Missing or uncalibrated budgets for the existing calibrated workloads fail rather
+than disabling the gate.
+
+Both profiles use the recorded weekly Rust dependency closure as their expected
+runtime identity. Quick includes the Rust manifests, gemspec and loaded
+dependencies. Both profiles retain the benchmark Gemfile, lock and shell bytes
+and hashes. Baseline and candidate must match that environment exactly;
+unavailable or changed identities fail. The shared
+comparison entry point activates the recorded native JSON 2.21.2 before its
+first require, including in unbundled workers. A newer visible or already loaded
+JSON must not silently replace that dependency; a missing or conflicting version
+fails during activation. Historical
+quick allocation calibration and all existing reference/budget bytes are retained
+unchanged, without claiming that the original quick calibration loaded Rust.
+
+The root, Ruby server and Rust generator development Gemfiles declare JSON
+2.21.2 so fresh setup installs the recorded native dependency. Comparisons
+accept only that exact declaration change in these three files. They retain
+the original manifest contents, hashes and declaration evidence, then compare
+normalized contents. Replay verifies the transformation from the retained raw
+inputs. Other dependency requirements and manifest contents must match.
+
+## GitHub workflow and baseline selection
+
+The `servers/ruby performance` workflow runs on pushes, ordinary pull requests,
+manual dispatch and Sunday at 03:00 UTC. It always creates the `Performance gate`
+aggregate check. Relevant-path detection happens after event resolution, inside
+the workflow; an irrelevant valid change can succeed without running benchmarks.
+Source/dependency/fixture/budget/workflow/flake changes trigger measurement.
+Missing event/source evidence fails even when no relevant path can be established.
+
+| Event | Candidate | Baseline |
+| --- | --- | --- |
+| Pull request | Exact event head SHA | Merge-base of head and exact event base SHA |
+| Existing branch push, quick | Exact event `after` | Exact nonzero event `before`, on every branch |
+| New branch push, quick (zero `before`) | Exact event `after` | Merge-base with captured exact default-branch SHA |
+| Weekly | Exact scheduled default-branch event SHA | Fixed accepted reference below |
+| Manual with a complete explicit pair | Supplied full candidate SHA | Supplied full baseline SHA |
+| Manual without either SHA | Captured default SHA | Fixed accepted reference below |
+
+The immutable accepted reference is
+`b85ec364057f536940d689b09e612512ffffaf82`. Required ancestry is checked. The
+reference and budgets never move automatically. Deleted branches, malformed or
+missing commits, unavailable new-branch fallback, partial manual pairs and equal
+endpoints fail. PRs use the head commit, never the synthetic merge commit. An
+existing branch push uses `before`, never `HEAD^` or a guessed fallback. A quick
+push can compare a nonancestor before/after pair after a force push; its exact
+event pair is carried through all ancestry guards. Direct CLI use of that
+exception requires `--push-event selection.json` from the event resolver. Other
+PR, manual and weekly ancestry restrictions remain. Relevance uses the direct
+before/after tree diff, including the benchmark setup files.
+The weekly profile always requires that fixed baseline, including an explicit
+manual pair. An explicit quick pair may select another ancestor.
+
+### Maintained 0.30 release comparisons
+
+The original fixed reference remains the measured baseline for weekly runs.
+Its maintenance counterpart is
+`8b7abc097db49893da9cc8fa4395648901fec71d`. The resolver and direct runner accept
+this one nonliteral ancestry relationship only when the counterpart is a literal
+candidate ancestor and the complete binary tree delta from the original reference
+equals the published 0.30.1 metadata commit
+`1c3c98f0d77e0b23c8da1a8937f25c5799864a3b` relative to its parent. They verify
+the exact four trees and canonical full-index delta hash, retain both raw diffs
+and bind the receipt to
+the candidate SHA. Cherry-pick trailers do not establish this proof. A different
+mapping needs a new review; the reference and budget calibration never change.
+Diff rendering uses full blob IDs and explicit formatting options, independent
+of repository-dependent abbreviation and user diff display settings. Ordinary
+master ancestry is checked before probing the maintenance mapping, so a master
+clone does not need maintenance objects for that path.
+Unrelated direct quick baselines still fail. Existing maintenance branch pushes
+use their exact pushed pair; new branches retain the captured-default fallback
+and reason. A `haveapi-0.30` push still requires verified maintenance lineage.
+
+Both sources in a maintenance comparison use the prepared benchmark environment.
+In addition to the JSON preparation rule above, these comparisons normalize the
+shared `0.30.x` patch identity, matching local Ruby component VERSION assignments
+and exactly synchronized internal `haveapi-client` requirements. All remaining
+bytes in dependency manifests, gemspecs and Ruby requirements must match, as must
+the resolved third-party runtime graph and benchmark lock bytes. Source `flake.nix` and `flake.lock` remain raw provenance
+with source hashes; they do not supply the benchmark runtime and may differ.
+Every other supported declaration remains strict. The consumed benchmark shell
+and lock are retained separately and must match across workers. Raw manifest
+contents and hashes remain bound to each verified source tree alongside their
+normalized hashes. Replay
+recomputes the transformation and rejects missing, inconsistent or changed inputs.
+
+The HTML comparison may normalize the own-version segment of the documentation
+templates' `https://webui.haveapi.org/v<own-version>/#...` anchor hrefs and
+the version in the exact framework-generated HaveAPI footer. The footer must
+occur once and match the verified source's own VERSION; literal examples, other
+footer text and URLs remain exact. Validation runs after the timed loop. Complete
+raw bodies, byte counts and hashes remain in the samples, together with the
+normalized comparison digest and source version. Replay checks these again from
+the raw body. This normalization applies only to the HTML documentation workloads
+on the proven maintenance lineage. JSON/API
+values, other URLs and hosts, example code, authorization markers, panels and all
+other output are not normalized. Cross-revision differences remain diagnostic;
+within-revision stability and raw/canonical integrity still apply.
+
+The workflow uses ephemeral GitHub-hosted Ubuntu workers, `contents: read`,
+disabled checkout credential persistence, ordinary `pull_request` events and no
+secrets, publication context or PR comments. The comparison job has a hard
+15-minute quick limit and 45-minute weekly limit. Measured page sizes and sample
+counts must leave room for preparation, ordinary workloads and evidence
+validation within those limits. Actual hosted campaign duration requires its own
+run receipt; the page probe alone does not prove it. A timeout blocks and needs
+diagnosis. Superseded runs are cancelled only within
+the same event/branch or PR concurrency group.
+
+Success, regression, inconclusive and preparation-failure artifacts are retained
+for 30 days. They include event selection, exact SHAs and source trees/archive
+hashes, matched dependency manifests, resolved locks, runtime/input graphs, raw
+samples, reports, process diagnostics and runner exit. The aggregate rejects
+failed, cancelled or unexpectedly skipped required work and requires the retained
+report. A completed comparison can retain inconclusive timing diagnostics while
+its deterministic checks pass; the report keeps that distinction visible.
+Repository rules determine whether this aggregate check is required for merging;
+the workflow does not change branch protection or repository permissions.
+
+A newly added workflow's manual dispatch may be unavailable until its definition
+exists on the default branch. Preserve a dispatch refusal and run the same weekly
+CLI locally if needed; disclose that hosted weekly execution remains unverified.
+Workflow enablement alone is not a reason to integrate source into the default
+branch. Push verification still checks the exact published candidate.
+
+The separate [documentation benchmark](client-examples.md#documentation-benchmark)
+remains available for diagnosis and custom page shapes. Its JSON trials/medians
+are useful measurements; the paired endpoint runner owns required timing gates.

data/haveapi.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |s|
   s.required_ruby_version = ">= #{File.read('../../.ruby-version').strip}"
 
   s.add_dependency 'activesupport', '>= 7.1'
-  s.add_dependency 'haveapi-client', '~> 0.30.1'
+  s.add_dependency 'haveapi-client', '~> 0.31.0'
   s.add_dependency 'i18n', '>= 1.6', '< 2'
   s.add_dependency 'json'
   s.add_dependency 'mail'