haveapi 0.30.0 → 0.30.2

data/doc/client-examples.md

@@ -15,9 +15,96 @@ profile; ordinary servers do not depend on either generator.
 
 ## Configure a generated SDK
 
-Register profiles before mounting the server. Paths must name trusted absolute
-local files. Keep the SDK's saved description and generator configuration;
-the server does not fetch descriptions or regenerate SDKs while serving docs.
+Register profiles before mounting the server. For an SDK that matches the current
+API, configure its package identity:
+
+```ruby
+api.documentation_clients('1.0',
+  go: {
+    import_path: 'example.org/widget/client'
+  },
+  rust: {
+    crate_name: '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
+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.
+
+Automatic profiles assume that the installed SDK matches the current server's
+generation contract. A package name or version does not prove its contents.
+An older SDK can lack new actions or use different names after a collision or
+route change. Check actual SDK compatibility before advertising it; use a saved
+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
+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:
+
+```sh
+go get example.org/widget/client@latest
+cargo add widget-client
+# Blocking Rust variant:
+cargo add widget-client --features blocking
+```
+
+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
+the selection. Cargo never receives a literal `version = "latest"`. Rust
+examples also show their Tokio and serde_json requirements.
+
+For an unpublished Rust SDK, supply an HTTPS Git URL and a full commit SHA:
+
+```ruby
+api.documentation_clients('7.0',
+  rust: {
+    crate_name: 'vpsadmin-client',
+    source: {
+      git: 'https://github.com/vpsfreecz/vpsadmin-rust-client',
+      rev: 'ff876abe17e3301da62c1b6afbda055ec89db9d2'
+    }
+  }
+)
+```
+
+The dependency hint uses that source instead of a registry release:
+
+```toml
+# Cargo.toml
+vpsadmin-client = { git = "https://github.com/vpsfreecz/vpsadmin-rust-client", rev = "ff876abe17e3301da62c1b6afbda055ec89db9d2" }
+# The blocking variant also sets features = ["blocking"].
+```
+
+`source` accepts only `git` and `rev`. URLs must be absolute HTTPS without
+credentials, query strings, fragments or control characters; revisions must be
+40 hexadecimal characters. Branches, tags, local paths and custom registries are
+not supported. An explicit crate version additionally constrains the selected
+source package. The server never fetches the repository or runs these user
+installation commands. These settings do not regenerate or publish an SDK and
+do not establish that this particular SDK matches a given API surface.
+
+### Saved-schema overrides
+
+The existing file-based profiles remain supported:
 
 ```ruby
 api.documentation_clients('1.0',
@@ -33,24 +120,39 @@ api.documentation_clients('1.0',
     generator_version: '0.30.0'
   }
 )
-api.mount('/api/')
 ```
 
-Use the SDK's published package name and version. The Rust crate name and
-version come from the generator TOML configuration, which also records the
-formatter and language requirements. Go uses the import alias `client`. The
-installed generator version must match the profile. Missing files or adapters,
-unknown fields, duplicate profiles and invalid SDK schemas or configurations
-cause startup to fail. Mounting also rejects profiles for unselected API
-versions and Rust snapshots bound to another API version.
-
-An SDK profile can still serve examples after unrelated additions to the live
-API. Each example is checked against the SDK's saved action, route, layout and
-parameter contract. An unsupported or stale sample produces a limitation.
-Profiles do not expose actions, fields, defaults or samples hidden from the
-current user. The full SDK schema and local paths stay private; request
-contexts use only the current user's filtered description and the selected
-sample.
+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
+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
+packaging configuration. It is mutually exclusive with inline `crate_name` and
+`crate_version`, and can be paired with either a saved snapshot or automatic
+schema. A saved snapshot can instead use inline crate identity. `source` works
+with either identity form. The server validates the full legacy TOML; normal
+inline documentation needs no license, compiler or formatter settings.
+
+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
+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.
+
+A saved SDK can still serve examples after unrelated live additions. Each sample
+must match its saved route, layout and supplied parameter contracts; unavailable
+or stale samples show a limitation. Hidden actions, fields, defaults and samples
+remain hidden from the current user. The server never fetches descriptions,
+regenerates packages or runs a compiler/formatter during an HTML request.
+
+Old profile settings work on the new server. Inline settings require the new
+server code; rolling back that code also requires restoring compatible settings.
+Mixed server workers can show different documentation examples without changing
+wire requests or persisted data.
 
 ## Renderer extensions
 
@@ -59,8 +161,20 @@ 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
@@ -71,9 +185,12 @@ 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
-saved generator schema 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
 
@@ -88,6 +205,98 @@ 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,272 @@
+# 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
+
+Use the repository's Nix environments and prepare dependencies before running
+measurements. `nix develop .#server-ruby` prepares the server bundle; the top-level
+`nix develop` prepares contributor tools. Both profiles render full Rust-enabled
+pages and need the Ruby dependencies from `nix develop .#client-rust`. SDK
+generation, Cargo and formatting are outside these measurements. Resolved
+component lockfiles remain local library inputs and must not be committed.
+
+Run deterministic specs in the prepared top-level shell:
+
+```sh
+make test-performance
+```
+
+The runner consumes the same neutral fixtures for both implementation roots,
+using a fresh process for each sample. Keep the harness in a candidate repository
+checkout containing the exact baseline and candidate Git objects. Export both
+source revisions separately, retain their archive hashes and source manifests,
+and run `make doc` in each exported root. Do not point one process at both roots.
+Then run outside Bundler with the prepared 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 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'
+```
+
+Run inside the prepared top-level Nix shell, from the candidate checkout.
+Replace the paths and full 40-character lowercase SHAs. Use `--profile weekly`
+for the expanded workload. The runner verifies source paths, source identities,
+response contracts and dependency/runtime identities before accepting a result.
+An incompatible graph or fixture contract fails; prepare a separately reviewed
+environment/reference migration instead of mixing versions or relaxing checks.
+
+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. Historical evidence remains attributable to its
+recorded implementation. `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, wrong 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 response occurrence totals across paired samples; it does not retain
+request order or independently reprove each live authorization/counter check.
+The compact artifact is a summary, not an execution transcript.
+
+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 already recorded weekly Rust dependency closure as their
+expected runtime identity. Quick includes the Rust manifests, gemspec, resolved
+lock and actually loaded dependencies too. 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 |
+| Feature push, including a new branch | Event `after` | Merge-base with captured default-branch SHA; compares the whole feature |
+| Default-branch push | Event `after` | Event `before`, covering the whole pushed batch |
+| `haveapi-0.30` push with verified maintenance lineage | Event `after` | Event `before`, covering the whole pushed batch |
+| Feature push with verified maintenance lineage | Event `after` | Merge-base with captured `origin/haveapi-0.30` head |
+| 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, initial
+default pushes without a predecessor, missing commits, partial manual pairs,
+unrelated history or equal baseline/candidate fail. PRs use the head commit,
+never the synthetic merge commit; default pushes use `before`, never `HEAD^`.
+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 quick baselines still fail. Maintenance feature selection records both
+the captured default and release heads; missing release refs fail closed.
+
+These verified maintenance comparisons reuse the candidate's prepared environment
+for both sources. In addition to the JSON preparation rule above, they 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,
+Ruby requirements and flake inputs must match, as must the resolved third-party
+runtime graph and retained lock bytes. 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. The exception 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 remain exact. A version change cannot hide a response difference.
+
+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.0'
+  s.add_dependency 'haveapi-client', '~> 0.30.2'
   s.add_dependency 'i18n', '>= 1.6', '< 2'
   s.add_dependency 'json'
   s.add_dependency 'mail'