lex-llm-ledger 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70deb6cfb3814da49ebbc893a2025e06ddcf96ee7789a65f794fa66910502f41
-  data.tar.gz: e0837642064bf0c1ee6bf480704d297f961144f5f6cfb0814b88d8de438bf0f6
+  metadata.gz: 7b0e51e42bfec73669b2065b292a856ba029708010d10fc038d086a3442207e5
+  data.tar.gz: dbfbc4bf7b969362ff0363096fac13d33e8484080eddbccb09051fe3b794c0ff
 SHA512:
-  metadata.gz: '024169e420f778950b01bd074b03b1e63ccc642cb6c0148a14046dc91a74426c8a4d202a70fb33b6a669fbe3248fba62940e72a3a63ba1d776cef0044e0b9e36'
-  data.tar.gz: 207e66a936b63bf8c52437d2dc1d92931afdcb12caea03976b4e293bf8e67d43f963e62e9ba336c1e80789b3d60ad960b56eb6b85081f3146509f84c760aaf6f
+  metadata.gz: 18e7a33c0c64c8cb6ebc6ef09c21b174ac2a73ef0643947029e2898ec59bf523e5e0d8c157672908755147b136c98b87117be1f7d1e701d6542862fd9b58e4b3
+  data.tar.gz: f9e869ab4703524b7b054d1c1a44c8ab4d2fd1b53a770aa48f471f69c70f124ad4e4b4a90ecd1ca5399e43817394cdbc05248b00108cdca4ee45b494b8c5d4c9

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.7.0] - 2026-06-09
+
+### Fixed
+- **ASYNC-RACE-01**: Resolved race condition between metering and prompt audit messages causing duplicate response rows and stale `"{}"`/`"null"` JSON placeholders. Added response UUID fallback to `message_inference_request_id` lookup to enrich metering-created shells instead of creating duplicates.
+- **RECONCILIATION-01**: Fixed `UniqueConstraintViolation` in `link_orphaned_tool_calls` by recalculating `tool_call_index` based on existing max index before linking, preventing index collisions.
+- **ENRICHMENT-01**: Implemented strict upsert guards (`upsert_guard?`) to prevent overwriting valid data with `nil`, `''`, or `'{}'`. Centralized validation across `update_if_missing` and `update_if_placeholder`.
+- **PAYLOAD-01**: Updated `request_payload`, `visible_response`, and `thinking_response` to return `nil` instead of `{}` when content is missing. Insert paths now write `nil` to JSON columns, preventing `"{}"` or `"null"` string artifacts.
+- **ENRICHMENT-02**: Expanded `update_if_placeholder` to recognize both `'{}'` and `'null'` as stale markers for retroactive cleanup. Guarded `response_content(body)` against `nil` returns.
+
 ## [0.6.0] - 2026-05-31
 
 ### Added

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

@@ -49,7 +49,7 @@ module Legion
               Helpers::SubscriptionMessage.runner_args(payload, metadata, message)
             end
 
-            def build_escalation_record(db, body, props, headers) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+            def build_escalation_record(db, body, props, headers)
               history = Array(body[:history])
               identity = Helpers::CallerIdentity.normalize(
                 caller_raw: body[:caller], identity: body[:identity], headers: headers

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

@@ -28,8 +28,16 @@ module Legion
                 response = find_response_for_tool_call(db, tool_call)
                 next unless response
 
+                # Recalculate tool_call_index to avoid unique constraint collisions.
+                # Orphaned tool calls were inserted with index 0 (no response known),
+                # but the response may already have tool calls at those indices.
+                next_index = db[:llm_tool_calls]
+                             .where(message_inference_response_id: response[:id])
+                             .max(:tool_call_index).to_i + 1
+
                 db[:llm_tool_calls].where(id: tool_call[:id]).update(
-                  message_inference_response_id: response[:id]
+                  message_inference_response_id: response[:id],
+                  tool_call_index:               next_index
                 )
                 linked += 1
               end

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

@@ -101,7 +101,7 @@ module Legion
               conv&.[](:id)
             end
 
-            def find_or_create_tool_call(db, response, body, ctx, tool, headers, identity_attrs, conversation_id) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+            def find_or_create_tool_call(db, response, body, ctx, tool, headers, identity_attrs, conversation_id)
               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
@@ -152,7 +152,7 @@ module Legion
               [row, false]
             end
 
-            def find_or_create_tool_call_attempt(db, tool_call_row, tool, body, props, headers, identity_attrs) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize
+            def find_or_create_tool_call_attempt(db, tool_call_row, tool, body, props, headers, identity_attrs)
               return nil unless tool_call_row # rubocop:disable Legion/Extension/RunnerReturnHash
 
               tool_call_id = tool_call_row[:id]

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Ledger
-        VERSION = '0.6.0'
+        VERSION = '0.7.0'
       end
     end
   end

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

@@ -112,7 +112,7 @@ module Legion
               end
             end
 
-            def find_or_create_request(db, conversation, latest_message, body) # rubocop:disable Metrics/AbcSize
+            def find_or_create_request(db, conversation, latest_message, body)
               request_id = request_ref(body)
               existing = db[:llm_message_inference_requests].where(request_ref: request_id).first
               return enrich_request!(db, existing, body, latest_message) if existing
@@ -140,7 +140,10 @@ module Legion
                                            status:                  'responded',
                                            context_message_count:   Array(body.dig(:request, :messages) || body[:messages]).size,
                                            request_capture_mode:    'full',
-                                           request_json:            phi_protect(json_dump(request_payload(body)), contains_phi?(body)),
+                                           request_json:            if request_payload(body)
+                                                                      phi_protect(json_dump(request_payload(body)),
+                                                                                  contains_phi?(body))
+                                                                    end,
                                            classification_level:    classification_level(body),
                                            cost_center:             billing(body)[:cost_center],
                                            budget_key:              billing(body)[:budget_id] || billing(body)[:budget_key],
@@ -194,15 +197,29 @@ module Legion
               end
             end
 
-            def find_or_create_response(db, request, response_message, body) # rubocop:disable Metrics/AbcSize
+            def find_or_create_response(db, request, response_message, body)
               response_uuid = stable_uuid(reference(body, :provider_response_ref) || "response:#{request_ref(body)}:#{body[:provider] || 'unknown'}")
               existing = db[:llm_message_inference_responses].where(uuid: response_uuid).first
+
+              # Fallback: if we couldn't find a response by UUID, check if a response
+              # already exists for this request (e.g., metering arrived first and created
+              # a response with a different UUID). Enrich it instead of creating a duplicate.
+              unless existing
+                existing = db[:llm_message_inference_responses]
+                           .where(message_inference_request_id: request[:id])
+                           .first
+                log.debug("[ledger] response fallback: found existing response id=#{existing[:id]} for request_id=#{request[:id]}") if existing
+              end
+
               if existing
                 enrich_response!(db, existing, response_message, body)
                 return existing
               end
 
+              vis_resp = visible_response(body)
+              think_resp = thinking_response(body)
               phi = contains_phi?(body)
+
               id = insert_with_savepoint(db, :llm_message_inference_responses, {
                                            uuid:                         response_uuid,
                                            message_inference_request_id: request[:id],
@@ -218,8 +235,8 @@ module Legion
                                            latency_ms:                   integer(body[:latency_ms]),
                                            wall_clock_ms:                integer(body[:wall_clock_ms]),
                                            response_capture_mode:        'full',
-                                           response_json:                phi_protect(json_dump(visible_response(body)), phi),
-                                           response_thinking_json:       phi_protect(json_dump(thinking_response(body)), phi),
+                                           response_json:                vis_resp ? phi_protect(json_dump(vis_resp), phi) : nil,
+                                           response_thinking_json:       think_resp ? phi_protect(json_dump(think_resp), phi) : nil,
                                            dispatch_path:                body[:dispatch_path] || body[:tier],
                                            error_category:               body[:error_category] || body.dig(:error, :category),
                                            error_code:                   body[:error_code] || body.dig(:error, :code),
@@ -254,11 +271,21 @@ module Legion
               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)
+              vis = visible_response(body)
+              if vis
+                response_json = json_dump(vis)
+                update_if_placeholder(updates, existing, :response_json, response_json)
+              elsif existing[:response_json].nil?
+                # Nothing to add, but also don't overwrite existing data with nil
+              end
 
-              thinking_json = json_dump(thinking_response(body))
-              update_if_placeholder(updates, existing, :response_thinking_json, thinking_json)
+              think = thinking_response(body)
+              if think
+                thinking_json = json_dump(think)
+                update_if_placeholder(updates, existing, :response_thinking_json, thinking_json)
+              elsif existing[:response_thinking_json].nil?
+                # Nothing to add
+              end
 
               return if updates.empty?
 
@@ -266,12 +293,27 @@ module Legion
               log.info("[ledger] enriched response id=#{existing[:id]} fields=#{updates.keys.join(',')}")
             end
 
+            # Core guard: never upsert a value that is nil, empty string, or empty JSON object.
+            # This prevents a leaner message (e.g., metering) from overwriting valid data
+            # written by a richer message (e.g., prompt audit).
+            def upsert_guard?(value)
+              return false if value.nil?
+              return false if value.is_a?(String) && value.strip.empty?
+              return false if value.to_s == '{}'
+
+              true
+            end
+
             def update_if_missing(updates, existing, key, value)
-              updates[key] = value if existing[key].nil? && present?(value)
+              updates[key] = value if existing[key].nil? && upsert_guard?(value)
             end
 
             def update_if_placeholder(updates, existing, key, value)
-              updates[key] = value if existing[key].to_s == '{}' && value != '{}'
+              return unless upsert_guard?(value)
+
+              existing_val = existing[key]
+              is_placeholder = ['{}', 'null'].include?(existing_val.to_s)
+              updates[key] = value if is_placeholder
             end
 
             def find_or_create_metric(db, request, response, body)
@@ -339,15 +381,19 @@ module Legion
               updates = {}
               update_if_missing(updates, existing, :latest_message_id, latest_message&.dig(:id))
               caller_refs = caller_identity_refs(db, body)
-              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, :caller_identity_id, caller_refs[:identity_id])
+              update_if_missing(updates, existing, :caller_principal_id, caller_refs[:principal_id])
+              update_if_missing(updates, existing, :runtime_caller_type, 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 != '{}'
+              request_json = request_payload(body) ? json_dump(request_payload(body)) : nil
+              if request_json
+                update_if_placeholder(updates, existing, :request_json, request_json)
+              elsif existing[:request_json].nil?
+                # Nothing to add
+              end
 
               msg_count = Array(body.dig(:request, :messages) || body[:messages]).size
               updates[:context_message_count] = msg_count if existing[:context_message_count].to_i.zero? && msg_count.positive?
@@ -574,7 +620,7 @@ module Legion
             end
 
             def resolve_parent_request_id(db, body)
-              parent_ref = body[:parent_request_id] || body.dig(:context, :parent_request_id)
+              parent_ref = body[:parent_request_id] || body.dig(:context, :parent_request_id) || body.dig(:caller, :parent_request_ref)
               return nil unless present?(parent_ref)
 
               if parent_ref.is_a?(Integer)
@@ -630,7 +676,7 @@ module Legion
             end
 
             def request_payload(body)
-              body[:request] || body[:messages] || {}
+              body[:request] || body[:messages]
             end
 
             def request_content(body)
@@ -641,7 +687,9 @@ module Legion
             end
 
             def visible_response(body)
-              response = body[:response] || body[:response_content] || body[:content] || {}
+              response = body[:response] || body[:response_content] || body[:content]
+              return nil if response.nil? || (response.is_a?(Hash) && response.empty?)
+
               if response.is_a?(String)
                 clean, _thinking = extract_inline_thinking(response)
                 return { content: clean }
@@ -661,10 +709,10 @@ module Legion
               end
 
               content_str = body[:response_content] || body[:response] || body[:content]
-              return {} unless content_str.is_a?(String)
+              return nil unless content_str.is_a?(String)
 
               _clean, extracted = extract_inline_thinking(content_str)
-              extracted ? { content: extracted } : {}
+              extracted ? { content: extracted } : nil
             end
 
             def extract_inline_thinking(text)
@@ -677,7 +725,10 @@ module Legion
             end
 
             def response_content(body)
-              stringify_content(visible_response(body)[:content] || visible_response(body).dig(:message, :content))
+              vis = visible_response(body)
+              return nil unless vis
+
+              stringify_content(vis[:content] || vis.dig(:message, :content))
             end
 
             def finish_reason(body)
@@ -788,9 +839,7 @@ module Legion
             def resolve_context_tokens(body)
               raw = body[:tokens] || body[:audit] || body
               val = raw[:input_tokens] || raw[:input] || raw[:context_tokens] || raw[:prompt_tokens]
-              return nil unless present?(val)
-
-              val.to_i
+              present?(val) ? val.to_i : 0
             end
           end
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-ledger
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Esity