haveapi 0.30.2 → 0.31.1

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.1'.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

data/spec/documentation/client_examples_spec.rb

@@ -42,10 +42,10 @@ describe HaveAPI::ClientExample do
     expect(last_response.body).to include('Initialization', '<h4>Ruby</h4>', '<h4>PHP</h4>', '<h4>curl</h4>')
   end
 
-  it 'hides unconfigured Go and Rust SDKs in overview, initialization, authentication and actions' do
+  it 'hides unconfigured generated SDKs in overview, initialization, authentication and actions' do
     get '/v1/'
     expect(last_response.status).to eq(200)
-    expect(last_response.body).not_to include('clients/go', 'clients/rust', 'init-go', 'init-rust', '>Go</h', '>Rust (')
+    expect(last_response.body).not_to include('clients/go', 'clients/rust', 'init-go', 'init-rust', 'typescript-generated', '>Go</h', '>Rust (')
     expect(last_response.body).to include('init-javascript-callback', 'init-typescript-async', 'init-python-sync')
     expect(last_response.body).to include('example-widget-show-0-javascript-callback')
   end

data/spec/performance/comparator_spec.rb

@@ -4,12 +4,12 @@ require 'open3'
 require_relative 'support/samples'
 
 describe HaveAPI::Performance::Comparator do
-  def compare_cli(samples, budgets)
+  def compare_cli(samples, budgets, sample_bytes: JSON.generate(samples))
     Dir.mktmpdir('haveapi-comparator-') do |directory|
       input = File.join(directory, 'samples.json')
       policy = File.join(directory, 'budgets.json')
       output = File.join(directory, 'result')
-      File.write(input, JSON.generate(samples))
+      File.binwrite(input, sample_bytes)
       File.write(policy, budgets)
       _stdout, _stderr, status = Open3.capture3(RbConfig.ruby, File.expand_path('../../benchmarks/endpoints.rb', __dir__),
                                                 'compare', '--input', input, '--budgets', policy, '--output', output)
@@ -25,6 +25,14 @@ describe HaveAPI::Performance::Comparator do
     output.merge!('body_sha256' => digest, 'body_bytes' => body.bytesize)
   end
 
+  def replace_response(sample, body, json: true)
+    replace_raw_body(sample, body)
+    canonical = json ? JSON.parse(body) : nil
+    sample['bodies'].values.first['canonical_body'] = canonical
+    sample['outputs'].first.merge!('envelope_status' => json ? canonical.fetch('status') : nil,
+                                   'canonical_sha256' => json ? HaveAPI::Performance::Identity.digest(canonical) : Digest::SHA256.hexdigest(body))
+  end
+
   def rebind_source(samples, role, sha)
     samples["#{role}_sha"] = sha
     samples['sources'][role]['sha'] = sha
@@ -44,6 +52,99 @@ describe HaveAPI::Performance::Comparator do
     expect(JSON.generate(report)).not_to include('canonical_body', 'body_sha256', 'self_pairs', 'observations', 'loaded_sources')
   end
 
+  it 'attributes replay success and loaded-input errors to exact input/comparator bytes and the original measurement harness' do
+    samples, budgets = PerformanceSamples.fixture
+    [false, true].each do |broken|
+      samples['schema_version'] = broken ? 1 : 2
+      bytes = "#{JSON.pretty_generate(samples)}\n"
+      code, report = compare_cli(samples, budgets, sample_bytes: bytes)
+      expect(code).to eq(broken ? 3 : 0)
+      expect(report['harness_sha256']).to eq('e' * 64)
+      expect(report.values_at('baseline_sha', 'candidate_sha', 'budget_sha256')).to eq(samples.values_at('baseline_sha', 'candidate_sha', 'budget_sha256'))
+      expect(report['comparison']).to eq('policy' => 'per-revision-response-stability-v1',
+                                         'comparator_sha256' => Digest::SHA256.file(File.expand_path('../../benchmarks/performance_compare.rb', __dir__)).hexdigest,
+                                         'samples_sha256' => Digest::SHA256.hexdigest(bytes))
+    end
+    code, report = compare_cli(samples, budgets, sample_bytes: '{')
+    expect(code).to eq(3)
+    expect(report).not_to have_key('harness_sha256')
+    expect(report.dig('comparison', 'samples_sha256')).to eq(Digest::SHA256.hexdigest('{'))
+  end
+
+  it 'classifies stable changed JSON and HTML normally without changing performance budgets' do
+    samples, budgets = PerformanceSamples.fixture
+    samples['cases'].each do |item|
+      html = item['id'].start_with?('docs.')
+      (item['self_pairs'] + item['pairs']).each do |pair|
+        %w[baseline candidate].each do |role|
+          actual = samples['observations'][pair[role]['observation']]['source']['sha']
+          value = actual == samples['baseline_sha'] ? 'before' : 'after'
+          body = html ? "<!doctype html><html><body>#{value}</body></html>" : JSON.generate(status: true, response: value)
+          replace_response(pair[role], body, json: !html)
+        end
+      end
+    end
+    code, report = compare_cli(samples, budgets)
+    expect(code).to eq(0)
+    expect(report['status']).to eq('pass')
+    expect(report['cases'].map { |item| item['responses'].slice('raw_changed', 'canonical_changed') }).to all(eq('raw_changed' => true, 'canonical_changed' => true))
+    %w[wall_seconds cpu_seconds allocated_objects].each do |metric|
+      changed = Marshal.load(Marshal.dump(samples))
+      changed['cases'].first['pairs'].each { |pair| pair['candidate'][metric] = metric == 'allocated_objects' ? 140 : 3.0 }
+      regression_code, regression_report = compare_cli(changed, budgets)
+      expect(regression_code).to eq(1), metric
+      expect(regression_report['status']).to eq('regression')
+    end
+  end
+
+  it 'rejects canonical variation within a source including the second baseline/self column' do
+    %w[self_pairs pairs].each do |group|
+      samples, budgets = PerformanceSamples.fixture
+      replace_response(samples['cases'].first[group].last['candidate'], '{"status":true,"response":"changed"}')
+      code, report = compare_cli(samples, budgets)
+      expect(code).to eq(3)
+      expected_sha = samples[group == 'self_pairs' ? 'baseline_sha' : 'candidate_sha']
+      expect(report.dig('error', 'message')).to eq("Response identity differs within revision #{expected_sha}")
+    end
+  end
+
+  it 'replays benchmark inputs with different unused contributor flakes and rejects tampered consumed or source inputs' do
+    %w[quick weekly].each do |profile|
+      samples, budgets = PerformanceSamples.fixture(profile:)
+      tool = HaveAPI::Performance::BENCHMARK_INPUTS.to_h do |path|
+        content = "controlled #{path}\n"
+        [path, { 'content' => content, 'sha256' => Digest::SHA256.hexdigest(content) }]
+      end
+      samples.fetch('observations').each_value do |observation|
+        role = observation.fetch('source').fetch('sha') == samples['baseline_sha'] ? 'baseline' : 'candidate'
+        inputs = Marshal.load(Marshal.dump(observation.fetch('inputs')))
+        inputs['benchmark'] = tool
+        inputs['locks'] = { 'servers/ruby/benchmarks/Gemfile.lock' => tool.fetch('servers/ruby/benchmarks/Gemfile.lock').fetch('sha256') }
+        inputs['contributor_flakes'] = %w[flake.nix flake.lock].to_h { |path| [path, { 'content' => "#{role} #{path}" }] }
+        inputs['contributor_flakes'].each do |path, input|
+          samples['sources'][role]['files_sha256'][path] = Digest::SHA256.hexdigest(input.fetch('content'))
+        end
+        inputs['manifests']['.ruby-version'] = Digest::SHA256.hexdigest('3.2.0')
+        samples['sources'][role]['files_sha256']['.ruby-version'] = inputs['manifests']['.ruby-version']
+        observation['inputs'] = inputs
+      end
+      samples['inputs'] = HaveAPI::Performance::Release.graph(samples['observations']['baseline']['inputs'])
+      expect(compare_cli(samples, budgets).first).to eq(0)
+      %w[tool lock raw-flake declaration ruby].each do |fault|
+        changed = Marshal.load(Marshal.dump(samples))
+        inputs = changed['observations']['candidate']['inputs']
+        case fault
+        when 'tool' then inputs['benchmark']['servers/ruby/benchmarks/shell.nix']['content'] << 'tampered'
+        when 'lock' then inputs['locks']['servers/ruby/benchmarks/Gemfile.lock'] = 'f' * 64
+        when 'raw-flake' then inputs['contributor_flakes']['flake.nix']['content'] << 'tampered'
+        when 'declaration' then inputs['manifests']['servers/ruby/Gemfile'] = 'f' * 64
+        else inputs['manifests']['.ruby-version'] = 'f' * 64
+        end
+        expect(compare_cli(changed, budgets).first).to eq(3), "#{profile}:#{fault}"
+      end
+    end
+  end
+
   it 'rejects unsupported sample formats without converting historical evidence' do
     samples, budgets = PerformanceSamples.fixture
     samples['schema_version'] = 1
@@ -170,7 +271,7 @@ describe HaveAPI::Performance::Comparator do
     end
   end
 
-  it 'compares response occurrence totals across revisions without retaining request order' do
+  it 'compares response occurrence totals within each revision without retaining request order' do
     samples, json = PerformanceSamples.fixture
     spec = samples['cases'].first
     spec['iterations'] = 3
@@ -178,7 +279,7 @@ describe HaveAPI::Performance::Comparator do
       %w[baseline candidate].each do |role|
         sample = pair[role]
         output = sample['outputs'].first
-        body = sample['bodies'].values.first['body'].sub('"zero":0', '"zero":1')
+        body = sample['bodies'].values.first['body'].sub('"zero":0', '"zero":100')
         canonical = JSON.parse(body)
         digest = Digest::SHA256.hexdigest(body)
         sample['bodies'][digest] = { 'body' => body, 'canonical_body' => canonical }
@@ -189,9 +290,16 @@ describe HaveAPI::Performance::Comparator do
       end
     end
     comparator = described_class.new(samples, JSON.parse(json), budget_sha256: samples['budget_sha256'])
-    expect(comparator.compare['status']).to eq('pass')
+    report = comparator.compare
+    expect(report['status']).to eq('pass')
+    original_bytes = spec['pairs'].first['baseline']['outputs'].first['body_bytes']
+    expect(report['cases'].first.dig('responses', 'bytes_per_request', 'baseline')).to be_within(0.00001).of(original_bytes + (4.0 / 3))
     spec['pairs'].last['candidate']['outputs'].reverse!
     expect(comparator.compare['status']).to eq('pass')
+    spec['pairs'].each { |pair| pair['candidate']['outputs'].each { |example| example['count'] = 3 - example['count'] } }
+    report = comparator.compare
+    expect(report['status']).to eq('pass')
+    expect(report['cases'].first.dig('responses', 'canonical_changed')).to be(true)
     spec['pairs'].last['candidate']['outputs'].each { |example| example['count'] = 3 - example['count'] }
     expect { comparator.compare }.to raise_error(HaveAPI::Performance::ContractError, /Response identity/)
   end
@@ -226,7 +334,29 @@ describe HaveAPI::Performance::Comparator do
     body = JSON.parse(target['bodies'].values.first['body'])
     body['response'] = body['response'].to_a.reverse.to_h
     replace_raw_body(target, JSON.generate(body.to_a.reverse.to_h))
-    expect(compare_cli(samples, budgets).first).to eq(0)
+    code, report = compare_cli(samples, budgets)
+    expect(code).to eq(0)
+    expect(report['cases'].first['responses']).to include('raw_changed' => true, 'canonical_changed' => false)
+    expect(report['cases'].first.dig('responses', 'bytes_per_request', 'delta')).to eq(0)
+  end
+
+  it 'reports weighted byte deltas from baseline/candidate pairs without self-pair bias or a raw determinism requirement' do
+    samples, budgets = PerformanceSamples.fixture
+    item = samples['cases'].first
+    baseline_bytes = item['pairs'].first['baseline']['outputs'].first['body_bytes']
+    item['self_pairs'].each do |pair|
+      %w[baseline candidate].each { |role| replace_raw_body(pair[role], " #{pair[role]['bodies'].values.first['body']}") }
+    end
+    item['pairs'].last(2).each do |pair|
+      replace_raw_body(pair['candidate'], "  #{pair['candidate']['bodies'].values.first['body']}")
+    end
+    code, report = compare_cli(samples, budgets)
+    expect(code).to eq(0)
+    response = report['cases'].first['responses']
+    expect(response).to include('raw_changed' => true, 'canonical_changed' => false)
+    expect(response['bytes_per_request']).to include('baseline' => baseline_bytes, 'candidate' => baseline_bytes + 0.8)
+    expect(response['bytes_per_request']['delta']).to be_within(0.00001).of(0.8)
+    expect(response['bytes_per_request']['delta_percent']).to be_within(0.00001).of(80.0 / baseline_bytes)
   end
 
   it 'rejects identical source SHAs even with consistently rebound provenance' do