haveapi 0.30.2 → 0.31.1

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.
@@ -165,7 +196,8 @@ 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,
+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.
 
@@ -185,16 +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 authorized description snapshots belong to individual requests.
+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
+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;
@@ -210,6 +247,13 @@ 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.
 
+The additional required `make test-performance-clients` contract checks every
+registered renderer and mode with real generated profiles, bounded per-render
+work and allocations, and complete-page allocation scaling. It runs in the
+locked, unbundled benchmark environment, separately from the ordinary server
+bundle. See [performance testing](performance.md#all-client-documentation-contract)
+for preparation, exact coverage and CI behavior.
+
 ### Documentation benchmark
 
 Prepare the server bundle in its declared Nix environment, then run the opt-in
@@ -220,8 +264,10 @@ 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.
+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`.
@@ -229,8 +275,10 @@ 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
+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
@@ -242,8 +290,10 @@ make benchmark-documentation \
 ```
 
 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
+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
@@ -269,13 +319,16 @@ Rust lanes are never silently omitted. See the
 
 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
+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
+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

data/doc/performance.md

@@ -13,41 +13,97 @@ 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
+## All-client documentation contract
+
+The required performance workflow first runs `make test-performance-clients`
+against the selected candidate in the prepared, unbundled benchmark shell:
+
+```sh
+export HAVEAPI_BENCHMARK_GEM_HOME="$PWD/servers/ruby/benchmarks/.gems"
+nix-shell servers/ruby/benchmarks/shell.nix --run 'make test-performance-clients'
+```
 
-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.
+Prepare the frozen benchmark bundle as described below before running this
+command. It loads the actual Go, Rust and TypeScript generator sources and fails
+if a dependency or profile is missing. It needs no Go, Rust or TypeScript
+compiler. The ordinary `make test-performance` remains a separate server-bundle
+check; both checks are required.
+
+The explicit coverage matrix must equal the live renderer registry. Its 15
+entries include every callback, async, blocking and generated variant. Each
+entry renders initialization, Basic, token and OAuth2 authentication, public and
+protected actions, and a failed action sample. Basic authentication and action
+samples must produce code for every renderer. Generated TypeScript's OAuth2
+limitation and the Ruby library/CLI's existing unsupported-OAuth2 comments have
+explicit expectations. New renderer IDs or providers require reviewed coverage;
+they cannot silently disappear from measurement.
+
+Direct checks hold the selected action, sample and provider constant while adding
+128 unrelated resource subtrees. Setup and context ownership copying happen
+outside measurement. Three batches of eight renders check allocations, and a
+separate Ruby-call count checks traversal growth; each allows 32 additional
+objects or calls per render. Output must remain identical and inputs unchanged.
+
+Complete Rack HTML requests enable all three generated profiles. Checks compare
+every registered initialization/authentication/action panel with real renderer
+output, including successful and failed samples, and exercise admin/member/admin
+isolation through the same adapters. Allocation measurements use pages with
+2, 4 and 8 resources, each with two actions and three admin-visible samples per
+action, plus one admin-only action. Member pages hide the admin sample and action.
+The added-resource allocation increment may grow by at most 2.5 times when the
+resource increment doubles. This permits linear panel/output growth while
+rejecting the measured whole-description-per-example copy regression. The
+fixture uses scalar fields so Go action panels exercise supported code paths.
+
+The log retains the named registry, kinds, allocations, Ruby-call counts and
+page byte counts. These deterministic checks measure the selected candidate.
+They use no wall-clock threshold and provide no historical timing result. The
+paired timing suite below retains its original workloads, fixed reference and budgets; its
+reference predates generated TypeScript support. Relevant pushes and pull
+requests, manual runs and scheduled runs must pass the all-client contract before
+the paired comparison. Changes under any client directory trigger the gate.
 
-Run deterministic specs in the prepared top-level shell:
+## 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
-make test-performance
+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 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:
+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
-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'
+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"
+'
 ```
 
-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.
+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:
 
@@ -59,14 +115,22 @@ make performance-compare \
 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.
+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, 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.
+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.
 
@@ -140,10 +204,24 @@ 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.
+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
@@ -153,10 +231,11 @@ 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
+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
@@ -171,6 +250,20 @@ 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.
 
+Comparisons outside the historical 0.30 maintenance mapping retain a
+`source_versions` receipt for each source. It validates the numeric source
+`VERSION`, matching Ruby server/client
+and Rust generator version constants, package identities and exact synchronized
+internal `haveapi-client` requirements before normalizing those version fields.
+Preparation, live workers and replay bind the raw hashes to the verified source
+and compare the normalized manifests. Missing, duplicate, inconsistent or tampered
+metadata fails. All other manifest bytes, external dependencies, runtime and
+benchmark locks remain part of the strict comparison. Older raw-manifest samples
+still replay; removing a receipt from normalized samples fails source validation.
+This rule permits coordinated package-version changes without changing baseline
+selection or the separate historical 0.30 maintenance-lineage proof. Response
+changes remain diagnostics under the existing per-revision stability policy.
+
 ## GitHub workflow and baseline selection
 
 The `servers/ruby performance` workflow runs on pushes, ordinary pull requests,
@@ -183,20 +276,23 @@ Missing event/source evidence fails even when no relevant path can be establishe
 | 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 |
+| 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, 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^`.
+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.
 
@@ -217,29 +313,35 @@ 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
+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. The exception applies only to the
-HTML documentation workloads on the proven maintenance lineage. JSON/API
+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 remain exact. A version change cannot hide a response difference.
+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

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.2'
+  s.add_dependency 'haveapi-client', '~> 0.31.1'
   s.add_dependency 'i18n', '>= 1.6', '< 2'
   s.add_dependency 'json'
   s.add_dependency 'mail'

data/lib/haveapi/client_examples/ts_generated_client.rb

@@ -0,0 +1,36 @@
+require 'haveapi/client_example'
+
+module HaveAPI::ClientExamples
+  class TsGeneratedClient < HaveAPI::ClientExample
+    id 'typescript-generated'
+    label 'TypeScript (generated)'
+    code :typescript
+    order 19
+
+    def self.available?(context)
+      context&.profile&.language == :typescript
+    end
+
+    def init
+      render_documentation(:init)
+    end
+
+    def auth(method, desc)
+      render_documentation(:auth, auth_method: method, auth_description: desc)
+    end
+
+    def example(sample)
+      render_documentation(:example, rendering_context: context&.with(sample:))
+    end
+
+    private
+
+    def render_documentation(kind, rendering_context: context, **)
+      unless self.class.available?(rendering_context)
+        return { status: :limitation, reason: 'A generated TypeScript SDK documentation profile is required.' }.freeze
+      end
+
+      rendering_context.profile.adapter.render(kind:, context: rendering_context, mode: :async, **)
+    end
+  end
+end