lex-llm 0.6.16 → 0.7.2

data/spec/legion/extensions/llm/inventory/callable_handle_spec.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/callable_handle'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::CallableHandle do
+  let(:errors) { Legion::Extensions::Llm::Inventory::Errors }
+
+  # Minimal callable recording exactly-once disconnect; no registry/provider hooks.
+  let(:callable_class) do
+    Class.new do
+      attr_reader :disconnect_count
+
+      def initialize
+        @disconnect_count = 0
+      end
+
+      def disconnect
+        @disconnect_count += 1
+      end
+    end
+  end
+
+  let(:callable) { callable_class.new }
+  let(:handle) { described_class.new(handle_id: 'call:v1:test', callable: callable) }
+
+  describe 'construction' do
+    it 'starts ACTIVE with zero references' do
+      expect(handle.state).to eq(:active)
+      expect(handle.reference_count).to eq(0)
+      expect(handle.handle_id).to eq('call:v1:test')
+    end
+
+    it 'rejects an empty handle_id and a nil callable' do
+      expect { described_class.new(handle_id: '', callable: callable) }.to raise_error(errors::ValidationError)
+      expect { described_class.new(handle_id: 'call:v1:x', callable: nil) }.to raise_error(errors::ValidationError)
+    end
+  end
+
+  describe '#acquire' do
+    it 'increments the reference count and returns a lease exposing the exact callable' do
+      lease = handle.acquire
+      expect(handle.reference_count).to eq(1)
+      expect(lease.callable).to equal(callable)
+      expect(lease).not_to be_released
+    end
+
+    it 'returns independent leases with distinct ids' do
+      a = handle.acquire
+      b = handle.acquire
+      expect(handle.reference_count).to eq(2)
+      expect(a.lease_id).not_to eq(b.lease_id)
+    end
+
+    it 'does not disconnect while leases are released back (error/cancellation/stream-close simulation)' do
+      lease = handle.acquire
+      lease.release
+      expect(lease).to be_released
+      expect(handle.reference_count).to eq(0)
+      expect(callable.disconnect_count).to eq(0)
+      expect(handle.state).to eq(:active)
+    end
+  end
+
+  describe '#retire' do
+    it 'disposes immediately and disconnects once when idle' do
+      expect(handle.retire).to eq(:disposed)
+      expect(handle.state).to eq(:disposed)
+      expect(callable.disconnect_count).to eq(1)
+    end
+
+    it 'moves to RETIRING while a lease is outstanding and blocks new acquisition' do
+      lease = handle.acquire
+      expect(handle.retire).to eq(:retiring)
+      expect(handle.state).to eq(:retiring)
+      expect { handle.acquire }.to raise_error(errors::StaleCallableError)
+      expect(callable.disconnect_count).to eq(0)
+
+      lease.release
+      expect(handle.state).to eq(:disposed)
+      expect(callable.disconnect_count).to eq(1)
+    end
+
+    it 'raises CallableDisposedError on acquire after disposal' do
+      handle.retire
+      expect { handle.acquire }.to raise_error(errors::CallableDisposedError)
+    end
+
+    it 'disconnects exactly once even with multiple leases' do
+      a = handle.acquire
+      b = handle.acquire
+      handle.retire
+      a.release
+      expect(callable.disconnect_count).to eq(0)
+      b.release
+      expect(callable.disconnect_count).to eq(1)
+      expect(handle.state).to eq(:disposed)
+    end
+  end
+
+  describe 'release safety' do
+    it 'raises on duplicate release and does not decrement twice' do
+      a = handle.acquire
+      b = handle.acquire
+      a.release
+      expect { a.release }.to raise_error(errors::InvalidTransitionError)
+      expect(handle.reference_count).to eq(1)
+      b.release
+      expect(handle.reference_count).to eq(0)
+    end
+  end
+
+  describe 'disconnect failure' do
+    let(:callable_class) do
+      Class.new do
+        def disconnect
+          raise StandardError, 'boom'
+        end
+      end
+    end
+
+    it 'still becomes DISPOSED and returns :disposed_with_error without raising' do
+      expect(handle.retire).to eq(:disposed_with_error)
+      expect(handle.state).to eq(:disposed)
+    end
+  end
+end

data/spec/legion/extensions/llm/inventory/evidence_spec.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/evidence'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::Evidence do
+  let(:errors) { Legion::Extensions::Llm::Inventory::Errors }
+  let(:operation_evidence) { Legion::Extensions::Llm::Inventory::OperationEvidence }
+  let(:capability_evidence) { Legion::Extensions::Llm::Inventory::CapabilityEvidence }
+  let(:value_evidence) { Legion::Extensions::Llm::Inventory::ValueEvidence }
+
+  describe 'OperationEvidence' do
+    it 'stores a canonical operation and exposes exact predicates' do
+      ev = operation_evidence.new(operation: :chat, status: :supported, source: :provider_implementation)
+      expect(ev.operation).to eq(:chat)
+      expect(ev).to be_supported
+      expect(ev).not_to be_unknown
+    end
+
+    it 'keeps stream_chat as the operation and never canonicalizes to capability streaming' do
+      ev = operation_evidence.new(operation: :stream_chat, status: :supported, source: :provider_catalog)
+      expect(ev.operation).to eq(:stream_chat)
+      expect(ev.operation).not_to eq(:streaming)
+    end
+
+    it 'rejects an operation alias when allow_aliases is false (registry path)' do
+      expect { operation_evidence.new(operation: :stream, status: :supported, source: :provider_catalog) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects an unknown operation' do
+      expect { operation_evidence.new(operation: :nonsense, status: :unknown, source: :absent) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects a status outside supported/unsupported/unknown' do
+      expect { operation_evidence.new(operation: :chat, status: :maybe, source: :provider_implementation) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects a source outside EVIDENCE_SOURCES' do
+      expect { operation_evidence.new(operation: :chat, status: :supported, source: :made_up) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'requires unknown status for an unknown-only source' do
+      expect { operation_evidence.new(operation: :chat, status: :supported, source: :default_false) }
+        .to raise_error(errors::ValidationError)
+      expect { operation_evidence.new(operation: :chat, status: :unknown, source: :default_false) }
+        .not_to raise_error
+    end
+
+    it 'freezes copied metadata' do
+      ev = operation_evidence.new(
+        operation: :chat, status: :supported, source: :provider_implementation, metadata: { note: +'x' }
+      )
+      expect(ev.metadata).to be_frozen
+      expect(ev.metadata[:note]).to be_frozen
+    end
+
+    it 'duplicates and freezes observed_at but rejects a non-Time' do
+      now = Time.now
+      ev = operation_evidence.new(operation: :chat, status: :supported, source: :probe, observed_at: now)
+      expect(ev.observed_at).to be_frozen
+      expect(ev.observed_at).not_to equal(now)
+      expect { operation_evidence.new(operation: :chat, status: :supported, source: :probe, observed_at: 5) }
+        .to raise_error(errors::ValidationError)
+    end
+  end
+
+  describe 'CapabilityEvidence' do
+    it 'canonicalizes a capability alias' do
+      ev = capability_evidence.new(capability: :tool_use, status: :supported, source: :provider_implementation)
+      expect(ev.capability).to eq(:tools)
+    end
+
+    it 'canonicalizes the stream_chat capability alias to streaming (distinct from the operation)' do
+      ev = capability_evidence.new(capability: :stream_chat, status: :supported, source: :provider_catalog)
+      expect(ev.capability).to eq(:streaming)
+    end
+
+    it 'rejects a non-canonical capability' do
+      expect { capability_evidence.new(capability: :telepathy, status: :unknown, source: :absent) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'requires unknown status for guessed/default_false/failed_probe sources' do
+      %i[guessed default_false failed_probe inconclusive_probe].each do |source|
+        expect { capability_evidence.new(capability: :vision, status: :unsupported, source: source) }
+          .to raise_error(errors::ValidationError)
+        expect { capability_evidence.new(capability: :vision, status: :unknown, source: source) }
+          .not_to raise_error
+      end
+    end
+
+    it 'never lets config/override sources carry :supported (enable_* is consumed router-side, not published)' do
+      %i[model_override instance_override provider_override].each do |source|
+        expect { capability_evidence.new(capability: :tools, status: :supported, source: source) }
+          .to raise_error(errors::ValidationError)
+        expect { capability_evidence.new(capability: :thinking, status: :supported, source: source) }
+          .to raise_error(errors::ValidationError)
+        expect { operation_evidence.new(operation: :chat, status: :supported, source: source) }
+          .to raise_error(errors::ValidationError)
+        expect { capability_evidence.new(capability: :tools, status: :unknown, source: source) }
+          .not_to raise_error
+      end
+    end
+  end
+
+  describe 'ValueEvidence' do
+    it 'requires a non-nil value when known and copies/freezes it' do
+      ev = value_evidence.new(status: :known, value: 128_000, source: :model_metadata)
+      expect(ev).to be_known
+      expect(ev.value).to eq(128_000)
+    end
+
+    it 'freezes a known collection value' do
+      ev = value_evidence.new(status: :known, value: [512, 1024], source: :provider_catalog)
+      expect(ev.value).to be_frozen
+    end
+
+    it 'rejects a known status with a nil value' do
+      expect { value_evidence.new(status: :known, value: nil, source: :model_metadata) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'requires nil value when unknown' do
+      expect { value_evidence.new(status: :unknown, value: 5, source: :absent) }
+        .to raise_error(errors::ValidationError)
+      expect(value_evidence.new(status: :unknown, source: :absent)).to be_unknown
+    end
+
+    it 'enforces the unknown-only source rule' do
+      expect { value_evidence.new(status: :known, value: 10, source: :guessed) }
+        .to raise_error(errors::ValidationError)
+    end
+  end
+end

data/spec/legion/extensions/llm/inventory/identity_spec.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/identity'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::Identity do
+  let(:errors) { Legion::Extensions::Llm::Inventory::Errors }
+  let(:instance_key_class) { Legion::Extensions::Llm::Inventory::Identity::InstanceKey }
+
+  fixture_path = File.expand_path('../conformance/fixtures/ssot_identity_vectors.json', __dir__)
+  fixture = Legion::JSON.load(File.read(fixture_path))
+
+  def hex(binary)
+    binary.b.unpack1('H*')
+  end
+
+  describe 'binding identity vectors (recomputed field by field)' do
+    fixture[:vectors].each_with_index do |vector, index|
+      context "with vector #{index}: #{vector[:provider_family]}+#{vector[:instance_id]}" do
+        let(:instance_key) do
+          instance_key_class.new(
+            provider_family: vector[:provider_family],
+            instance_id: vector[:instance_id]
+          )
+        end
+
+        it 'reproduces every framed field as lowercase hex bytes' do
+          expect(hex(described_class.length_frame(value: instance_key.provider_family)))
+            .to eq(vector[:framed_hex][:provider_family])
+          expect(hex(described_class.length_frame(value: instance_key.instance_id)))
+            .to eq(vector[:framed_hex][:instance_id])
+          expect(hex(described_class.length_frame(value: vector[:provider_native_key])))
+            .to eq(vector[:framed_hex][:provider_native_key])
+          expect(hex(described_class.length_frame(value: vector[:operation])))
+            .to eq(vector[:framed_hex][:operation])
+          expect(hex(described_class.length_frame(value: vector[:model])))
+            .to eq(vector[:framed_hex][:model])
+        end
+
+        it 'reproduces the offering hash input and offering_id' do
+          input = described_class.length_frame(value: instance_key.provider_family) +
+                  described_class.length_frame(value: instance_key.instance_id) +
+                  described_class.length_frame(value: vector[:provider_native_key])
+          expect(hex(input)).to eq(vector[:offering_hash_input_hex])
+
+          offering_id = described_class.offering_id(
+            instance_key: instance_key, provider_native_key: vector[:provider_native_key]
+          )
+          expect(offering_id).to eq(vector[:expected_offering_id])
+        end
+
+        it 'reproduces the lane hash input and lane_id' do
+          offering_id = described_class.offering_id(
+            instance_key: instance_key, provider_native_key: vector[:provider_native_key]
+          )
+          input = "lane-v1\x00".b +
+                  described_class.length_frame(value: instance_key.provider_family) +
+                  described_class.length_frame(value: instance_key.instance_id) +
+                  described_class.length_frame(value: vector[:operation]) +
+                  described_class.length_frame(value: vector[:model]) +
+                  described_class.length_frame(value: offering_id)
+          expect(hex(input)).to eq(vector[:lane_hash_input_hex])
+
+          lane_id = described_class.lane_id(
+            instance_key: instance_key,
+            operation: vector[:operation].to_sym,
+            model: vector[:model],
+            offering_id: offering_id
+          )
+          expect(lane_id).to eq(vector[:expected_lane_id])
+        end
+
+        it 'validates the reproduced offering_id and lane_id' do
+          offering_id = vector[:expected_offering_id]
+          expect(
+            described_class.validate_offering_id!(
+              value: offering_id, instance_key: instance_key, provider_native_key: vector[:provider_native_key]
+            )
+          ).to eq(offering_id)
+          expect(
+            described_class.validate_lane_id!(
+              value: vector[:expected_lane_id], instance_key: instance_key,
+              operation: vector[:operation].to_sym, model: vector[:model], offering_id: offering_id
+            )
+          ).to eq(vector[:expected_lane_id])
+        end
+      end
+    end
+  end
+
+  describe 'independence and delimiter safety' do
+    it 'produces distinct offering/lane IDs for the same model on two instance IDs' do
+      expect(fixture[:vectors][0][:expected_offering_id]).not_to eq(fixture[:vectors][1][:expected_offering_id])
+      expect(fixture[:vectors][0][:expected_lane_id]).not_to eq(fixture[:vectors][1][:expected_lane_id])
+    end
+
+    it 'is tier-independent: tier is never a framing input' do
+      vector = fixture[:vectors][0]
+      instance_key = instance_key_class.new(provider_family: vector[:provider_family], instance_id: vector[:instance_id])
+      %i[local frontier].each do |_tier|
+        offering_id = described_class.offering_id(
+          instance_key: instance_key, provider_native_key: vector[:provider_native_key]
+        )
+        expect(offering_id).to eq(vector[:expected_offering_id])
+        expect(
+          described_class.lane_id(
+            instance_key: instance_key, operation: vector[:operation].to_sym,
+            model: vector[:model], offering_id: offering_id
+          )
+        ).to eq(vector[:expected_lane_id])
+      end
+    end
+
+    it 'frames punctuation inside a component without delimiter ambiguity' do
+      vector = fixture[:vectors][2]
+      instance_key = instance_key_class.new(provider_family: vector[:provider_family], instance_id: vector[:instance_id])
+      expect(instance_key.instance_id).to eq('prod:eastus')
+      expect(
+        described_class.offering_id(instance_key: instance_key, provider_native_key: vector[:provider_native_key])
+      ).to eq(vector[:expected_offering_id])
+    end
+  end
+
+  describe '.length_frame' do
+    it 'is decimal byte length + ASCII colon + exact UTF-8 bytes, in binary' do
+      frame = described_class.length_frame(value: 'gemma4')
+      expect(frame.encoding).to eq(Encoding::BINARY)
+      expect(frame).to eq('6:gemma4'.b)
+    end
+
+    it 'counts UTF-8 bytes, not characters' do
+      composed = [0x00e9].pack('U*') # single codepoint => two UTF-8 bytes
+      expect(described_class.length_frame(value: composed)).to eq('2:'.b + composed.b)
+    end
+  end
+
+  describe '.normalize_text' do
+    it 'accepts String and Symbol and returns a frozen UTF-8 String' do
+      result = described_class.normalize_text(value: :vllm, field: :provider_family)
+      expect(result).to eq('vllm')
+      expect(result).to be_frozen
+    end
+
+    it 'trims surrounding whitespace' do
+      expect(described_class.normalize_text(value: '  h200  ', field: :instance_id)).to eq('h200')
+    end
+
+    it 'rejects empty and whitespace-only values' do
+      expect { described_class.normalize_text(value: '   ', field: :f) }.to raise_error(errors::ValidationError)
+      expect { described_class.normalize_text(value: '', field: :f) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects invalid UTF-8' do
+      expect { described_class.normalize_text(value: "\xFF".b, field: :f) }.to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects a non-NFC (decomposed) string' do
+      decomposed = [0x0065, 0x0301].pack('U*') # e + combining acute; not NFC
+      expect { described_class.normalize_text(value: decomposed, field: :f) }
+        .to raise_error(errors::ValidationError, /NFC/)
+    end
+
+    it 'rejects a non-text type' do
+      expect { described_class.normalize_text(value: 5, field: :f) }.to raise_error(errors::ValidationError)
+    end
+  end
+
+  describe '.normalize_enum' do
+    it 'returns an allowed symbol' do
+      expect(described_class.normalize_enum(value: 'local', field: :tier, allowed: %i[local frontier])).to eq(:local)
+    end
+
+    it 'rejects a value not in the allowed set' do
+      expect { described_class.normalize_enum(value: :nope, field: :tier, allowed: %i[local]) }
+        .to raise_error(errors::ValidationError)
+    end
+  end
+
+  describe 'InstanceKey' do
+    it 'downcases provider_family to a Symbol and preserves instance_id case' do
+      key = instance_key_class.new(provider_family: 'Azure_Foundry', instance_id: 'Prod:EastUS')
+      expect(key.provider_family).to eq(:azure_foundry)
+      expect(key.instance_id).to eq('Prod:EastUS')
+    end
+
+    it 'exposes to_h with the three fields (physical_id nil by default)' do
+      key = instance_key_class.new(provider_family: :vllm, instance_id: 'h200')
+      expect(key.to_h).to eq(provider_family: :vllm, instance_id: 'h200', physical_id: nil)
+    end
+
+    it 'is value-equal for equal normalized fields' do
+      a = instance_key_class.new(provider_family: 'vllm', instance_id: 'h200')
+      b = instance_key_class.new(provider_family: :vllm, instance_id: '  h200 ')
+      expect(a).to eq(b)
+      expect(a.hash).to eq(b.hash)
+    end
+
+    it 'rejects a provider_family that is not snake-case ASCII' do
+      expect { instance_key_class.new(provider_family: '1bad', instance_id: 'x') }
+        .to raise_error(errors::ValidationError)
+      expect { instance_key_class.new(provider_family: 'has space', instance_id: 'x') }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects the reserved instance_id "default"' do
+      expect { instance_key_class.new(provider_family: 'vllm', instance_id: 'default') }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'rejects nil fields' do
+      expect { instance_key_class.new(provider_family: nil, instance_id: 'x') }
+        .to raise_error(errors::ValidationError)
+      expect { instance_key_class.new(provider_family: 'vllm', instance_id: nil) }
+        .to raise_error(errors::ValidationError)
+    end
+
+    it 'keeps the two-argument constructor working (physical_id defaults to nil)' do
+      key = instance_key_class.new(provider_family: :vllm, instance_id: 'apollo')
+      expect(key.physical_id).to be_nil
+    end
+
+    describe 'physical_id (secondary, not identity)' do
+      it 'normalizes like identity text: trims, NFC, frozen String' do
+        key = instance_key_class.new(provider_family: :vllm, instance_id: 'apollo', physical_id: '  10.0.0.1:8000/ak:abc123 ')
+        expect(key.physical_id).to eq('10.0.0.1:8000/ak:abc123')
+        expect(key.physical_id).to be_frozen
+      end
+
+      it 'preserves the physical id for diagnostics while identity stays the config name' do
+        key = instance_key_class.new(
+          provider_family: :vllm, instance_id: 'apollo', physical_id: '10.0.0.1:8000/ak:abc123'
+        )
+        expect(key.instance_id).to eq('apollo')
+        expect(key.physical_id).to eq('10.0.0.1:8000/ak:abc123')
+      end
+
+      it 'excludes physical_id from equality and hashing' do
+        bare = instance_key_class.new(provider_family: :vllm, instance_id: 'apollo')
+        with_physical = instance_key_class.new(
+          provider_family: :vllm, instance_id: 'apollo', physical_id: '10.0.0.1:8000/ak:abc123'
+        )
+        other_physical = instance_key_class.new(
+          provider_family: :vllm, instance_id: 'apollo', physical_id: '10.0.0.9:9000'
+        )
+        expect(bare).to eq(with_physical)
+        expect(bare.hash).to eq(with_physical.hash)
+        expect(with_physical).to eq(other_physical)
+        expect({ bare => :found }[with_physical]).to eq(:found)
+      end
+
+      it 'does not reserve "default" for physical_id (only instance_id is reserved)' do
+        key = instance_key_class.new(provider_family: :vllm, instance_id: 'apollo', physical_id: 'default')
+        expect(key.physical_id).to eq('default')
+      end
+
+      it 'rejects a blank or non-text physical_id' do
+        expect { instance_key_class.new(provider_family: 'vllm', instance_id: 'x', physical_id: '   ') }
+          .to raise_error(errors::ValidationError)
+        expect { instance_key_class.new(provider_family: 'vllm', instance_id: 'x', physical_id: 5) }
+          .to raise_error(errors::ValidationError)
+      end
+
+      it 'still distinguishes distinct config names on the same physical endpoint' do
+        apollo = instance_key_class.new(provider_family: :ollama, instance_id: 'apollo', physical_id: 'localhost:11434')
+        apollo_embed = instance_key_class.new(provider_family: :ollama, instance_id: 'apollo-embed', physical_id: 'localhost:11434')
+        expect(apollo).not_to eq(apollo_embed)
+      end
+    end
+  end
+
+  describe 'public surface' do
+    it 'exposes exactly the seven documented module methods' do
+      expected = %i[
+        normalize_text normalize_enum length_frame offering_id lane_id
+        validate_offering_id! validate_lane_id!
+      ].sort
+      expect(described_class.singleton_methods(false).sort).to eq(expected)
+    end
+  end
+end

data/spec/legion/extensions/llm/inventory/immutable_value_spec.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/immutable_value'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::ImmutableValue do
+  subject(:copy) { described_class.copy_and_freeze(value: value, field: :meta) }
+
+  describe 'scalar passthrough' do
+    it 'returns nil, booleans, symbols, and integers unchanged' do
+      [nil, true, false, :sym, 0, -5, 2**80].each do |scalar|
+        expect(described_class.copy_and_freeze(value: scalar, field: :f)).to eq(scalar)
+      end
+    end
+
+    it 'accepts finite floats' do
+      expect(described_class.copy_and_freeze(value: 1.5, field: :f)).to eq(1.5)
+    end
+
+    it 'rejects NaN' do
+      expect { described_class.copy_and_freeze(value: (0.0 / 0.0), field: :f) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError, /f is not a finite Float/)
+    end
+
+    it 'rejects positive and negative infinity' do
+      expect { described_class.copy_and_freeze(value: (1.0 / 0.0), field: :f) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError)
+      expect { described_class.copy_and_freeze(value: (-1.0 / 0.0), field: :f) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError)
+    end
+  end
+
+  describe 'strings' do
+    let(:value) { +'hello' }
+
+    it 'returns a frozen copy' do
+      expect(copy).to eq('hello')
+      expect(copy).to be_frozen
+    end
+
+    it 'does not retain the original mutable reference' do
+      original = +'mutable'
+      result = described_class.copy_and_freeze(value: original, field: :f)
+      expect(result).not_to equal(original)
+    end
+
+    it 'rejects invalid UTF-8' do
+      bad = "\xFF\xFE".b
+      expect { described_class.copy_and_freeze(value: bad, field: :f) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError, /not valid UTF-8/)
+    end
+  end
+
+  describe 'Time' do
+    let(:value) { Time.now }
+
+    it 'duplicates and freezes' do
+      original = Time.now
+      result = described_class.copy_and_freeze(value: original, field: :f)
+      expect(result).to eq(original)
+      expect(result).to be_frozen
+      expect(result).not_to equal(original)
+    end
+  end
+
+  describe 'arrays and hashes' do
+    it 'deeply freezes nested arrays preserving order' do
+      result = described_class.copy_and_freeze(value: [3, [2, [1]]], field: :f)
+      expect(result).to eq([3, [2, [1]]])
+      expect(result).to be_frozen
+      expect(result[1]).to be_frozen
+      expect(result[1][1]).to be_frozen
+    end
+
+    it 'deeply freezes nested hashes and preserves insertion order' do
+      result = described_class.copy_and_freeze(value: { b: 1, a: { c: [1] } }, field: :f)
+      expect(result.keys).to eq(%i[b a])
+      expect(result).to be_frozen
+      expect(result[:a]).to be_frozen
+      expect(result[:a][:c]).to be_frozen
+    end
+
+    it 'accepts String and Symbol hash keys and freezes String keys' do
+      result = described_class.copy_and_freeze(value: { 'x' => 1, y: 2 }, field: :f)
+      expect(result.keys.map(&:frozen?)).to all(be(true))
+    end
+
+    it 'rejects a non-String/Symbol hash key' do
+      expect { described_class.copy_and_freeze(value: { 1 => :v }, field: :f) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError, %r{non-String/Symbol key})
+    end
+
+    it 'does not retain nested mutable references from the original' do
+      inner = +'inner'
+      original = { list: [inner] }
+      result = described_class.copy_and_freeze(value: original, field: :f)
+      inner << '-mutated'
+      expect(result[:list].first).to eq('inner')
+    end
+  end
+
+  describe 'rejections' do
+    it 'rejects an unsupported object' do
+      expect { described_class.copy_and_freeze(value: Object.new, field: :f) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError, /unsupported value type/)
+    end
+
+    it 'rejects a callable' do
+      expect { described_class.copy_and_freeze(value: -> { 1 }, field: :f) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError, /unsupported value type/)
+    end
+
+    it 'rejects a cyclic array naming the field path' do
+      cyclic = []
+      cyclic << cyclic
+      expect { described_class.copy_and_freeze(value: cyclic, field: :meta) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError, /meta.*cyclic/)
+    end
+
+    it 'rejects a cyclic hash' do
+      cyclic = {}
+      cyclic[:self] = cyclic
+      expect { described_class.copy_and_freeze(value: cyclic, field: :meta) }
+        .to raise_error(Legion::Extensions::Llm::Inventory::Errors::ValidationError, /cyclic/)
+    end
+
+    it 'allows the same non-cyclic object referenced twice' do
+      shared = { k: 1 }
+      expect { described_class.copy_and_freeze(value: [shared, shared], field: :f) }.not_to raise_error
+    end
+  end
+end