lex-llm-ledger 0.3.3 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfcca825db5b0e313cbeafc6c9f396b3f964dd4debd911854c89affe3bcb79ef
-  data.tar.gz: 1a4ea16c0c4ca34cc1ae4e3d0efa19cab3948c932162d9072c21127dae1ea375
+  metadata.gz: 9d96639d6f6bf123c338c0df58c4e25d1375d0102873318197f6297eeda70a80
+  data.tar.gz: 1ebcbc88558e3783595e3c07c13eb0f9d0f3fbb82a2c096cb52752592c469d2a
 SHA512:
-  metadata.gz: 362b96b3b385cfcca6c2edbe3fa9c6e30a23fbaa80bd5136fa1f95cc35af8ea5aa93ea89cd7cf1415999ac82ce881311aeea084ee44ba19cffadcbef0858a71b
-  data.tar.gz: 89c63b437c02355a9cc39182d42ac0a1971b7dcdf80473d7ef237d92bbb39cef96c13dd0ea3b34f13d6ed1f662cb6bb30aa473658dde119739b641bbf7b92dac
+  metadata.gz: 670f7c45555f557aae91ba858831f1ce40e74eaf92a5390a965e2d5e6487a6b6deb9700527a6098bd8454b2085fbe1de567195d4a7f54b8f910921d6dde9535f
+  data.tar.gz: a72b7dac0f47bf49ca637f060698899d8eb2fc1d7436e2271afbddb8ef5684a00e5b75ae264ac6d635bc9ac58b9e79fab84070b4b51878324615d939942a9ef7

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## [0.4.2] - 2026-05-22
+
+### Fixed
+- Dead-letter tool audit messages with missing parent response rows via `UnrecoverableMessageError` so the subscription rejects the RabbitMQ delivery with `requeue: false` instead of acknowledging, republishing, or blocking inside a runner-local sleep/retry loop.
+- Set the `llm.registry.availability` subscription actor prefetch to 4 so registry availability events can drain with modest concurrency.
+
+## [0.4.1] - 2026-05-18
+
+### Fixed
+- Tool write retries once after 1s when parent response row is not yet committed (race between async metering publish and tool audit AMQP delivery)
+- Raises `ResponseNotReady` instead of silently returning nil when response row is missing
+
+
+## [0.4.0] - 2026-05-17
+
+### Changed
+- Rewrite `Runners::Tools` to write tool audit events to the official `llm_tool_calls` and
+  `llm_tool_call_attempts` tables instead of the legacy `llm_tool_records` table.
+- Each tool audit event produces one `llm_tool_calls` row (linked to the parent
+  `llm_message_inference_responses` row) and one `llm_tool_call_attempts` row containing
+  the execution outcome.
+- Argument and result payloads are stored as SHA-256 fingerprints in `arguments_ref` /
+  `result_ref` (the official schema columns are 255-char refs, not full JSON blobs).
+- Idempotency is enforced via UUID derived from `tool_call.id` (or request/message context);
+  a second write for the same tool call returns `{ result: :duplicate }`.
+- Tool call writes that cannot be linked to an existing inference response are logged at
+  `warn` and dropped gracefully (returns `{ result: :ok }`).
+- Populate `identity_canonical_name` on every insert in `OfficialRecordWriter`:
+  `llm_conversations`, `llm_messages` (user and assistant), `llm_message_inference_requests`,
+  `llm_message_inference_responses`, and `llm_message_inference_metrics`.
+- Populate `identity_principal_id` and `identity_id` on inserts into `llm_messages`,
+  `llm_message_inference_responses`, and `llm_message_inference_metrics`.
+- Backfill `identity_canonical_name` in `enrich_request!` and `enrich_response!` when the
+  enrichment opportunity arrives after a metering-first write.
+- `Runners::Tools` extracts identity via `CallerIdentity.normalize` and writes
+  `identity_canonical_name`, `identity_principal_id`, and `identity_id` to both
+  `llm_tool_calls` and `llm_tool_call_attempts`.
+- `Runners::RegistryAvailability` writes `identity_canonical_name` from AMQP headers or
+  body identity fields when present; `identity_principal_id` and `identity_id` FK columns
+  are not resolved because node/service identities may not be registered in identity tables.
+
 ## [0.3.3] - 2026-05-17
 
 ### Fixed

data/lex-llm-ledger.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |spec|
   end
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'legion-data',      '>= 1.8.0'
+  spec.add_dependency 'legion-data',      '>= 1.8.7'
   spec.add_dependency 'legion-json',      '>= 1.2'
   spec.add_dependency 'legion-logging',   '>= 1.3'
   spec.add_dependency 'legion-settings',  '>= 1.3'

data/lib/legion/extensions/llm/ledger/actors/registry_availability.rb

@@ -11,6 +11,8 @@ module Legion
           class RegistryAvailability < Legion::Extensions::Actors::Subscription
             include Helpers::SubscriptionActor
 
+            prefetch 4
+
             def runner_class = Legion::Extensions::Llm::Ledger::Runners::RegistryAvailability
 
             def runner_function

data/lib/legion/extensions/llm/ledger/backfill/legacy_llm_records.rb

@@ -13,9 +13,9 @@ module Legion
             extend Legion::Logging::Helper
 
             LEGACY_TABLES = %i[
-              llm_prompt_records
-              llm_metering_records
-              llm_tool_records
+              z_archive_llm_prompt_records
+              z_archive_llm_metering_records
+              z_archive_llm_tool_records
               llm_registry_availability_records
             ].freeze
 
@@ -43,11 +43,11 @@ module Legion
 
             def backfill_row(table, row)
               case table
-              when :llm_prompt_records
+              when :z_archive_llm_prompt_records
                 backfill_prompt(row)
-              when :llm_metering_records
+              when :z_archive_llm_metering_records
                 backfill_metering(row)
-              when :llm_tool_records
+              when :z_archive_llm_tool_records
                 backfill_tool(row)
               when :llm_registry_availability_records
                 backfill_registry(row)

data/lib/legion/extensions/llm/ledger/data/migrations/011_add_identity_columns_to_registry_availability.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    alter_table(:llm_registry_availability_records) do
+      add_column :access_scope,            String, size: 20, null: false, default: 'global'
+      add_column :identity_principal_id,   Integer, null: true
+      add_column :identity_id,             Integer, null: true
+      add_column :identity_canonical_name, String, size: 255, null: true
+    end
+
+    alter_table(:llm_registry_availability_records) do
+      add_index :identity_principal_id
+      add_index :identity_id
+      add_index :access_scope
+    end
+  end
+
+  down do
+    alter_table(:llm_registry_availability_records) do
+      drop_index :identity_principal_id
+      drop_index :identity_id
+      drop_index :access_scope
+      drop_column :access_scope
+      drop_column :identity_principal_id
+      drop_column :identity_id
+      drop_column :identity_canonical_name
+    end
+  end
+end

data/lib/legion/extensions/llm/ledger/data/migrations/012_archive_legacy_tables.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    rename_table :llm_metering_records,  :z_archive_llm_metering_records
+    rename_table :llm_prompt_records,    :z_archive_llm_prompt_records
+    rename_table :llm_tool_records,      :z_archive_llm_tool_records
+  end
+
+  down do
+    rename_table :z_archive_llm_metering_records, :llm_metering_records
+    rename_table :z_archive_llm_prompt_records,   :llm_prompt_records
+    rename_table :z_archive_llm_tool_records,     :llm_tool_records
+  end
+end

data/lib/legion/extensions/llm/ledger/runners/registry_availability.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative '../helpers/caller_identity'
 require_relative '../helpers/json'
 require_relative '../helpers/persistence_logging'
 
@@ -13,10 +14,11 @@ module Legion
 
             def write_registry_availability_record(payload = nil, metadata = {}, **message)
               payload, metadata = normalize_runner_args(payload, metadata, message)
-              props = metadata[:properties] || {}
+              headers = Helpers::SubscriptionMessage.extract_headers(payload, metadata)
+              props   = metadata[:properties] || {}
 
               body = symbolize(payload)
-              record = build_registry_availability_record(body, props)
+              record = build_registry_availability_record(body, props, headers)
               Helpers::PersistenceLogging.insert_row(
                 ::Legion::Data.connection,
                 :llm_registry_availability_records,
@@ -38,41 +40,55 @@ module Legion
               Helpers::SubscriptionMessage.runner_args(payload, metadata, message)
             end
 
-            def build_registry_availability_record(body, props)
+            def build_registry_availability_record(body, props, headers)
               offering = body[:offering] || {}
               runtime = body[:runtime] || {}
               lane = body[:lane]
 
               {
-                event_id:          body[:event_id],
-                message_id:        props[:message_id],
-                correlation_id:    props[:correlation_id],
-                routing_key:       props[:routing_key],
-                event_type:        body[:event_type].to_s,
-                occurred_at:       body[:occurred_at],
-                offering_id:       offering[:offering_id],
-                provider_family:   offering[:provider_family]&.to_s,
-                provider_instance: offering[:provider_instance]&.to_s,
-                instance_id:       offering[:instance_id]&.to_s,
-                model_family:      offering[:model_family]&.to_s,
-                model_id:          offering[:model],
-                canonical_model:   offering[:canonical_model_alias],
-                provider_model:    offering[:provider_model],
-                usage_type:        offering[:usage_type]&.to_s,
-                transport:         offering[:transport]&.to_s,
-                lane_key:          lane_key(lane),
-                worker_id:         runtime[:worker_id] || runtime[:worker],
-                node_id:           runtime[:node_id] || runtime[:host_id],
-                offering_json:     json_dump(offering),
-                runtime_json:      json_dump(runtime),
-                capacity_json:     json_dump(body[:capacity] || {}),
-                health_json:       json_dump(body[:health] || {}),
-                lane_json:         json_dump(lane || {}),
-                metadata_json:     json_dump(body[:metadata] || {}),
-                inserted_at:       Time.now.utc
+                event_id:                body[:event_id],
+                message_id:              props[:message_id],
+                correlation_id:          props[:correlation_id],
+                routing_key:             props[:routing_key],
+                event_type:              body[:event_type].to_s,
+                occurred_at:             body[:occurred_at],
+                offering_id:             offering[:offering_id],
+                provider_family:         offering[:provider_family]&.to_s,
+                provider_instance:       offering[:provider_instance]&.to_s,
+                instance_id:             offering[:instance_id]&.to_s,
+                model_family:            offering[:model_family]&.to_s,
+                model_id:                offering[:model],
+                canonical_model:         offering[:canonical_model_alias],
+                provider_model:          offering[:provider_model],
+                usage_type:              offering[:usage_type]&.to_s,
+                transport:               offering[:transport]&.to_s,
+                lane_key:                lane_key(lane),
+                worker_id:               runtime[:worker_id] || runtime[:worker],
+                node_id:                 runtime[:node_id] || runtime[:host_id],
+                identity_canonical_name: extract_canonical_name(body, headers),
+                offering_json:           json_dump(offering),
+                runtime_json:            json_dump(runtime),
+                capacity_json:           json_dump(body[:capacity] || {}),
+                health_json:             json_dump(body[:health] || {}),
+                lane_json:               json_dump(lane || {}),
+                metadata_json:           json_dump(body[:metadata] || {}),
+                inserted_at:             Time.now.utc
               }
             end
 
+            # Extract identity_canonical_name from AMQP headers or body.
+            # No FK resolution — node/service identities may not be registered in
+            # identity tables, but the canonical name string is still valuable for
+            # tracking which identity is publishing which model availability.
+            def extract_canonical_name(body, headers)
+              raw = headers['x-legion-identity'] ||
+                    body.dig(:identity, :identity) ||
+                    body.dig(:identity, :canonical_name)
+              return nil unless raw && !raw.to_s.empty? # rubocop:disable Legion/Extension/RunnerReturnHash
+
+              raw.to_s
+            end
+
             def lane_key(lane)
               if lane.is_a?(String)
                 lane

data/lib/legion/extensions/llm/ledger/runners/tools.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'digest'
+require 'securerandom'
 require_relative '../helpers/caller_identity'
 require_relative '../helpers/json'
 require_relative '../helpers/persistence_logging'
@@ -8,6 +10,8 @@ module Legion
   module Extensions
     module Llm
       module Ledger
+        class ResponseNotReady < StandardError; end
+
         module Runners
           module Tools
             extend self
@@ -21,19 +25,25 @@ module Legion
               ctx  = body[:message_context] || {}
               tool = body[:tool_call]       || {}
 
-              expires_at = Helpers::Retention.resolve(
+              Helpers::Retention.resolve(
                 retention:    headers['x-legion-retention'],
                 contains_phi: headers['x-legion-contains-phi'] == 'true'
               )
 
-              record = build_tool_record(body, ctx, tool, props, headers, expires_at)
-              Helpers::PersistenceLogging.insert_row(
-                ::Legion::Data.connection,
-                :llm_tool_records,
-                record,
-                operation: 'write_tool_record'
-              )
-              { result: :ok }
+              db = ::Legion::Data.connection
+              write_result = [:ok]
+              db.transaction do
+                response                     = find_or_resolve_response(db, body, ctx, props, headers)
+                identity_attrs               = extract_identity_attrs(body, headers, db)
+                tool_call_row, new_tool_call = find_or_create_tool_call(db, response, body, ctx, tool, headers, identity_attrs)
+                if tool_call_row && !new_tool_call
+                  write_result[0] = :duplicate
+                elsif new_tool_call
+                  find_or_create_tool_call_attempt(db, tool_call_row, tool, body, props, headers, identity_attrs)
+                end
+              end
+
+              { result: write_result[0] }
             rescue Sequel::UniqueConstraintViolation => e
               log.warn("write_tool_record duplicate insert ignored: #{e.message}")
               { result: :duplicate }
@@ -43,6 +53,9 @@ module Legion
             rescue Helpers::DecryptionFailed => e
               handle_exception(e, level: :error, handled: true, operation: 'write_tool_record.decrypt')
               raise
+            rescue ResponseNotReady => e
+              log.warn("[ledger] write_tool_record: parent response not yet written, dead-lettering message (#{e.message})")
+              raise unrecoverable_message_error(e)
             rescue StandardError => e
               handle_exception(e, level: :error, handled: true, operation: 'write_tool_record')
               { result: :error, error: e.message }
@@ -54,46 +67,209 @@ module Legion
               Helpers::SubscriptionMessage.runner_args(payload, metadata, message)
             end
 
-            def build_tool_record(body, ctx, tool, props, headers, expires_at) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
-              src      = tool[:source] || {}
-              cls      = body[:classification] || {}
-              ts       = body[:timestamps] || {}
-              tracing    = body[:tracing] || {}
-              caller_raw = body[:caller] || {}
-              identity   = body[:identity] || {}
+            def unrecoverable_message_error(error)
+              if defined?(Legion::Extensions::Actors::UnrecoverableMessageError)
+                Legion::Extensions::Actors::UnrecoverableMessageError.new(error.message)
+              else
+                error
+              end
+            end
+
+            # Resolve the llm_message_inference_responses row this tool call belongs to.
+            # Returns nil if we cannot link at all.
+            def find_or_resolve_response(db, body, ctx, props, headers)
+              request_ref = ctx[:request_id] || body[:request_id] ||
+                            props[:correlation_id] || headers['x-legion-llm-request-id']
+              return nil unless request_ref # rubocop:disable Legion/Extension/RunnerReturnHash
+
+              request = db[:llm_message_inference_requests].where(request_ref: request_ref).first
+              return nil unless request # rubocop:disable Legion/Extension/RunnerReturnHash
+
+              db[:llm_message_inference_responses]
+                .where(message_inference_request_id: request[:id]).first
+            end
+
+            def find_or_create_tool_call(db, response, body, ctx, tool, headers, identity_attrs)
+              tool_uuid = derive_tool_call_uuid(body, ctx, tool, headers)
+              existing  = db[:llm_tool_calls].where(uuid: tool_uuid).first
+              return [existing, false] if existing # rubocop:disable Legion/Extension/RunnerReturnHash
+
+              response_id = resolve_response_id(db, response, body, ctx, headers, tool_uuid)
+              return [nil, false] unless response_id # rubocop:disable Legion/Extension/RunnerReturnHash
+
+              next_index = db[:llm_tool_calls]
+                           .where(message_inference_response_id: response_id)
+                           .max(:tool_call_index).to_i + 1
+
+              src    = tool[:source] || {}
+              status = tool[:status] || headers['x-legion-tool-status'] || 'success'
+              ts     = body[:timestamps] || {}
+
+              id = insert_with_savepoint(db, :llm_tool_calls, {
+                                           uuid:                          tool_uuid,
+                                           message_inference_response_id: response_id,
+                                           tool_call_index:               next_index,
+                                           provider_tool_call_ref:        tool[:id],
+                                           tool_name:                     tool[:name] || headers['x-legion-tool-name'],
+                                           tool_source_type:              src[:type] || headers['x-legion-tool-source-type'],
+                                           tool_source_server:            src[:server] || headers['x-legion-tool-source-server'],
+                                           status:                        status,
+                                           requested_at:                  ts[:tool_start] || tool[:started_at],
+                                           completed_at:                  ts[:tool_end] || tool[:finished_at],
+                                           **identity_attrs,
+                                           inserted_at:                   Time.now.utc
+                                         }, operation: 'write_tool_record.tool_call')
+              [db[:llm_tool_calls][id: id], true]
+            rescue Sequel::UniqueConstraintViolation => e
+              log.debug("[ledger] tool_call collision resolved uuid=#{tool_uuid} error=#{e.class}")
+              row = db[:llm_tool_calls].where(uuid: tool_uuid).first
+              raise(e) unless row
+
+              [row, false]
+            end
+
+            # Extract or fall back to find a response_id for linking the tool call.
+            def resolve_response_id(db, response, body, ctx, headers, tool_uuid)
+              return response[:id] if response # rubocop:disable Legion/Extension/RunnerReturnHash
+
+              fallback = fallback_response_for_conversation(db, body, ctx, headers)
+              return fallback[:id] if fallback # rubocop:disable Legion/Extension/RunnerReturnHash
+
+              raise ResponseNotReady, "no response row found for tool call uuid=#{tool_uuid}"
+            end
+
+            def fallback_response_for_conversation(db, body, ctx, headers)
+              conv_id = ctx[:conversation_id] || body[:conversation_id] ||
+                        headers['x-legion-llm-conversation-id']
+              return nil unless conv_id # rubocop:disable Legion/Extension/RunnerReturnHash
+
+              conv = db[:llm_conversations].where(uuid: stable_uuid(conv_id)).first ||
+                     db[:llm_conversations].where(uuid: conv_id).first
+              return nil unless conv # rubocop:disable Legion/Extension/RunnerReturnHash
+
+              db[:llm_message_inference_responses]
+                .join(:llm_message_inference_requests,
+                      id: :message_inference_request_id)
+                .where(Sequel[:llm_message_inference_requests][:conversation_id] => conv[:id])
+                .order(Sequel.desc(Sequel[:llm_message_inference_responses][:id]))
+                .select_all(:llm_message_inference_responses)
+                .first
+            end
+
+            def find_or_create_tool_call_attempt(db, tool_call_row, tool, body, props, headers, identity_attrs) # rubocop:disable Metrics/CyclomaticComplexity
+              return nil unless tool_call_row # rubocop:disable Legion/Extension/RunnerReturnHash
+
+              tool_call_id = tool_call_row[:id]
+              attempt_no   = db[:llm_tool_call_attempts]
+                             .where(tool_call_id: tool_call_id).max(:attempt_no).to_i + 1
+              attempt_uuid = derive_attempt_uuid(tool_call_row[:uuid], attempt_no)
+
+              existing = db[:llm_tool_call_attempts].where(uuid: attempt_uuid).first
+              return existing if existing # rubocop:disable Legion/Extension/RunnerReturnHash
+
+              status     = tool[:status] || headers['x-legion-tool-status'] || 'success'
+              error_info = tool[:error] || body[:error]
+              error_hash = error_info.is_a?(Hash) ? error_info : {}
+              ts         = body[:timestamps] || {}
+              runner_ref = body[:worker_id] || body[:runner_ref] || props[:app_id]
+
+              id = insert_with_savepoint(db, :llm_tool_call_attempts, {
+                                           uuid:           attempt_uuid,
+                                           tool_call_id:   tool_call_id,
+                                           attempt_no:     attempt_no,
+                                           runner_ref:     runner_ref,
+                                           status:         status,
+                                           error_category: error_hash[:category] || error_hash[:type],
+                                           error_code:     error_hash[:code],
+                                           error_message:  error_info.is_a?(String) ? error_info : error_hash[:message],
+                                           duration_ms:    tool[:duration_ms].to_i,
+                                           arguments_ref:  sha256_ref(tool[:arguments]),
+                                           result_ref:     sha256_ref(tool[:result] || body[:result]),
+                                           started_at:     ts[:tool_start] || tool[:started_at],
+                                           ended_at:       ts[:tool_end] || tool[:finished_at],
+                                           **identity_attrs,
+                                           inserted_at:    Time.now.utc
+                                         }, operation: 'write_tool_record.attempt')
+              db[:llm_tool_call_attempts][id: id]
+            rescue Sequel::UniqueConstraintViolation => e
+              log.debug("[ledger] tool_call_attempt collision resolved uuid=#{attempt_uuid} error=#{e.class}")
+              db[:llm_tool_call_attempts].where(uuid: attempt_uuid).first || raise(e)
+            end
+
+            def extract_identity_attrs(body, headers, db)
               caller_identity = Helpers::CallerIdentity.normalize(
-                caller_raw: caller_raw, identity: identity, headers: headers
+                caller_raw: body[:caller],
+                identity:   body[:identity],
+                headers:    headers
               )
-              agent = body[:agent] || {}
+              # raw_identity may carry a "type:value" prefix that OfficialRecordWriter
+              # knows how to parse; keep it intact for FK resolution.
+              raw_identity   = caller_identity[:identity]
+              canonical_name = raw_identity
+              # Strip "type:" prefix added by CallerIdentity for generic identities
+              if canonical_name&.include?(':') && !canonical_name&.include?('@')
+                _prefix, remainder = canonical_name.split(':', 2)
+                canonical_name = remainder if remainder && !remainder.empty?
+              end
+
+              refs = resolve_tool_identity(db, body, raw_identity)
 
               {
-                message_id:           props[:message_id] || body[:message_id],
-                correlation_id:       props[:correlation_id] || body[:correlation_id] || tracing[:correlation_id],
-                conversation_id:      ctx[:conversation_id] || body[:conversation_id] || headers['x-legion-llm-conversation-id'],
-                message_id_ctx:       ctx[:message_id],
-                parent_message_id:    ctx[:parent_message_id],
-                message_seq:          ctx[:message_seq],
-                request_id:           ctx[:request_id] || body[:request_id] || headers['x-legion-llm-request-id'],
-                exchange_id:          ctx[:exchange_id] || body[:exchange_id],
-                tool_call_id:         tool[:id],
-                tool_name:            tool[:name] || headers['x-legion-tool-name'],
-                tool_source_type:     src[:type] || headers['x-legion-tool-source-type'],
-                tool_source_server:   src[:server] || headers['x-legion-tool-source-server'],
-                tool_status:          tool[:status] || headers['x-legion-tool-status'],
-                tool_duration_ms:     tool[:duration_ms].to_i,
-                arguments_json:       Helpers::Json.dump(tool[:arguments] || {}),
-                result_json:          Helpers::Json.dump(tool[:result] || body[:result]),
-                error_json:           Helpers::Json.dump(tool[:error] || body[:error]),
-                caller_identity:      caller_identity[:identity],
-                agent_id:             agent[:id],
-                classification_level: cls[:level] || headers['x-legion-classification'],
-                contains_phi:         Helpers::Queries.phi_flag?(cls, headers),
-                retention_policy:     headers['x-legion-retention'] || 'default',
-                expires_at:           expires_at,
-                tool_start_at:        ts[:tool_start] || tool[:started_at],
-                tool_end_at:          ts[:tool_end] || tool[:finished_at],
-                inserted_at:          Time.now.utc
-              }
+                identity_canonical_name: canonical_name,
+                identity_principal_id:   refs[:principal_id],
+                identity_id:             refs[:identity_id]
+              }.compact
+            end
+
+            def resolve_tool_identity(db, body, raw_identity)
+              return {} unless raw_identity
+              return {} unless Writers::OfficialRecordWriter.identity_tables_available?(db)
+
+              # Merge the header-resolved identity string into the body so that
+              # OfficialRecordWriter.resolve_identity can find it via
+              # parsed_identity_descriptor even when identity came solely from
+              # AMQP headers and is absent from the payload body.
+              body_with_identity = raw_identity ? body.merge(caller_identity: raw_identity) : body
+              Writers::OfficialRecordWriter.resolve_identity(db, body_with_identity)
+            rescue StandardError => e
+              handle_exception(e, level: :warn, handled: true, operation: 'write_tool_record.identity_resolution')
+              {}
+            end
+
+            def derive_tool_call_uuid(body, ctx, tool, headers)
+              ref = tool[:id] ||
+                    ctx[:request_id] ||
+                    body[:request_id] ||
+                    headers['x-legion-llm-request-id'] ||
+                    ctx[:message_id] ||
+                    (body[:properties] || {})[:message_id]
+              stable_uuid("tool_call:#{ref || SecureRandom.uuid}")
+            end
+
+            def derive_attempt_uuid(tool_call_uuid, attempt_no)
+              stable_uuid("attempt:#{tool_call_uuid}:#{attempt_no}")
+            end
+
+            def sha256_ref(value)
+              return nil if value.nil? # rubocop:disable Legion/Extension/RunnerReturnHash
+
+              raw = value.is_a?(String) ? value : Helpers::Json.dump(value)
+              Digest::SHA256.hexdigest(raw)[0, 64]
+            end
+
+            def stable_uuid(value)
+              raw = value.to_s
+              return raw if raw.length <= 36 # rubocop:disable Legion/Extension/RunnerReturnHash
+
+              hex = Digest::SHA256.hexdigest(raw)[0, 32]
+              "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+            end
+
+            def insert_with_savepoint(db, table, attributes, operation:)
+              db.transaction(savepoint: true) do
+                Helpers::PersistenceLogging.insert_row(db, table, attributes,
+                                                       operation: operation, warn_on_unique: false)
+              end
             end
 
             include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&

data/lib/legion/extensions/llm/ledger/version.rb

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Ledger
-        VERSION = '0.3.3'
+        VERSION = '0.4.2'
       end
     end
   end

data/lib/legion/extensions/llm/ledger/writers/official_record_writer.rb

@@ -58,17 +58,18 @@ module Legion
               return existing if existing
 
               id = insert_with_savepoint(db, :llm_conversations, {
-                                           uuid:                 uuid,
-                                           title:                body[:title] || body[:conversation_title],
-                                           classification_level: classification_level(body),
-                                           contains_phi:         contains_phi?(body),
-                                           contains_pii:         contains_pii?(body),
-                                           retention_policy:     body[:retention_policy] || 'default',
-                                           expires_at:           body[:expires_at],
-                                           recorded_at:          recorded_at(body),
-                                           inserted_at:          Time.now.utc,
-                                           created_at:           Time.now.utc,
-                                           updated_at:           Time.now.utc
+                                           uuid:                    uuid,
+                                           title:                   body[:title] || body[:conversation_title],
+                                           classification_level:    classification_level(body),
+                                           contains_phi:            contains_phi?(body),
+                                           contains_pii:            contains_pii?(body),
+                                           retention_policy:        body[:retention_policy] || 'default',
+                                           expires_at:              body[:expires_at],
+                                           identity_canonical_name: identity_canonical_name(body),
+                                           recorded_at:             recorded_at(body),
+                                           inserted_at:             Time.now.utc,
+                                           created_at:              Time.now.utc,
+                                           updated_at:              Time.now.utc
                                          }, operation: 'official_record_writer.conversation')
               db[:llm_conversations][id: id]
             rescue Sequel::UniqueConstraintViolation => e
@@ -87,16 +88,19 @@ module Legion
               seq = body[:message_seq] ? integer(body[:message_seq]) : next_message_seq(db, conversation)
               begin
                 id = insert_with_savepoint(db, :llm_messages, {
-                                             uuid:            uuid,
-                                             conversation_id: conversation[:id],
-                                             seq:             seq,
-                                             role:            'user',
-                                             content_type:    'text',
-                                             content:         request_content(body),
-                                             input_tokens:    tokens(body)[:input_tokens],
-                                             output_tokens:   0,
-                                             created_at:      recorded_at(body),
-                                             inserted_at:     Time.now.utc
+                                             uuid:                    uuid,
+                                             conversation_id:         conversation[:id],
+                                             seq:                     seq,
+                                             role:                    'user',
+                                             content_type:            'text',
+                                             content:                 request_content(body),
+                                             input_tokens:            tokens(body)[:input_tokens],
+                                             output_tokens:           0,
+                                             identity_principal_id:   caller_identity_refs(db, body)[:principal_id],
+                                             identity_id:             caller_identity_refs(db, body)[:identity_id],
+                                             identity_canonical_name: identity_canonical_name(body),
+                                             created_at:              recorded_at(body),
+                                             inserted_at:             Time.now.utc
                                            }, operation: 'official_record_writer.user_message')
                 db[:llm_messages][id: id]
               rescue Sequel::UniqueConstraintViolation => e
@@ -114,28 +118,31 @@ module Legion
               operation = operation(body)
               caller_refs = caller_identity_refs(db, body)
               id = insert_with_savepoint(db, :llm_message_inference_requests, {
-                                           uuid:                  stable_uuid(request_id),
-                                           conversation_id:       conversation[:id],
-                                           latest_message_id:     latest_message&.dig(:id),
-                                           caller_principal_id:   caller_refs[:principal_id],
-                                           caller_identity_id:    caller_refs[:identity_id],
-                                           runtime_caller_type:   caller_type(body),
-                                           request_ref:           request_id,
-                                           correlation_ref:       correlation_id(body),
-                                           correlation_id:        correlation_id(body),
-                                           exchange_ref:          body[:exchange_id],
-                                           request_type:          operation,
-                                           operation:             operation,
-                                           idempotency_key:       body[:idempotency_key] || request_id,
-                                           status:                'responded',
-                                           context_message_count: Array(body.dig(:request, :messages) || body[:messages]).size,
-                                           request_capture_mode:  'full',
-                                           request_json:          json_dump(request_payload(body)),
-                                           classification_level:  classification_level(body),
-                                           cost_center:           billing(body)[:cost_center],
-                                           budget_key:            billing(body)[:budget_id] || billing(body)[:budget_key],
-                                           requested_at:          recorded_at(body),
-                                           inserted_at:           Time.now.utc
+                                           uuid:                    stable_uuid(request_id),
+                                           conversation_id:         conversation[:id],
+                                           latest_message_id:       latest_message&.dig(:id),
+                                           caller_principal_id:     caller_refs[:principal_id],
+                                           caller_identity_id:      caller_refs[:identity_id],
+                                           identity_canonical_name: identity_canonical_name(body),
+                                           runtime_caller_type:     caller_type(body),
+                                           runtime_caller_class:    runtime_caller_class(body),
+                                           runtime_caller_client:   runtime_caller_client(body),
+                                           request_ref:             request_id,
+                                           correlation_ref:         correlation_id(body),
+                                           correlation_id:          correlation_id(body),
+                                           exchange_ref:            body[:exchange_id],
+                                           request_type:            operation,
+                                           operation:               operation,
+                                           idempotency_key:         body[:idempotency_key] || request_id,
+                                           status:                  'responded',
+                                           context_message_count:   Array(body.dig(:request, :messages) || body[:messages]).size,
+                                           request_capture_mode:    'full',
+                                           request_json:            json_dump(request_payload(body)),
+                                           classification_level:    classification_level(body),
+                                           cost_center:             billing(body)[:cost_center],
+                                           budget_key:              billing(body)[:budget_id] || billing(body)[:budget_key],
+                                           requested_at:            recorded_at(body),
+                                           inserted_at:             Time.now.utc
                                          }, operation: 'official_record_writer.inference_request')
               db[:llm_message_inference_requests][id: id]
             rescue Sequel::UniqueConstraintViolation => e
@@ -165,6 +172,9 @@ module Legion
                                              content:                      response_content(body),
                                              input_tokens:                 0,
                                              output_tokens:                tokens(body)[:output_tokens],
+                                             identity_principal_id:        caller_identity_refs(db, body)[:principal_id],
+                                             identity_id:                  caller_identity_refs(db, body)[:identity_id],
+                                             identity_canonical_name:      identity_canonical_name(body),
                                              created_at:                   recorded_at(body),
                                              inserted_at:                  Time.now.utc
                                            }, operation: 'official_record_writer.response_message')
@@ -202,6 +212,9 @@ module Legion
                                            response_json:                json_dump(visible_response(body)),
                                            response_thinking_json:       json_dump(thinking_response(body)),
                                            dispatch_path:                body[:dispatch_path] || body[:tier],
+                                           identity_principal_id:        caller_identity_refs(db, body)[:principal_id],
+                                           identity_id:                  caller_identity_refs(db, body)[:identity_id],
+                                           identity_canonical_name:      identity_canonical_name(body),
                                            responded_at:                 recorded_at(body),
                                            inserted_at:                  Time.now.utc
                                          }, operation: 'official_record_writer.inference_response')
@@ -224,6 +237,7 @@ module Legion
               update_if_missing(updates, existing, :provider_instance, provider_instance(body))
               update_if_missing(updates, existing, :finish_reason, finish_reason(body))
               update_if_missing(updates, existing, :dispatch_path, body[:dispatch_path] || body[:tier])
+              update_if_missing(updates, existing, :identity_canonical_name, identity_canonical_name(body))
 
               response_json = json_dump(visible_response(body))
               update_if_placeholder(updates, existing, :response_json, response_json)
@@ -268,6 +282,9 @@ module Legion
                                            currency:                      body[:currency] || 'USD',
                                            cost_center:                   billing(body)[:cost_center],
                                            budget_key:                    billing(body)[:budget_id] || billing(body)[:budget_key],
+                                           identity_principal_id:         caller_identity_refs(db, body)[:principal_id],
+                                           identity_id:                   caller_identity_refs(db, body)[:identity_id],
+                                           identity_canonical_name:       identity_canonical_name(body),
                                            recorded_at:                   recorded_at(body),
                                            inserted_at:                   Time.now.utc
                                          }, operation: 'official_record_writer.inference_metric')
@@ -310,6 +327,9 @@ module Legion
               updates[:caller_identity_id] = caller_refs[:identity_id] if existing[:caller_identity_id].nil? && caller_refs[:identity_id]
               updates[:caller_principal_id] = caller_refs[:principal_id] if existing[:caller_principal_id].nil? && caller_refs[:principal_id]
               updates[:runtime_caller_type] = caller_type(body) if existing[:runtime_caller_type].nil? && caller_type(body)
+              update_if_missing(updates, existing, :runtime_caller_class, runtime_caller_class(body))
+              update_if_missing(updates, existing, :runtime_caller_client, runtime_caller_client(body))
+              update_if_missing(updates, existing, :identity_canonical_name, identity_canonical_name(body))
 
               request_json = json_dump(request_payload(body))
               updates[:request_json] = request_json if existing[:request_json].to_s == '{}' && request_json != '{}'
@@ -342,6 +362,16 @@ module Legion
               parsed_identity_descriptor(body)[:kind]
             end
 
+            def runtime_caller_class(body)
+              body.dig(:caller, :class) || body.dig(:caller, :caller_class) ||
+                body.dig(:caller, :source_class) || body[:runtime_caller_class]
+            end
+
+            def runtime_caller_client(body)
+              body.dig(:caller, :client) || body.dig(:caller, :user_agent) ||
+                body[:runtime_caller_client]
+            end
+
             def caller_identity_refs(db, body)
               body[:__ledger_caller_identity_refs] ||= begin
                 explicit_identity_id = integer_or_nil(body[:caller_identity_id] || body.dig(:caller, :requested_by, :id))
@@ -691,6 +721,10 @@ module Legion
               end
             end
 
+            def identity_canonical_name(body)
+              parsed_identity_descriptor(body)[:canonical_name]
+            end
+
             def present?(value)
               !value.nil? && !(value.respond_to?(:empty?) && value.empty?)
             end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-ledger
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.2
 platform: ruby
 authors:
 - Esity
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.8.0
+        version: 1.8.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.8.0
+        version: 1.8.7
 - !ruby/object:Gem::Dependency
   name: legion-json
   requirement: !ruby/object:Gem::Requirement
@@ -207,6 +207,8 @@ files:
 - lib/legion/extensions/llm/ledger/data/migrations/008_relax_message_id_not_null.rb
 - lib/legion/extensions/llm/ledger/data/migrations/009_add_caller_to_metering.rb
 - lib/legion/extensions/llm/ledger/data/migrations/010_add_response_thinking_json_to_prompt_records.rb
+- lib/legion/extensions/llm/ledger/data/migrations/011_add_identity_columns_to_registry_availability.rb
+- lib/legion/extensions/llm/ledger/data/migrations/012_archive_legacy_tables.rb
 - lib/legion/extensions/llm/ledger/helpers/caller_identity.rb
 - lib/legion/extensions/llm/ledger/helpers/decryption.rb
 - lib/legion/extensions/llm/ledger/helpers/json.rb