haveapi 0.30.2 → 0.31.0

data/doc/performance.md

@@ -15,39 +15,45 @@ 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:
+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 +65,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 +154,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 +181,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
@@ -183,20 +212,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 +249,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.0'
   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

data/lib/haveapi/documentation_clients.rb

@@ -21,7 +21,8 @@ module HaveAPI
 
       KEYS = {
         go: %i[import_path module_version description_path generator_version],
-        rust: %i[crate_name crate_version source snapshot_path generator_config_path generator_version]
+        rust: %i[crate_name crate_version source snapshot_path generator_config_path generator_version],
+        typescript: %i[package_name package_version snapshot_path generator_version]
       }.freeze
 
       def initialize
@@ -52,9 +53,12 @@ module HaveAPI
         raise Invalid, 'Documentation client profile selects an unavailable API version' unless unknown.empty?
 
         @registrations.each do |version, languages|
-          snapshot = languages.dig(:rust, :snapshot)
-          if snapshot && snapshot.fetch('api_version').to_s != version
-            raise Invalid, 'Documentation Rust snapshot API version mismatch'
+          %i[rust typescript].each do |language|
+            snapshot = languages.dig(language, :snapshot)
+            if snapshot && snapshot.fetch('api_version').to_s != version
+              label = language == :rust ? 'Rust' : 'TypeScript'
+              raise Invalid, "Documentation #{label} snapshot API version mismatch"
+            end
           end
         end
       end
@@ -101,7 +105,7 @@ module HaveAPI
 
       def validate_config(language, config)
         unless config.is_a?(Hash) && (config.keys - KEYS.fetch(language)).empty? &&
-               config.all? { |key, value| %i[source module_version crate_version].include?(key) || nonempty_string?(value) }
+               config.all? { |key, value| %i[source module_version crate_version package_version].include?(key) || nonempty_string?(value) }
           raise Invalid, 'Invalid documentation client profile fields'
         end
 
@@ -125,7 +129,11 @@ module HaveAPI
       def load_profile(language, config)
         safely do
           config = validate_config(language, config)
-          language == :go ? load_go(config) : load_rust(config)
+          case language
+          when :go then load_go(config)
+          when :rust then load_rust(config)
+          when :typescript then load_typescript(config)
+          end
         end
       end
 
@@ -211,6 +219,12 @@ module HaveAPI
 
         arguments = { description:, api_version: version, protocol_version: HaveAPI::PROTOCOL_VERSION,
                       mount_path: server.root }
+        if language == :typescript
+          adapter = HaveAPI::TypeScriptClient::Documentation.from_description(
+            **arguments, package_name: config[:name], package_version: config[:version]
+          )
+          return profile(:typescript, config, adapter)
+        end
         if config[:generator_config]
           snapshot = HaveAPI::RustClient::Snapshot.from_description(
             **arguments, source_url: "https://haveapi.invalid#{server.root}v#{version}/", profile: 'server-documentation'
@@ -237,6 +251,35 @@ module HaveAPI
         profile(:rust, config, adapter)
       end
 
+      def load_typescript(config)
+        name = config[:package_name]
+        version = config[:package_version]
+        unless nonempty_string?(name) && name.bytesize <= 214 &&
+               name.match?(%r{\A(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*\z}) &&
+               !%w[node_modules favicon.ico].include?(name) &&
+               (version.nil? || (version.is_a?(String) &&
+                 version.match?(/\A(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?\z/)))
+          raise Invalid, 'Invalid TypeScript documentation client package'
+        end
+
+        require 'haveapi/typescript_client/documentation'
+        unless config.fetch(:generator_version) == HaveAPI::TypeScriptClient::VERSION
+          raise Invalid, 'Documentation TypeScript generator version mismatch'
+        end
+
+        documentation = HaveAPI::TypeScriptClient::Documentation
+        unless documentation.respond_to?(:from_description) && documentation.respond_to?(:from_snapshot)
+          raise Invalid, 'Documentation TypeScript generator has an incompatible profile interface'
+        end
+
+        prepared = { name: name.dup.freeze, version: version&.dup&.freeze }.freeze
+        return prepared unless config.has_key?(:snapshot_path)
+
+        snapshot = JSON.parse(File.read(local_file(config[:snapshot_path])))
+        adapter = documentation.from_snapshot(snapshot:, package_name: name, package_version: version)
+        prepared.merge(snapshot:, profile: profile(:typescript, prepared, adapter)).freeze
+      end
+
       def profile(language, config, adapter)
         unless adapter.respond_to?(:resolve) && adapter.respond_to?(:render)
           raise Invalid, 'Documentation client generator has an incompatible adapter interface'

data/lib/haveapi/version.rb

@@ -1,4 +1,4 @@
 module HaveAPI
   PROTOCOL_VERSION = '2.0'.freeze
-  VERSION = '0.30.2'.freeze
+  VERSION = '0.31.0'.freeze
 end

data/lib/haveapi/views/version_page.erb

@@ -20,7 +20,7 @@
   <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/js" target="_blank" rel="noopener">JavaScript and TypeScript (callback and async)</a></li>
   <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/python" target="_blank" rel="noopener">Python (sync and async)</a></li>
   <% settings.api_server.documentation_client_profiles(@v).each do |language, profile| %>
-    <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/<%= escape_html(language) %>" target="_blank" rel="noopener"><%= language == :go ? 'Go' : 'Rust (async and blocking)' %></a>: <code><%= escape_html(profile.package_name) %></code><% if profile.package_version %> <%= escape_html(profile.package_version) %><% end %></li>
+    <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/<%= escape_html(language) %>" target="_blank" rel="noopener"><%= { go: 'Go', rust: 'Rust (async and blocking)', typescript: 'TypeScript (generated)' }.fetch(language) %></a>: <code><%= escape_html(profile.package_name) %></code><% if profile.package_version %> <%= escape_html(profile.package_version) %><% end %></li>
   <% end %>
   <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/php" target="_blank" rel="noopener">PHP</a></li>
   <li>
@@ -31,7 +31,7 @@
 
 <p>
   These examples target API v<%= escape_html(@v) %>. The framework and dynamic
-  clients share HaveAPI package versions. Generated Go and Rust SDKs use their
+  clients share HaveAPI package versions. Generated Go, Rust and TypeScript SDKs use their
   own package versions. Their configured SDKs are expected to match this API.
 </p>
 

data/spec/client_examples/profile_mount_spec.rb

@@ -139,6 +139,20 @@ describe HaveAPI::Server, '#mount' do
     )
   end
 
+  def register_typescript
+    generator = Module.new
+    generator.const_set(:VERSION, HaveAPI::VERSION)
+    generator.const_set(:Documentation, documentation)
+    stub_const('HaveAPI::TypeScriptClient', generator)
+    allow(registry).to receive(:require).with('haveapi/typescript_client/documentation').and_return(true)
+    allow(documentation).to receive(:from_description) do |description:, **|
+      descriptions << description
+      adapter
+    end
+    allow(documentation).to receive(:from_snapshot).and_return(adapter)
+    server.documentation_clients(1, typescript: { package_name: '@example/widget-client' })
+  end
+
   it 'captures the complete selected version after auth, action-state and post-mount routes exist' do
     register
     server.action_state = Object.new
@@ -212,4 +226,35 @@ describe HaveAPI::Server, '#mount' do
     expect(server.app).to be_nil
     expect(server.documentation_client_profiles(1)).to be_empty
   end
+
+  it 'mounts a generated TypeScript panel beside dynamic tabs using only authorized request samples' do
+    register_typescript
+    server.mount('/mounted/api/')
+    expect(descriptions.size).to eq(1)
+    private_schema = descriptions.first
+    expect(private_schema).to be_frozen
+    expect(JSON.generate(private_schema)).not_to include('PRIVATE_DEFAULT', 'PRIVATE_SAMPLE', 'PRIVATE_RESPONSE')
+    expect(private_schema.dig('resources', 'widget', 'actions')).to have_key('secret')
+    expect(request_as('admin', 'en').body).to include('PRIVATE_SAMPLE')
+    contexts.clear
+    response = request_as('member', 'en')
+    expect(response.status).to eq(200)
+    expect(response.body).to include('TypeScript (generated)', 'init-typescript-generated', 'init-typescript-callback',
+                                     'init-typescript-async', 'example-widget-show-0-typescript-generated', '@example/widget-client')
+    expect(response.body).not_to include('PRIVATE_DEFAULT', 'PRIVATE_SAMPLE', 'PRIVATE_RESPONSE', 'admin_only')
+    selected = contexts.find { |context| context.action_name == 'show' }
+    expect(selected.version_url).to eq('http://example.org/mounted/api/v1/')
+    expect(selected.action.dig(:input, :parameters).keys).to eq([:visible])
+    expect(selected.sample[:request]).to eq(visible: 'public sample')
+    expect(documentation).to have_received(:from_description).once
+  end
+
+  it 'aborts the whole mount when the generated TypeScript adapter rejects the full declaration' do
+    register_typescript
+    allow(documentation).to receive(:from_description).and_raise('PRIVATE_TYPESCRIPT_DIAGNOSTIC')
+    expect { server.mount('/') }.to raise_error(HaveAPI::ClientExample::Profiles::Invalid,
+                                                'Configured documentation client schema or configuration is invalid')
+    expect(server.app).to be_nil
+    expect(server.documentation_client_profiles(1)).to be_empty
+  end
 end

data/spec/client_examples/ts_generated_client_spec.rb

@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+class TypeScriptDocumentationAdapterFixture
+  def render(kind:, context:, mode:, auth_method: nil, auth_description: nil); end
+end
+
+describe HaveAPI::ClientExamples::TsGeneratedClient do
+  let(:adapter) { instance_spy(TypeScriptDocumentationAdapterFixture) }
+  let(:profile) { Struct.new(:language, :adapter).new(:typescript, adapter).freeze }
+  let(:context) do
+    HaveAPI::ClientExample::Context.new(
+      version: '1.0', host: 'example.test', base_url: 'https://example.test/mount/',
+      version_url: 'https://example.test/mount/v1.0/', description: {},
+      resource_path: ['widget'], action_name: 'update', action: {}, sample: { request: {} }, profile:
+    )
+  end
+
+  it 'adds a separate generated variant while preserving dynamic TypeScript identifiers' do
+    expect(described_class.id).to eq('typescript-generated')
+    expect(described_class.label).to eq('TypeScript (generated)')
+    expect(described_class.code).to eq(:typescript)
+    expect(HaveAPI::ClientExamples::TsClient.id).to eq('typescript-callback')
+    expect(HaveAPI::ClientExamples::TsAsyncClient.id).to eq('typescript-async')
+  end
+
+  it 'is available only for a matching optional profile' do
+    expect(described_class.available?(nil)).to be(false)
+    expect(described_class.available?(context.with(profile: nil))).to be(false)
+    expect(described_class.available?(context.with(profile: Struct.new(:language).new(:rust)))).to be(false)
+    expect(described_class.available?(context)).to be(true)
+  end
+
+  it 'delegates the immutable authorized context and exact authentication metadata' do
+    result = { status: :code, code: 'generated TypeScript' }.freeze
+    allow(adapter).to receive(:render).and_return(result)
+    expect(described_class.render(:init, context:)).to eq(result)
+    expect(described_class.render(:auth, context:, auth_method: :token, auth_description: { http_header: 'X-Token' })).to eq(result)
+    expect(adapter).to have_received(:render).with(kind: :init, context:, mode: :async)
+    expect(adapter).to have_received(:render).with(kind: :auth, context:, mode: :async, auth_method: :token,
+                                                   auth_description: { http_header: 'X-Token' })
+  end
+
+  it 'binds only the supplied authorized sample and preserves limitations' do
+    sample = { request: { label: 'public' } }
+    result = { status: :limitation, reason: 'The saved SDK does not represent this sample.' }.freeze
+    allow(adapter).to receive(:render).and_return(result)
+    renderer = described_class.new('example.test', 'https://example.test/', '1.0').with_context(context)
+    expect(renderer.example(sample)).to eq(result)
+    expect(adapter).to have_received(:render).with(kind: :example, mode: :async, context: have_attributes(sample: sample))
+    expect(renderer.init).to eq(result)
+    expect(described_class.new('example.test', 'https://example.test/', '1.0').init).to include(status: :limitation)
+  end
+end

data/spec/client_examples/typescript_profiles_spec.rb

@@ -0,0 +1,113 @@
+require 'spec_helper'
+require 'tmpdir'
+
+describe HaveAPI::ClientExample::Profiles do
+  let(:profiles) { described_class.new }
+  let(:server) { instance_double(HaveAPI::Server, versions: ['1.0'], root: '/mounted/', describe_version: description) }
+  let(:adapter) do
+    Class.new do
+      def resolve(**); end
+      def render(**); end
+    end.new
+  end
+  let(:documentation) { Class.new }
+  let(:directory) { Dir.mktmpdir('haveapi-typescript-profile-') }
+
+  def snapshot_path
+    File.join(directory, 'snapshot.json')
+  end
+
+  def description
+    { resources: { widget: { actions: { show: { input: { parameters: { hidden: { default: 'PRIVATE_DEFAULT' } } }, examples: ['PRIVATE_SAMPLE'] } } } },
+      authentication: {}, meta: { namespace: '_meta' } }
+  end
+
+  before do
+    generator = Module.new
+    generator.const_set(:VERSION, HaveAPI::VERSION)
+    generator.const_set(:Documentation, documentation)
+    stub_const('HaveAPI::TypeScriptClient', generator)
+    allow(profiles).to receive(:require).with('haveapi/typescript_client/documentation').and_return(true)
+    allow(documentation).to receive_messages(from_description: adapter, from_snapshot: adapter)
+  end
+
+  after { FileUtils.remove_entry(directory) }
+
+  def mount
+    profiles.mount(['1.0'])
+    profiles.finalize(server)
+  end
+
+  it 'defers one frozen private structural description and preserves omitted package version' do
+    config = { package_name: '@example/widget-client' }
+    profiles.register('1.0', typescript: config)
+    config[:package_name].replace('changed-client')
+    expect(documentation).not_to have_received(:from_description)
+    mount
+    expect(documentation).to have_received(:from_description).once do |**arguments|
+      expect(arguments).to include(api_version: '1.0', protocol_version: HaveAPI::PROTOCOL_VERSION, mount_path: '/mounted/',
+                                   package_name: '@example/widget-client', package_version: nil)
+      expect(arguments[:description]).to be_frozen
+      expect(JSON.generate(arguments[:description])).not_to include('PRIVATE_DEFAULT', 'PRIVATE_SAMPLE')
+      expect(arguments[:description].dig('resources', 'widget', 'actions', 'show', 'input', 'parameters')).to have_key('hidden')
+    end
+    profile = profiles.for_version('1.0').fetch(:typescript)
+    expect(profile).to have_attributes(language: :typescript, package_name: '@example/widget-client', package_version: nil)
+    expect(profile).to be_frozen
+    expect(profile.adapter).to be_frozen
+    expect(server).to have_received(:describe_version).once
+  end
+
+  it 'loads a saved SDK once at registration with explicit package and generator versions' do
+    File.write(snapshot_path, JSON.generate(api_version: '1.0'))
+    profiles.register('1.0', typescript: { package_name: 'widget-client', package_version: '1.2.3-beta.1+build.4',
+                                           snapshot_path:, generator_version: HaveAPI::VERSION })
+    File.unlink(snapshot_path)
+    mount
+    expect(documentation).to have_received(:from_snapshot).once.with(snapshot: { 'api_version' => '1.0' },
+                                                                     package_name: 'widget-client', package_version: '1.2.3-beta.1+build.4')
+    expect(server).not_to have_received(:describe_version)
+  end
+
+  it 'rejects unsafe names, nonconcrete versions and unexpected fields before loading the generator' do
+    ['../client', '@scope', 'https://example.test/client', 'UPPERCASE', 'client name', 'node_modules'].each do |name|
+      expect { profiles.register('1.0', typescript: { package_name: name }) }.to raise_error(described_class::Invalid, /package/)
+    end
+    ['latest', '^1.2.3', '1.2', '01.2.3', '1.2.3-01', false].each do |version|
+      expect { profiles.register('1.0', typescript: { package_name: 'client', package_version: version }) }.to raise_error(described_class::Invalid, /package/)
+    end
+    expect { profiles.register('1.0', typescript: { package_name: 'client', factory: 'custom' }) }.to raise_error(described_class::Invalid, /fields/)
+    expect(profiles).not_to have_received(:require)
+  end
+
+  it 'rejects missing generators, version mismatch, missing snapshots and incompatible factories' do
+    allow(profiles).to receive(:require).and_raise(LoadError)
+    expect { profiles.register('1.0', typescript: { package_name: 'client' }) }.to raise_error(described_class::Invalid, /not installed/)
+    allow(profiles).to receive(:require).and_return(true)
+    expect { profiles.register('1.0', typescript: { package_name: 'client', generator_version: '0.0.0' }) }.to raise_error(described_class::Invalid, /version mismatch/)
+    expect { profiles.register('1.0', typescript: { package_name: 'client', snapshot_path: '/missing/schema.json' }) }.to raise_error(described_class::Invalid, /absolute local/)
+    allow(documentation).to receive(:respond_to?).and_call_original
+    allow(documentation).to receive(:respond_to?).with(:from_snapshot).and_return(false)
+    expect { profiles.register('1.0', typescript: { package_name: 'client' }) }.to raise_error(described_class::Invalid, /incompatible profile/)
+  end
+
+  it 'rejects a different saved API version without publishing any profile' do
+    File.write(snapshot_path, JSON.generate(api_version: '2.0'))
+    profiles.register('1.0', typescript: { package_name: 'client', snapshot_path: })
+    expect { profiles.mount(['1.0']) }.to raise_error(described_class::Invalid, /TypeScript snapshot API version mismatch/)
+    expect(profiles.for_version('1.0')).to be_empty
+  end
+
+  it 'fails atomically and hides private diagnostics for invalid schemas or adapters' do
+    allow(documentation).to receive(:from_description).and_raise('PRIVATE_SCHEMA_DIAGNOSTIC')
+    profiles.register('1.0', typescript: { package_name: 'client' })
+    expect { mount }.to raise_error(described_class::Invalid, 'Configured documentation client schema or configuration is invalid')
+    expect(profiles.for_version('1.0')).to be_empty
+  end
+
+  it 'rejects an adapter missing render or resolve during initialization' do
+    allow(documentation).to receive(:from_description).and_return(Object.new)
+    profiles.register('1.0', typescript: { package_name: 'client' })
+    expect { mount }.to raise_error(described_class::Invalid, /adapter interface/)
+  end
+end