haveapi 0.31.0 → 0.31.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92be099fb88d7c03896cb0d40205830260f93959987227c2d793a31012e6917f
-  data.tar.gz: 06c2e32b9c92d68ff32cfbe5f43ae9c22fb360a0d8bfb365ead9a48080001348
+  metadata.gz: 88c7ed5020d8b6301015328a883c61412199cca27f7e26b934955b59715cd912
+  data.tar.gz: 04ad5b6f8090a864c7efaaed00b37ad6eb8a3291cb6009ac3056ddd40c815822
 SHA512:
-  metadata.gz: d3cb01c43beac90a8a095eded1edb417a32090ef7149fcd65da86d6d31da0cb54a2eb79f57e2ed2a456f5fd9f1d5bc7916551e88d0856b5d09fb5a1b0e0bba95
-  data.tar.gz: 610e4b8bc84dc86b6a03db3bcfac4bdedf8512482e76cfe2b3b8013cfc33fdb4367055cc546ada82ac1153342c742cbfe1f42b7efb466a3239aab5595352f5b3
+  metadata.gz: cf2eccf2154322f7d534bd7b8c71d7380f6c881e3a9197b511b490adb85084b9f6150a9280702b636d243a97a506cfeb4ed6db3083f4e3a15c6ef07797f91a12
+  data.tar.gz: b1e4cd6c8fc99ec02c42341e124f8c9e6b750b5c930b7a00e4eb2865f102da02f500f14e34a7992c784ff8419c3c5569690772fbfb359ec437e8a00e6d16b5d8

data/benchmarks/endpoints.rb

@@ -386,6 +386,7 @@ module HaveAPI
         paths = %w[Gemfile flake.lock servers/ruby/Gemfile servers/ruby/haveapi.gemspec clients/ruby/Gemfile clients/ruby/haveapi-client.gemspec]
         paths += %w[clients/rust/Gemfile clients/rust/haveapi-rust-client.gemspec]
         paths += %w[.ruby-version flake.nix] if benchmark
+        paths |= SourceVersions::PATHS unless release
         raw_manifests = paths.to_h do |path|
           target = File.join(source, path)
           raise ContractError, "Missing dependency input #{target}" unless File.file?(target)
@@ -410,7 +411,12 @@ module HaveAPI
 
           result = { manifests: receipt.fetch('normalized_sha256'), locks:, release_versions: receipt }
         else
-          result = { manifests:, locks:, json_preparation: preparation }
+          versions = SourceVersions.capture(raw_manifests.slice(*SourceVersions::PATHS))
+          loaded = [HaveAPI::VERSION, HaveAPI::Client::VERSION, HaveAPI::RustClient::VERSION]
+          raise ContractError, 'Wrong loaded local package version' unless loaded.all? { |version| version == versions.fetch('own_version') }
+
+          result = { manifests: manifests.merge(versions.fetch('normalized_sha256')), locks:,
+                     json_preparation: preparation, source_versions: versions }
         end
         if benchmark
           result[:manifests] = result.fetch(:manifests).except('flake.nix', 'flake.lock')
@@ -697,13 +703,7 @@ module HaveAPI
         end
 
         inputs = result.fetch('inputs')
-        if @release_lineage
-          Release.validate_inputs(inputs, @sources.fetch(role), @options.fetch(:profile))
-        elsif inputs.has_key?('release_versions')
-          raise ContractError, 'Unproven own-version normalization'
-        else
-          Release.validate_json_preparation(inputs, @sources.fetch(role))
-        end
+        Performance.validate_input_receipts(inputs, @sources.fetch(role), profile: @options.fetch(:profile), lineage: @release_lineage)
         expected = Identity.parse(File.read(@options.fetch(:budgets))).fetch('environment').fetch('weekly')
         raise ContractError, 'Calibration environment mismatch' unless result.fetch('environment') == expected
 

data/benchmarks/performance_compare.rb

@@ -38,7 +38,7 @@ module HaveAPI
         require 'json'
         spec = Gem::Specification.load(File.basename(ARGV.fetch(0)))
         abort 'Cannot load gemspec' unless spec
-        puts JSON.generate(ruby: spec.required_ruby_version.to_s,
+        puts JSON.generate(name: spec.name, version: spec.version.to_s, ruby: spec.required_ruby_version.to_s,
                            dependencies: spec.dependencies.map { |d| [d.name, d.type.to_s, d.requirement.to_s] }.sort)
       RUBY
       environment = (ENV.keys.grep(/\ABUNDLE/) + %w[RUBYOPT RUBYLIB RUBYGEMS_GEMDEPS]).to_h { |key| [key, nil] }
@@ -209,7 +209,7 @@ module HaveAPI
       end
 
       def self.graph(inputs)
-        inputs.except('release_versions', 'json_preparation', 'contributor_flakes')
+        inputs.except('release_versions', 'source_versions', 'json_preparation', 'contributor_flakes')
       end
 
       def self.html(body, own)
@@ -238,6 +238,103 @@ module HaveAPI
       end
     end
 
+    # Ordinary source ancestry needs no historical maintenance certificate.
+    # Only synchronized package metadata is omitted from input equality.
+    module SourceVersions
+      PLACEHOLDER = 'OWN.VERSION'.freeze
+      COMPONENTS = Release::VERSIONS
+      SPECS = COMPONENTS.to_h { |path, name| ["#{path.split('/lib/').first}/#{name}.gemspec", name] }.freeze
+      PATHS = (['VERSION'] + COMPONENTS.keys + SPECS.keys).freeze
+
+      def self.capture(contents)
+        raise ContractError, 'Incomplete own source metadata' unless contents.keys.sort == PATHS.sort
+
+        own = contents.fetch('VERSION').delete_suffix("\n")
+        unless own.match?(/\A(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\z/) && contents['VERSION'] == "#{own}\n"
+          raise ContractError, 'Invalid own source VERSION'
+        end
+
+        normalized = contents.merge('VERSION' => "#{PLACEHOLDER}\n")
+        COMPONENTS.each do |path, name|
+          text = contents.fetch(path)
+          declaration = /^(\s*VERSION = )'#{Regexp.escape(own)}'(?=\.freeze$)/
+          unless text.scan(/^\s*VERSION\s*=/).length == 1 && text.scan(declaration).length == 1
+            raise ContractError, "Unsynchronized own version: #{name}"
+          end
+
+          normalized[path] = text.sub(declaration, "\\1'#{PLACEHOLDER}'")
+        end
+        SPECS.each do |path, name|
+          text = contents.fetch(path)
+          constant = { 'haveapi' => 'HaveAPI', 'haveapi-client' => 'HaveAPI::Client', 'haveapi-rust-client' => 'HaveAPI::RustClient' }.fetch(name)
+          unless text.scan(/\.name\s*=/).length == 1 && text.scan(/\.name\s*= '#{Regexp.escape(name)}'$/).length == 1 &&
+                 text.scan(/\.version\s*=/).length == 1 && text.scan(/\.version\s*= #{Regexp.escape(constant)}::VERSION$/).length == 1
+            raise ContractError, 'Mismatched own package identity'
+          end
+
+          dependencies = text.scan(/\.add_(?:runtime_|development_)?dependency\s+['"]haveapi-client['"]/)
+          requirement = /(?<=\.add_dependency )'haveapi-client', '~> #{Regexp.escape(own)}'(?=$)/
+          if name == 'haveapi-client'
+            raise ContractError, 'Unexpected own client dependency' unless dependencies.empty?
+          else
+            unless dependencies.length == 1 && text.scan(requirement).length == 1
+              raise ContractError, 'Unsynchronized own client constraint'
+            end
+
+            normalized[path] = text.sub(requirement, "'haveapi-client', '~> #{PLACEHOLDER}'")
+          end
+        end
+        { 'contents' => contents, 'own_version' => own,
+          'raw_sha256' => contents.transform_values { |text| Digest::SHA256.hexdigest(text) },
+          'normalized_sha256' => normalized.transform_values { |text| Digest::SHA256.hexdigest(text) } }
+      end
+
+      def self.gemspec(root, path, receipt)
+        spec = Performance.gemspec(root, path)
+        own = receipt.fetch('own_version')
+        unless spec.fetch('name') == SPECS.fetch(path) && spec.fetch('version') == own
+          raise ContractError, 'Evaluated own package identity mismatch'
+        end
+
+        dependencies = spec.fetch('dependencies').select { |name, _type, _requirement| name == 'haveapi-client' }
+        expected = SPECS.fetch(path) == 'haveapi-client' ? [] : [['haveapi-client', 'runtime', "~> #{own}"]]
+        raise ContractError, 'Evaluated own client constraint mismatch' unless dependencies == expected
+
+        spec.merge('version' => PLACEHOLDER, 'dependencies' => spec.fetch('dependencies').map do |name, type, requirement|
+          [name, type, name == 'haveapi-client' ? "~> #{PLACEHOLDER}" : requirement]
+        end)
+      end
+
+      def self.validate_inputs(inputs, source)
+        receipt = inputs.fetch('source_versions')
+        raise ContractError, 'Own source metadata normalization mismatch' unless receipt == capture(receipt.fetch('contents'))
+
+        receipt.fetch('raw_sha256').each do |path, digest|
+          unless source.fetch('files_sha256').fetch(path) == digest && inputs.fetch('manifests').fetch(path) == receipt.fetch('normalized_sha256').fetch(path)
+            raise ContractError, 'Own source metadata escaped verified source'
+          end
+        end
+      end
+    end
+
+    def self.validate_input_receipts(inputs, source, profile:, lineage:)
+      if lineage
+        raise ContractError, 'Conflicting own-version receipts' if inputs.has_key?('source_versions')
+
+        Release.validate_inputs(inputs, source, profile)
+      else
+        raise ContractError, 'Unproven own-version normalization' if inputs.has_key?('release_versions')
+
+        Release.validate_json_preparation(inputs, source)
+        SourceVersions.validate_inputs(inputs, source) if inputs.has_key?('source_versions')
+        inputs.fetch('manifests').each do |path, digest|
+          next if Release::JSON_GEMFILES.include?(path) || (inputs.has_key?('source_versions') && SourceVersions::PATHS.include?(path))
+
+          raise ContractError, 'Dependency manifest escaped source' unless source.fetch('files_sha256').fetch(path) == digest
+        end
+      end
+    end
+
     def self.validate_source_pair(profile:, baseline_sha:, candidate_sha:)
       raise ContractError, 'Baseline and candidate must differ' if baseline_sha == candidate_sha
       return unless profile == 'weekly' && baseline_sha != REFERENCE
@@ -430,21 +527,10 @@ module HaveAPI
               raise ContractError, 'Missing contributor flake provenance'
             end
 
-            inputs.fetch('manifests').each do |path, digest|
-              next if Release::JSON_GEMFILES.include?(path) || lineage
-
-              raise ContractError, 'Dependency manifest escaped source' unless selected.fetch('files_sha256').fetch(path) == digest
-            end
           elsif inputs.has_key?('contributor_flakes')
             raise ContractError, 'Contributor flake separation without benchmark inputs'
           end
-          if lineage
-            Release.validate_inputs(inputs, selected, @samples.fetch('profile'))
-          elsif inputs.has_key?('release_versions')
-            raise ContractError, 'Unproven own-version normalization'
-          else
-            Release.validate_json_preparation(inputs, selected)
-          end
+          Performance.validate_input_receipts(inputs, selected, profile: @samples.fetch('profile'), lineage:)
           unless observation.fetch('environment') == @samples['environment'] && Release.graph(inputs) == @samples.fetch('inputs') &&
                  observation.fetch('fixture_sha256') == @samples['fixture_sha256']
             raise ContractError, 'Worker provenance mismatch'

data/benchmarks/spec/client_examples_spec.rb

@@ -0,0 +1,216 @@
+# Run unbundled in the locked benchmark shell; optional generators are required.
+# One shared mounted fixture excludes setup from the per-render measurements.
+# rubocop:disable RSpec/InstanceVariable, RSpec/LeakyLocalVariable
+require_relative '../performance_compare'
+root = File.expand_path('../../../..', __dir__)
+%w[servers/ruby clients/ruby clients/go clients/rust clients/typescript].each do |component|
+  $:.unshift(File.join(root, component, 'lib'))
+end
+require 'haveapi'
+require 'rack/mock'
+require 'base64'
+require 'cgi'
+require_relative '../../test_support/all_client_performance_fixture'
+
+RSpec.configure { |config| config.fail_if_no_examples = true }
+
+RSpec.describe HaveAPI::ClientExample, '.render' do
+  # Each mode has its own registry entry. New entries need reviewed expectations
+  # and a real supported profile here, rather than silently missing measurement.
+  profiles = {
+    '0' => nil, '2' => nil, '3' => nil, '5' => nil, '6' => nil,
+    'javascript-callback' => nil, 'javascript-async' => nil,
+    'typescript-callback' => nil, 'typescript-async' => nil,
+    'python-sync' => nil, 'python-async' => nil,
+    'go' => :go, 'rust-async' => :rust, 'rust-blocking' => :rust,
+    'typescript-generated' => :typescript
+  }.freeze
+  lanes = %i[init basic token oauth2 public protected failure].freeze
+  let(:matrix) { profiles }
+
+  before(:all) do
+    @server = HaveAPI::AllClientPerformanceFixture.build(resources: 2)
+    @profiles = @server.documentation_client_profiles(1)
+    @description = description(@server, 'admin')
+    @large_description = Marshal.load(Marshal.dump(@description))
+    unrelated = @large_description.fetch(:resources).fetch('resource1')
+    unrelated[:resources] = 128.times.to_h { |i| ["unrelated#{i}", Marshal.load(Marshal.dump(@description[:resources]['resource1']))] }
+    @measurements = []
+  end
+
+  after(:all) do
+    RSpec.configuration.reporter.message("ALL_CLIENT_PERFORMANCE #{JSON.generate(registry: profiles.keys.sort, lanes:, measurements: @measurements)}")
+  end
+
+  def headers(user)
+    { 'HTTP_HOST' => 'example.test', 'HTTP_ACCEPT_LANGUAGE' => 'en',
+      'HTTP_AUTHORIZATION' => "Basic #{Base64.strict_encode64("#{user}:fixture-only")}" }
+  end
+
+  def description(server, user)
+    server.describe_version(HaveAPI::Context.new(server, version: 1,
+                                                         user: HaveAPI::DocumentationPerformanceFixture::User.new(user), params: {}))
+  end
+
+  def context(description, profile, action_name: 'protected', sample_index: 0, resource_name: 'resource0')
+    resource = description.fetch(:resources).fetch(resource_name)
+    action = resource.fetch(:actions).fetch(action_name)
+    HaveAPI::ClientExample::Context.new(version: 1, host: 'example.test',
+                                        base_url: 'http://example.test/benchmark/api/',
+                                        version_url: 'http://example.test/benchmark/api/v1/',
+                                        description:, profile:, resource_path: [resource_name.to_s],
+                                        resource:, action_name:, action:, sample: action.fetch(:examples).fetch(sample_index))
+  end
+
+  def render(client, lane, ctx)
+    if %i[basic token oauth2].include?(lane)
+      client.render(:auth, context: ctx, auth_method: lane, auth_description: ctx.description.fetch(:authentication).fetch(lane))
+    else
+      client.render(lane == :init ? :init : :example, context: ctx)
+    end
+  end
+
+  def expect_result(result, id, lane)
+    expect(result).to be_a(Hash), "#{id}/#{lane} returned no panel"
+    if id == 'typescript-generated' && lane == :oauth2
+      expect(result[:status]).to eq(:limitation)
+      expect(result[:reason]).to be_a(String)
+      expect(result[:reason]).not_to be_empty
+    else
+      expect(result[:status]).to eq(:code), "#{id}/#{lane}: #{result.inspect}"
+      expect(result[:code]).to be_a(String)
+      expect(result[:code]).not_to be_empty
+      if %w[0 3].include?(id) && lane == :oauth2
+        expect(result[:code]).to include('OAuth2 is not supported')
+      end
+    end
+  end
+
+  def allocations(count: 8, &block)
+    2.times(&block)
+    Array.new(3) do
+      before = GC.stat(:total_allocated_objects)
+      count.times(&block)
+      (GC.stat(:total_allocated_objects) - before) / count.to_f
+    end.min
+  end
+
+  def calls(&block)
+    count = 0
+    trace = TracePoint.new(:call) { count += 1 }
+    trace.enable(&block)
+    count
+  ensure
+    trace&.disable
+  end
+
+  it 'requires exactly the reviewed registry and all real profiles' do
+    ids = described_class.clients.map(&:id)
+    expect(ids.sort).to eq(profiles.keys.sort)
+    expect(ids.uniq).to eq(ids)
+    expect(@profiles.keys.sort).to eq(%i[go rust typescript])
+    expect(@description.fetch(:authentication).keys.sort).to eq(%i[basic oauth2 token])
+  end
+
+  profiles.each do |id, language|
+    lanes.each do |lane|
+      it "bounds #{id}/#{lane} work and allocations with unrelated descendants" do
+        client = described_class.clients.find { |item| item.id == id }
+        expect(client).not_to be_nil
+        profile = language && @profiles.fetch(language)
+        options = { action_name: lane == :public ? 'public' : 'protected', sample_index: lane == :failure ? 1 : 0 }
+        small = context(@description, profile, **options)
+        large = context(@large_description, profile, **options)
+        expect(client.available?(small)).to be(true)
+        expect(client.available?(large)).to be(true)
+        before = Marshal.dump([small.description, large.description])
+        expected = render(client, lane, small)
+        expect_result(expected, id, lane)
+        expect(render(client, lane, large)).to eq(expected)
+        small_calls = calls { render(client, lane, small) }
+        large_calls = calls { render(client, lane, large) }
+        small_allocations = allocations { render(client, lane, small) }
+        large_allocations = allocations { render(client, lane, large) }
+        @measurements << { id:, lane:, allocations: [small_allocations, large_allocations], calls: [small_calls, large_calls] }
+        # Selected action/provider/sample is unchanged. Allow fixed VM/lookup
+        # slack, while recursive walks of the 128 unrelated subtrees must fail.
+        expect(large_calls).to be <= small_calls + 32
+        expect(large_allocations).to be <= small_allocations + 32
+        expect(Marshal.dump([small.description, large.description])).to eq(before)
+      end
+    end
+  end
+
+  def expect_panel(body, anchor, result)
+    panel = body.match(%r{<div id="#{Regexp.escape(anchor)}">\s*(.*?)</div>}m)
+    expect(panel).not_to be_nil, "Missing #{anchor}"
+    text = result.fetch(result[:status] == :code ? :code : :reason)
+    expect(panel[1]).to include(CGI.escapeHTML(text))
+    expect(panel[1]).to include(result[:status] == :code ? '<pre><code' : 'client-limitation')
+  end
+
+  def expect_complete_page(server, user, resources)
+    desc = description(server, user)
+    response = Rack::MockRequest.new(server.app).get('/benchmark/api/v1/', **headers(user))
+    expect(response.status).to eq(200)
+    expect(response['content-type']).to start_with('text/html')
+    expect(response.body).to include('PUBLIC_SAMPLE')
+    %w[ADMIN_ONLY_ACTION ADMIN_ONLY_DEFAULT ADMIN_ONLY_REQUEST ADMIN_ONLY_RESPONSE ADMIN_ONLY_ACTION_SAMPLE admin_field admin_only].each do |marker|
+      expect(response.body.include?(marker)).to eq(user == 'admin'), marker
+    end
+    example_count = 0
+    HaveAPI::ClientExample.clients.each do |client|
+      language = matrix.fetch(client.id)
+      profile = language && server.documentation_client_profiles(1).fetch(language)
+      ctx = context(desc, profile)
+      expect(client.available?(ctx)).to be(true)
+      expect_panel(response.body, "init-#{client.id}", render(client, :init, ctx))
+      desc.fetch(:authentication).each_key do |method|
+        result = render(client, method, ctx)
+        expect_result(result, client.id, method)
+        expect_panel(response.body, "auth-#{method}-#{client.id}", result)
+      end
+      resources.times do |index|
+        resource_name = "resource#{index}"
+        desc.fetch(:resources).fetch(resource_name).fetch(:actions).each do |action_name, action|
+          action.fetch(:examples).each_index do |sample_index|
+            selected = context(desc, profile, action_name: action_name.to_s, sample_index:, resource_name:)
+            result = client.render(:example, context: selected)
+            expect_result(result, client.id, :example)
+            expect_panel(response.body, "example-#{resource_name}-#{action_name}-#{sample_index}-#{client.id}", result)
+            example_count += 1
+          end
+        end
+      end
+    end
+    expected_samples = (resources * 2 * (user == 'admin' ? 3 : 2)) + (user == 'admin' ? 1 : 0)
+    expect(example_count).to eq(expected_samples * matrix.length)
+    response
+  end
+
+  it 'renders every real panel and isolates admin/member/admin pages through the same adapters' do
+    first = expect_complete_page(@server, 'admin', 2)
+    expect_complete_page(@server, 'member', 2)
+    last = expect_complete_page(@server, 'admin', 2)
+    expect(last.body).to eq(first.body)
+  end
+
+  it 'bounds complete all-profile page allocations by linear output growth' do
+    measurements = [2, 4, 8].map do |resources|
+      server = HaveAPI::AllClientPerformanceFixture.build(resources:)
+      response = expect_complete_page(server, 'admin', resources)
+      request = Rack::MockRequest.new(server.app)
+      allocated = allocations(count: 1) { request.get('/benchmark/api/v1/', **headers('admin')) }
+      { resources:, bytes: response.body.bytesize, allocations: allocated }
+    end
+    @measurements << { pages: measurements }
+    small, medium, large = measurements
+    expect(large[:bytes]).to be > medium[:bytes]
+    expect(medium[:bytes]).to be > small[:bytes]
+    expect(medium[:allocations]).to be > small[:allocations]
+    # Doubling the added resources doubles actual panels/output. A 2.5x
+    # incremental allowance covers bookkeeping; quadratic copying approaches 4x.
+    expect(large[:allocations] - medium[:allocations]).to be <= 2.5 * (medium[:allocations] - small[:allocations])
+  end
+end
+# rubocop:enable RSpec/InstanceVariable, RSpec/LeakyLocalVariable

data/doc/client-examples.md

@@ -247,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

data/doc/performance.md

@@ -13,6 +13,56 @@ 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.
 
+## 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'
+```
+
+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.
+
 ## Local commands
 
 The benchmark has its own third-party tool bundle and pinned Nix shell in
@@ -200,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,

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

data/lib/haveapi/version.rb

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

data/spec/performance/event_baseline_spec.rb

@@ -269,7 +269,7 @@ RSpec.describe HaveAPI::PerformanceCI do
   end
 
   it 'skips only irrelevant valid push/PR changes and still forces scheduled/manual work' do
-    allow(repository).to receive(:paths).and_return(['clients/php/README.md'])
+    allow(repository).to receive(:paths).and_return(['LICENSE.txt'])
     event.merge!('ref' => 'refs/heads/master', 'after' => candidate, 'before' => base)
     expect(resolve('push', event)).to include(relevant: false)
     expect(resolve('schedule', event)).to include(relevant: true)
@@ -280,11 +280,38 @@ RSpec.describe HaveAPI::PerformanceCI do
     %w[flake.lock Gemfile Makefile .ruby-version servers/ruby/benchmarks/endpoints.rb
        servers/ruby/benchmarks/Gemfile servers/ruby/benchmarks/Gemfile.lock servers/ruby/benchmarks/shell.nix
        servers/ruby/test_support/performance_sqlite_fixture.rb clients/ruby/Gemfile clients/rust/Gemfile
-       doc/performance.md utils/performance_ci.rb .github/workflows/servers-ruby-performance.yml].each do |path|
+       doc/performance.md utils/performance_ci.rb .github/workflows/servers-ruby-performance.yml
+       servers/ruby/benchmarks/spec/client_examples_spec.rb servers/ruby/test_support/all_client_performance_fixture.rb
+       clients/go/lib/haveapi/go_client/documentation.rb clients/typescript/lib/haveapi/typescript_client/documentation.rb
+       clients/js/src/client.ts clients/python/haveapi/client.py clients/php/src/Client.php clients/new-client/renderer.rb].each do |path|
       expect(described_class::RELEVANT).to match(path)
     end
   end
 
+  it 'requires the current-client contract before comparison and rejects a missing contract outcome' do
+    path = File.expand_path('../../../../.github/workflows/servers-ruby-performance.yml', __dir__)
+    steps = YAML.load_file(path).fetch('jobs').fetch('performance').fetch('steps')
+    contract = steps.find { |step| step['id'] == 'clients' }
+    comparison = steps.find { |step| step['name'] == 'Run the selected pair outside Bundler' }
+    expect(steps.index(contract)).to be < steps.index(comparison)
+    expect(contract.fetch('if')).to eq(comparison.fetch('if'))
+    expect(contract.fetch('run')).to include('make test-performance-clients', "echo 'outcome=passed'")
+    completion = steps.find { |step| step['id'] == 'completion' }
+    Dir.mktmpdir('haveapi-client-contract-gate-') do |directory|
+      File.write(File.join(directory, 'selection.json'), '{}')
+      File.write(File.join(directory, 'runner.exit'), "0\n")
+      FileUtils.mkdir_p(File.join(directory, 'results'))
+      File.write(File.join(directory, 'results/report.json'), '{}')
+      File.write(File.join(directory, 'all-client-contract.log'), 'passed')
+      [nil, '', 'failed', 'passed'].each do |outcome|
+        environment = { 'RELEVANT' => 'true', 'CLIENT_CONTRACT' => outcome,
+                        'PERFORMANCE_EVIDENCE' => directory, 'GITHUB_OUTPUT' => File.join(directory, 'output') }
+        _output, _error, status = Open3.capture3(environment, 'bash', '-euo', 'pipefail', '-c', completion.fetch('run'))
+        expect(status.success?).to eq(outcome == 'passed')
+      end
+    end
+  end
+
   it 'only accepts successful job completion in the aggregate gate' do
     expect(described_class.aggregate!('success', 'compared')).to be(true)
     expect(described_class.aggregate!('success', 'no-work')).to be(true)

data/spec/performance/runner_spec.rb

@@ -4,6 +4,8 @@ require 'tmpdir'
 require 'fileutils'
 require_relative '../../benchmarks/endpoints'
 require_relative '../../../../utils/performance_ci'
+require_relative '../../../../clients/ruby/lib/haveapi/client/version'
+require_relative '../../../../clients/rust/lib/haveapi/rust_client/version'
 require_relative 'support/samples'
 require_relative '../../test_support/performance_endpoint_fixture'
 require_relative '../../test_support/documentation_performance_fixture'

data/spec/performance/source_versions_spec.rb

@@ -0,0 +1,168 @@
+require 'spec_helper'
+require 'tmpdir'
+require 'fileutils'
+require_relative '../../../../utils/performance_ci'
+require_relative '../../benchmarks/endpoints'
+require_relative '../../../../clients/ruby/lib/haveapi/client/version'
+require_relative '../../../../clients/rust/lib/haveapi/rust_client/version'
+require_relative 'support/samples'
+
+describe HaveAPI::PerformanceCI::Campaign do
+  let(:root) { File.expand_path('../../../..', __dir__) }
+  let(:error) { HaveAPI::Performance::ContractError }
+
+  before do
+    # These metadata fixtures evaluate real gemspecs without loading the optional
+    # Rust adapter. Ordinary server bundles do not include its dependencies; the
+    # real benchmark environment checks their installed identities separately.
+    allow(Gem::Specification).to receive(:find_by_name).and_call_original
+    { 'fiddle' => '1.1.8', 'tomlrb' => '2.0.5' }.each do |name, version|
+      specification = Gem::Specification.new do |spec|
+        spec.name = name
+        spec.version = version
+      end
+      allow(Gem::Specification).to receive(:find_by_name).with(name).and_return(specification)
+    end
+  end
+
+  def source_contents(version)
+    paths = HaveAPI::Performance::Release.paths('quick')
+    actual = File.read(File.join(root, 'VERSION')).strip
+    paths.to_h do |path|
+      text = File.read(File.join(root, path))
+      text = "#{version}\n" if path == 'VERSION'
+      text = text.sub("VERSION = '#{actual}'", "VERSION = '#{version}'") if HaveAPI::Performance::Release::VERSIONS.has_key?(path)
+      text = text.sub("'haveapi-client', '~> #{actual}'", "'haveapi-client', '~> #{version}'") if path.end_with?('.gemspec')
+      [path, text]
+    end
+  end
+
+  def write_source(directory, contents)
+    contents.each do |path, text|
+      FileUtils.mkdir_p(File.dirname(File.join(directory, path)))
+      File.write(File.join(directory, path), text)
+    end
+  end
+
+  def prepare(baseline, candidate)
+    Dir.mktmpdir('haveapi-own-versions-') do |directory|
+      roots = { baseline: File.join(directory, 'baseline'), candidate: File.join(directory, 'candidate') }
+      write_source(roots[:baseline], baseline)
+      write_source(roots[:candidate], candidate)
+      campaign = described_class.new(repository: nil, selection: { 'profile' => 'quick' }, evidence: directory, sources: directory)
+      campaign.send(:verify_dependencies, roots)
+      yield roots if block_given?
+    end
+  end
+
+  %w[0.30.0 0.31.0].each do |baseline|
+    it "accepts synchronized #{baseline} to 0.31.1 metadata during preparation" do
+      expect { prepare(source_contents(baseline), source_contents('0.31.1')) }.not_to raise_error
+    end
+
+    it "retains and validates the live worker graph for #{baseline} to 0.31.1" do
+      prepare(source_contents(baseline), source_contents('0.31.1')) do |roots|
+        graphs = roots.map do |role, directory|
+          version = role == :baseline ? baseline : '0.31.1'
+          %w[HaveAPI::VERSION HaveAPI::Client::VERSION HaveAPI::RustClient::VERSION].each { |constant| stub_const(constant, version) }
+          inputs = JSON.parse(JSON.generate(HaveAPI::Performance::Worker.inputs(directory, 'quick', benchmark: true)))
+          hashes = source_contents(version).transform_values { |text| Digest::SHA256.hexdigest(text) }
+          expect do
+            HaveAPI::Performance.validate_input_receipts(inputs, { 'files_sha256' => hashes }, profile: 'quick', lineage: nil)
+          end.not_to raise_error
+          HaveAPI::Performance::Release.graph(inputs)
+        end
+        expect(graphs.first).to eq(graphs.last)
+      end
+    end
+
+    it "replays the synchronized #{baseline} to 0.31.1 graph" do
+      samples, budgets = replay_samples(baseline)
+      expect(compare(samples, budgets).fetch('status')).to eq('pass')
+    end
+  end
+
+  def replay_samples(baseline = '0.31.0')
+    samples, budgets = PerformanceSamples.fixture
+    samples.fetch('sources').each do |role, source|
+      contents = source_contents(role == 'baseline' ? baseline : '0.31.1').slice(*HaveAPI::Performance::SourceVersions::PATHS)
+      receipt = HaveAPI::Performance::SourceVersions.capture(contents)
+      source['files_sha256'].merge!(receipt.fetch('raw_sha256'))
+      samples.fetch('observations').each_value do |observation|
+        next unless observation.fetch('source').fetch('root') == source.fetch('root')
+
+        inputs = Marshal.load(Marshal.dump(observation.fetch('inputs')))
+        inputs['manifests'].merge!(receipt.fetch('normalized_sha256'))
+        inputs['source_versions'] = receipt
+        observation['inputs'] = inputs
+        samples['inputs'] = HaveAPI::Performance::Release.graph(inputs)
+      end
+    end
+    [samples, JSON.parse(budgets)]
+  end
+
+  def compare(samples, budgets)
+    HaveAPI::Performance::Comparator.new(samples, budgets, budget_sha256: samples.fetch('budget_sha256')).compare
+  end
+
+  it 'rejects external dependency and other unnormalized input edits in preparation' do
+    %w[Gemfile .ruby-version servers/ruby/haveapi.gemspec].each do |path|
+      changed = source_contents('0.31.1')
+      changed[path] = path == '.ruby-version' ? "3.0.0\n" : "#{changed[path]}\n# unrelated change\n"
+      expect { prepare(source_contents('0.31.0'), changed) }.to raise_error(HaveAPI::PerformanceCI::Error, /Dependency inputs differ/)
+    end
+    changed = source_contents('0.31.1')
+    changed['servers/ruby/haveapi.gemspec'] = changed['servers/ruby/haveapi.gemspec'].sub("'activesupport', '>= 7.1'", "'activesupport', '>= 999.0'")
+    expect { prepare(source_contents('0.31.0'), changed) }.to raise_error(error, /Benchmark dependencies do not satisfy/)
+  end
+
+  it 'rejects malformed, missing, duplicate and unsynchronized own declarations' do
+    original = source_contents('0.31.1').slice(*HaveAPI::Performance::SourceVersions::PATHS)
+    changes = [
+      ['VERSION', "0.31.01\n"], ['VERSION', " 0.31.1\n"],
+      ['servers/ruby/lib/haveapi/version.rb', original['servers/ruby/lib/haveapi/version.rb'].sub('0.31.1', '0.31.0')],
+      ['servers/ruby/lib/haveapi/version.rb', "VERSION = '0.31.1'.freeze\nVERSION = '0.31.1'.freeze\n"],
+      ['servers/ruby/haveapi.gemspec', original['servers/ruby/haveapi.gemspec'].sub('~> 0.31.1', '~> 0.31.0')],
+      ['servers/ruby/haveapi.gemspec', original['servers/ruby/haveapi.gemspec'].sub("~> 0.31.1'", "~> 0.31.1', '< 0.32'")],
+      ['servers/ruby/haveapi.gemspec', "#{original['servers/ruby/haveapi.gemspec']}s.add_dependency 'haveapi-client', '~> 0.31.1'\n"],
+      ['servers/ruby/haveapi.gemspec', original['servers/ruby/haveapi.gemspec'].sub('HaveAPI::VERSION', "'0.31.0'")],
+      ['clients/ruby/haveapi-client.gemspec', original['clients/ruby/haveapi-client.gemspec'].sub("'haveapi-client'", "'other-client'")]
+    ]
+    changes.each do |path, text|
+      expect { HaveAPI::Performance::SourceVersions.capture(original.merge(path => text)) }.to raise_error(error)
+    end
+    expect { HaveAPI::Performance::SourceVersions.capture(original.except('VERSION')) }.to raise_error(error)
+  end
+
+  it 'rejects loaded versions that do not match the captured source metadata' do
+    Dir.mktmpdir('haveapi-own-worker-') do |directory|
+      write_source(directory, source_contents('0.31.99'))
+      expect { HaveAPI::Performance::Worker.inputs(directory, 'quick', benchmark: true) }.to raise_error(error, /Wrong loaded local package version/)
+    end
+  end
+
+  it 'rejects tampered, stripped, conflicting or unbound receipts and changed runtime/lock inputs on replay' do
+    %w[raw normalized content stripped conflicting source runtime lock].each do |fault|
+      samples, budgets = replay_samples
+      observation = samples.fetch('observations').fetch('candidate')
+      inputs = observation.fetch('inputs')
+      receipt = inputs.fetch('source_versions')
+      case fault
+      when 'raw' then receipt['raw_sha256']['VERSION'] = 'f' * 64
+      when 'normalized' then receipt['normalized_sha256']['VERSION'] = 'f' * 64
+      when 'content' then receipt['contents']['VERSION'] = "0.31.2\n"
+      when 'stripped' then inputs.delete('source_versions')
+      when 'conflicting' then inputs['release_versions'] = {}
+      when 'source' then samples['sources']['candidate']['files_sha256']['VERSION'] = 'f' * 64
+      when 'runtime' then observation['environment'] = { 'ruby' => 'changed' }
+      when 'lock' then inputs['locks']['Gemfile.lock'] = 'f' * 64
+      end
+      expect { compare(samples, budgets) }.to raise_error(error), fault
+    end
+  end
+
+  it 'continues to replay legacy raw manifests without own-version receipts' do
+    samples, budgets = PerformanceSamples.fixture
+    expect(compare(samples, JSON.parse(budgets)).fetch('status')).to eq('pass')
+  end
+end

data/test_support/all_client_performance_fixture.rb

@@ -0,0 +1,84 @@
+require_relative 'documentation_performance_fixture'
+
+module HaveAPI
+  # Scalar samples deliberately stay inside every generator's supported subset.
+  # The historical timing fixture and its calibrated workloads stay separate.
+  module AllClientPerformanceFixture
+    class TokenConfig < Authentication::Token::Config
+      # Keep the saved JSON SDK description and live provider value identical.
+      query_parameter '_auth_token'
+    end
+
+    class OAuthConfig < Authentication::OAuth2::Config
+      def base_url
+        'http://example.test'
+      end
+    end
+
+    def self.build(resources:)
+      definitions = Module.new
+      resources.times do |index|
+        resource = Class.new(HaveAPI::Resource)
+        definitions.const_set("Resource#{index}", resource)
+        resource.resource_name = "Resource#{index}"
+        resource.version 1
+        resource.route "resources#{index}"
+        %w[Public Protected].each { |name| add_action(resource, name) }
+        DocumentationPerformanceFixture.send(:add_admin_action, resource) if index == 0
+      end
+      server = HaveAPI::Server.new(definitions)
+      server.use_version(1)
+      server.default_version = 1
+      server.auth_chain << DocumentationPerformanceFixture::BasicProvider
+      server.auth_chain << Authentication::Token.with_config(TokenConfig)
+      server.auth_chain << Authentication::OAuth2.with_config(OAuthConfig)
+      server.documentation_clients(1,
+                                   go: { import_path: 'example.test/performance/client' },
+                                   rust: { crate_name: 'performance_client' },
+                                   typescript: { package_name: 'performance-client' })
+      server.mount('/benchmark/api/')
+      server
+    end
+
+    def self.add_action(resource, name)
+      resource.define_action(name) do
+        route name.downcase
+        http_method :post
+        auth name == 'Protected'
+        input(:hash) do
+          string :value
+          bool :enabled
+          integer :count
+          string :admin_field, default: 'ADMIN_ONLY_DEFAULT'
+        end
+        output(:hash) do
+          string :marker
+          string :admin_field
+        end
+        authorize do |user|
+          if user && user.login != 'admin'
+            input blacklist: [:admin_field]
+            output blacklist: [:admin_field]
+          end
+          allow
+        end
+        example 'Success' do
+          request(value: '', enabled: false, count: 0)
+          response(marker: 'PUBLIC_SAMPLE')
+        end
+        example 'Failure' do
+          request(value: '', enabled: false, count: 0)
+          status false
+          message 'Expected failure'
+          errors(value: ['fixture error'])
+        end
+        example 'Admin' do
+          authorize { |user| user.login == 'admin' }
+          request(admin_field: 'ADMIN_ONLY_REQUEST')
+          response(admin_field: 'ADMIN_ONLY_RESPONSE')
+        end
+      end
+    end
+    private_class_method :add_action
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: haveapi
 version: !ruby/object:Gem::Version
-  version: 0.31.0
+  version: 0.31.2
 platform: ruby
 authors:
 - Jakub Skokan
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.31.0
+        version: 0.31.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.31.0
+        version: 0.31.2
 - !ruby/object:Gem::Dependency
   name: i18n
   requirement: !ruby/object:Gem::Requirement
@@ -217,6 +217,7 @@ files:
 - benchmarks/performance_budgets.json
 - benchmarks/performance_compare.rb
 - benchmarks/shell.nix
+- benchmarks/spec/client_examples_spec.rb
 - doc/client-examples.md
 - doc/create-client.md
 - doc/hooks.erb
@@ -396,6 +397,7 @@ files:
 - spec/performance/json_activation_spec.rb
 - spec/performance/release_lineage_spec.rb
 - spec/performance/runner_spec.rb
+- spec/performance/source_versions_spec.rb
 - spec/performance/sqlite_spec.rb
 - spec/performance/support/live_worker.rb
 - spec/performance/support/samples.rb
@@ -412,6 +414,7 @@ files:
 - spec/validators/length_spec.rb
 - spec/validators/numericality_spec.rb
 - spec/validators/presence_spec.rb
+- test_support/all_client_performance_fixture.rb
 - test_support/client_test_api.rb
 - test_support/client_test_server.rb
 - test_support/documentation_performance_fixture.rb