Module: Legion::Extensions::Llm::Inventory::Identity

Defined in:
lib/legion/extensions/llm/inventory/identity.rb

Overview

Canonical field normalization plus the off:v1: and lane:v1: length-framed SHA-256 encoders/validators. See phase-1-lex-llm-additive.md section 8.

Framing is binary: decimal UTF-8 byte length, ASCII ':', then the exact UTF-8 bytes. It never uses a delimiter join, Ruby hash order, object ID, or Ruby Hash#hash. Tier is never an identity input.

Defined Under Namespace

Classes: InstanceKey

Class Method Summary collapse

Class Method Details

.lane_id(instance_key:, operation:, model:, offering_id:) ⇒ Object 



59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/legion/extensions/llm/inventory/identity.rb', line 59

def lane_id(instance_key:, operation:, model:, offering_id:)
  digest = ::Digest::SHA256.hexdigest(
    "lane-v1\x00".b +
    length_frame(value: instance_key.provider_family) +
    length_frame(value: instance_key.instance_id) +
    length_frame(value: operation) +
    length_frame(value: model) +
    length_frame(value: offering_id)
  )
  "lane:v1:#{digest}"
end

.length_frame(value:) ⇒ Object 



45
46
47
48
 
# File 'lib/legion/extensions/llm/inventory/identity.rb', line 45

def length_frame(value:)
  bytes = value.to_s.b
  "#{bytes.bytesize}:".b + bytes
end

.normalize_enum(value:, field:, allowed:) ⇒ Object

Raises:



33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/legion/extensions/llm/inventory/identity.rb', line 33

def normalize_enum(value:, field:, allowed:)
  raise Errors::ValidationError, "#{field} must be a String or Symbol" unless text_input?(value)

  trimmed = value.to_s.strip
  raise Errors::ValidationError, "#{field} must not be empty" if trimmed.empty?

  candidate = trimmed.to_sym
  raise Errors::ValidationError, "#{field} is not one of the allowed values" unless allowed.include?(candidate)

  candidate
end

.normalize_text(value:, field:) ⇒ Object

Raises:



20
21
22
23
24
25
26
27
28
29
30
31
 
# File 'lib/legion/extensions/llm/inventory/identity.rb', line 20

def normalize_text(value:, field:)
  raise Errors::ValidationError, "#{field} must be a String or Symbol" unless text_input?(value)

  string = value.to_s
  raise Errors::ValidationError, "#{field} is not valid UTF-8" unless valid_utf8?(string)

  trimmed = utf8(string).strip
  raise Errors::ValidationError, "#{field} must not be empty" if trimmed.empty?
  raise Errors::ValidationError, "#{field} must be NFC-normalized" unless trimmed.unicode_normalized?(:nfc)

  trimmed.freeze
end

.offering_id(instance_key:, provider_native_key:) ⇒ Object 



50
51
52
53
54
55
56
57
 
# File 'lib/legion/extensions/llm/inventory/identity.rb', line 50

def offering_id(instance_key:, provider_native_key:)
  digest = ::Digest::SHA256.hexdigest(
    length_frame(value: instance_key.provider_family) +
    length_frame(value: instance_key.instance_id) +
    length_frame(value: provider_native_key)
  )
  "off:v1:#{digest}"
end

.validate_lane_id!(value:, instance_key:, operation:, model:, offering_id:) ⇒ Object

Raises:



78
79
80
81
82
83
84
85
 
# File 'lib/legion/extensions/llm/inventory/identity.rb', line 78

def validate_lane_id!(value:, instance_key:, operation:, model:, offering_id:)
  expected = lane_id(
    instance_key: instance_key, operation: operation, model: model, offering_id: offering_id
  )
  raise Errors::ValidationError, 'lane_id does not reproduce from its identity fields' unless value == expected

  value
end

.validate_offering_id!(value:, instance_key:, provider_native_key:) ⇒ Object

Raises:



71
72
73
74
75
76
 
# File 'lib/legion/extensions/llm/inventory/identity.rb', line 71

def validate_offering_id!(value:, instance_key:, provider_native_key:)
  expected = offering_id(instance_key: instance_key, provider_native_key: provider_native_key)
  raise Errors::ValidationError, 'offering_id does not reproduce from its identity fields' unless value == expected

  value
end