claude_memory 0.11.0 → 0.12.0

data/lib/claude_memory/otel/settings_writer.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require_relative "../core/result"
+
+module ClaudeMemory
+  module OTel
+    # Idempotent reader/writer for the OTel-related env block in
+    # .claude/settings.json. Each method returns Core::Result so the CLI
+    # can render uniform success/failure output.
+    #
+    # Settings file shape (Claude Code reads this on session start):
+    #
+    #   {
+    #     "env": {
+    #       "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
+    #       "OTEL_EXPORTER_OTLP_PROTOCOL": "http/json",
+    #       "OTEL_EXPORTER_OTLP_ENDPOINT": "http://127.0.0.1:3377",
+    #       "OTEL_METRICS_EXPORTER": "otlp",
+    #       "OTEL_LOGS_EXPORTER": "otlp"
+    #     }
+    #   }
+    #
+    # Traces and prompt-content opt-ins write additional keys; #disable!
+    # clears every key this module owns and leaves the rest of the file
+    # untouched.
+    class SettingsWriter
+      DEFAULT_PORT = 3377
+
+      OWNED_KEYS = %w[
+        CLAUDE_CODE_ENABLE_TELEMETRY
+        OTEL_EXPORTER_OTLP_PROTOCOL
+        OTEL_EXPORTER_OTLP_ENDPOINT
+        OTEL_METRICS_EXPORTER
+        OTEL_LOGS_EXPORTER
+        OTEL_TRACES_EXPORTER
+        OTEL_LOG_USER_PROMPTS
+      ].freeze
+
+      def initialize(claude_dir, port: DEFAULT_PORT)
+        @claude_dir = claude_dir
+        @settings_path = File.join(@claude_dir, "settings.json")
+        @port = port
+      end
+
+      attr_reader :settings_path
+
+      def enable!
+        update_env do |env|
+          env["CLAUDE_CODE_ENABLE_TELEMETRY"] = "1"
+          env["OTEL_EXPORTER_OTLP_PROTOCOL"] = "http/json"
+          env["OTEL_EXPORTER_OTLP_ENDPOINT"] = "http://127.0.0.1:#{@port}"
+          env["OTEL_METRICS_EXPORTER"] = "otlp"
+          env["OTEL_LOGS_EXPORTER"] = "otlp"
+        end
+      end
+
+      def disable!
+        update_env do |env|
+          OWNED_KEYS.each { |key| env.delete(key) }
+        end
+      end
+
+      def enable_traces!
+        update_env do |env|
+          env["OTEL_TRACES_EXPORTER"] = "otlp"
+        end
+      end
+
+      def disable_traces!
+        update_env do |env|
+          env["OTEL_TRACES_EXPORTER"] = "none"
+        end
+      end
+
+      def capture_prompts!
+        update_env do |env|
+          env["OTEL_LOG_USER_PROMPTS"] = "1"
+        end
+      end
+
+      def disable_capture_prompts!
+        update_env do |env|
+          env.delete("OTEL_LOG_USER_PROMPTS")
+        end
+      end
+
+      # Read-only accessor — returns the current OTel-related env values
+      # so the CLI's --status subcommand and the dashboard header can
+      # render what's configured without re-implementing JSON parsing.
+      def current_env
+        load_settings.fetch("env", {}).slice(*OWNED_KEYS)
+      end
+
+      private
+
+      def update_env
+        FileUtils.mkdir_p(@claude_dir)
+        settings = load_settings
+        settings["env"] ||= {}
+        yield settings["env"]
+        write_settings(settings)
+        Core::Result.success(settings["env"].slice(*OWNED_KEYS))
+      rescue Errno::EACCES, Errno::ENOSPC, JSON::ParserError => e
+        Core::Result.failure("settings.json write failed: #{e.message}")
+      end
+
+      def load_settings
+        return {} unless File.exist?(@settings_path)
+        raw = File.read(@settings_path)
+        return {} if raw.strip.empty?
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Hash) ? parsed : {}
+      end
+
+      def write_settings(settings)
+        File.write(@settings_path, JSON.pretty_generate(settings) + "\n")
+      end
+    end
+  end
+end

data/lib/claude_memory/otel/status.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module OTel
+    # Single source of truth for "what does telemetry look like right now?"
+    # Used by both the `claude-memory otel --status` CLI and the dashboard's
+    # Telemetry header. Pure read query — no writes.
+    class Status
+      def initialize(store, configuration: nil, settings_writer: nil)
+        @store = store
+        @configuration = configuration || ClaudeMemory::Configuration.new
+        @settings_writer = settings_writer
+      end
+
+      # @return [Hash]
+      def snapshot
+        {
+          metric_count: count_safely(:otel_metrics),
+          event_count: count_safely(:otel_events),
+          trace_count: count_safely(:otel_traces),
+          last_metric_at: last_timestamp(:otel_metrics, :recorded_at),
+          last_event_at: last_timestamp(:otel_events, :occurred_at),
+          last_trace_at: last_timestamp(:otel_traces, :recorded_at),
+          traces_enabled: @configuration.otel_traces_enabled?,
+          configured_env: configured_env,
+          endpoint: configured_endpoint
+        }
+      end
+
+      private
+
+      def count_safely(table)
+        return 0 unless @store&.db&.table_exists?(table)
+        @store.db[table].count
+      rescue Sequel::DatabaseError
+        0
+      end
+
+      def last_timestamp(table, column)
+        return nil unless @store&.db&.table_exists?(table)
+        @store.db[table].max(column)
+      rescue Sequel::DatabaseError
+        nil
+      end
+
+      def configured_env
+        return {} unless @settings_writer
+        @settings_writer.current_env
+      rescue Errno::ENOENT, JSON::ParserError
+        {}
+      end
+
+      def configured_endpoint
+        configured_env["OTEL_EXPORTER_OTLP_ENDPOINT"]
+      end
+    end
+  end
+end

data/lib/claude_memory/recall/staleness_annotator.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "time"
+
+module ClaudeMemory
+  class Recall
+    # Pure function. Given a fact hash, returns a human-readable staleness
+    # marker for single-value facts that are old and unconfirmed, or nil.
+    #
+    # Single-value predicates (uses_database / deployment_platform /
+    # auth_method) are exclusive claims — "the project uses X." Claude
+    # follows them authoritatively, so a *stale* single-value fact is the
+    # most dangerous kind of memory: the 0.12 harm benchmark caught Claude
+    # emitting `git push heroku` from a stale deployment_platform fact with
+    # no hedge (docs/1_0_punchlist.md #3 / #15). This annotator surfaces the
+    # uncertainty inline at context-injection time so Claude can hedge or
+    # verify instead of blindly following.
+    #
+    # Multi-value predicates (convention, decision, uses_framework, …) are
+    # NOT annotated: they accumulate, so one stale entry doesn't carry the
+    # same authoritative weight, and flagging them would just add noise.
+    #
+    # A fact is stale-for-injection when BOTH hold:
+    #   - the claim is old: valid_from (or created_at fallback) is older
+    #     than threshold_days — a freshly recorded fact is never stale even
+    #     if it describes something historical, and
+    #   - it hasn't been confirmed recently: last_recalled_at is null or
+    #     older than threshold_days — a fact that's been recalled lately is
+    #     implicitly re-validated by use.
+    #
+    # No side effects; safe to call per-fact in the context-injection loop.
+    module StalenessAnnotator
+      module_function
+
+      DEFAULT_THRESHOLD_DAYS = 180
+
+      # @param fact [Hash] needs :predicate; reads :valid_from, :created_at,
+      #   :last_recalled_at when present
+      # @param now [Time]
+      # @param threshold_days [Integer]
+      # @return [String, nil] marker text, or nil when not stale / not guarded
+      def marker_for(fact, now: Time.now.utc, threshold_days: DEFAULT_THRESHOLD_DAYS)
+        return nil unless Resolve::PredicatePolicy.single?(fact[:predicate].to_s)
+
+        established = parse_time(fact[:valid_from]) || parse_time(fact[:created_at])
+        return nil unless established
+
+        cutoff = now - threshold_days * 86_400
+        return nil unless established < cutoff
+
+        last_seen = parse_time(fact[:last_recalled_at])
+        return nil if last_seen && last_seen >= cutoff
+
+        months = ((now - established) / (30 * 86_400)).round
+        "⚠ stale: recorded #{established.strftime("%Y-%m-%d")}, " \
+          "not confirmed in ~#{months}mo — verify before relying"
+      end
+
+      # @return [Boolean] true when marker_for would return a marker
+      def stale?(fact, now: Time.now.utc, threshold_days: DEFAULT_THRESHOLD_DAYS)
+        !marker_for(fact, now: now, threshold_days: threshold_days).nil?
+      end
+
+      def parse_time(value)
+        return nil if value.nil?
+        return value.utc if value.is_a?(Time)
+        Time.parse(value.to_s).utc
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/claude_memory/resolve/predicate_policy.rb

@@ -62,9 +62,25 @@ module ClaudeMemory
 
       # Return the canonical form of a predicate name, applying known
       # synonym mappings. Leaves unmapped predicates unchanged.
+      #
+      # Emits a deprecation warning via `ClaudeMemory::Deprecations` when
+      # an actual synonym is hit, since the predicate vocabulary is part
+      # of the public API contract (`docs/api_stability.md` §6) and
+      # silent canonicalization makes the legacy form indistinguishable
+      # from the current one. Removal of the SYNONYMS entries is
+      # scheduled for `1.0.0`.
       def self.canonicalize(predicate)
         return predicate if predicate.nil?
-        SYNONYMS.fetch(predicate, predicate)
+        canonical = SYNONYMS.fetch(predicate, predicate)
+        if canonical != predicate
+          ClaudeMemory::Deprecations.warn(
+            name: "predicate=#{predicate}",
+            replacement: "predicate=#{canonical}",
+            removed_in: "1.0.0",
+            message: "PredicatePolicy::SYNONYMS will be removed; emit canonical predicate names directly."
+          )
+        end
+        canonical
       end
 
       # Return the snapshot section a predicate belongs to.

data/lib/claude_memory/resolve/resolver.rb

@@ -120,15 +120,36 @@ module ClaudeMemory
 
         # No exact match: for multi-value predicates the new object is
         # genuinely a new coexisting value. For single-value, either the
-        # user signaled supersession ("now we use X instead") or the new
-        # claim contradicts the current one.
+        # user signaled supersession ("now we use X instead"), the new
+        # claim is example text (silently discarded), or the new claim
+        # contradicts the current one (conflict).
         if PredicatePolicy.single?(fact_data[:predicate])
-          supersession_signal?(fact_data) ? :supersede : :conflict
+          return :supersede if supersession_signal?(fact_data)
+          return :discard if example_text_quote?(fact_data)
+          :conflict
         else
           :insert
         end
       end
 
+      # Single-cardinality stack predicates extracted from CLAUDE.md-style
+      # example text ('e.g., "this app uses PostgreSQL"') used to create a
+      # disputed fact + conflict row every ingest cycle. The
+      # ReferenceMaterialDetector handles this for the MCP
+      # `store_extraction` path; the resolver-side guard catches the same
+      # pattern when Layer-1 NullDistiller produces a stack fact from
+      # documentation text. Added 2026-05-21 audit Phase 3.6.
+      EXAMPLE_QUOTE_PATTERNS = [
+        /\b(?:e\.?g\.?|i\.?e\.?|for example|for instance|such as)[,:]?\s/i,
+        /\(\s*(?:e\.?g\.?|i\.?e\.?)[,.]/i
+      ].freeze
+
+      def example_text_quote?(fact_data)
+        quote = fact_data[:quote].to_s
+        return false if quote.empty?
+        EXAMPLE_QUOTE_PATTERNS.any? { |re| quote.match?(re) }
+      end
+
       def apply_resolution(resolution, fact_data, subject_id, entity_ids, content_item_id, occurred_at, existing_facts, project_path:, scope:)
         case resolution
         when :reinforce
@@ -136,6 +157,12 @@ module ClaudeMemory
         when :conflict
           apply_conflict(existing_facts, fact_data, subject_id, content_item_id, occurred_at,
             project_path: project_path, scope: scope)
+        when :discard
+          # Silently drop the fact — its quote looked like documentation
+          # example text against a single-cardinality predicate that
+          # already has a confirmed value. Returning zero across the
+          # board keeps the resolver-result accounting consistent.
+          {created: 0, superseded: 0, conflicts: 0, provenance: 0}
         else
           apply_insert(fact_data, subject_id, entity_ids, content_item_id, occurred_at, existing_facts, resolution,
             project_path: project_path, scope: scope)

data/lib/claude_memory/shortcuts.rb

@@ -1,40 +1,53 @@
 # frozen_string_literal: true
 
 module ClaudeMemory
+  # Predicate-based shortcuts for the three common "give me X" queries that
+  # MCP clients (and humans via CLI) expect to be trivially fast and
+  # noise-free.
+  #
+  # Prior implementation did FTS text search ("convention style format
+  # pattern prefer") with a hardcoded global-only scope on `conventions`.
+  # That produced cross-predicate matches (uses_database rows leaking into
+  # the decisions shortcut) and silently dropped every project convention
+  # on the floor. Switching to predicate-based filtering at the store level
+  # eliminates both classes of bug; the cost is we no longer rank by FTS
+  # relevance, but for "list the project's conventions" that's the correct
+  # trade.
   class Shortcuts
-    QUERIES = {
+    SHORTCUTS = {
       decisions: {
-        query: "decision constraint rule requirement",
-        scope: "all",
+        predicates: %w[decision],
         limit: 10
       },
       architecture: {
-        query: "uses framework implements architecture pattern",
-        scope: "all",
+        # Includes the stack-shaping predicates so an agent asking
+        # "what's the architecture?" gets both narrative architecture
+        # facts AND the constraints (uses_database, uses_framework, ...).
+        # Without these the shortcut returns only freeform architecture
+        # facts and the constraints section stays invisible.
+        predicates: %w[architecture uses_database uses_framework uses_language deployment_platform auth_method],
         limit: 10
       },
       conventions: {
-        query: "convention style format pattern prefer",
-        scope: "global",
+        predicates: %w[convention],
         limit: 20
       },
       project_config: {
-        query: "uses requires depends_on configuration",
-        scope: "project",
+        predicates: %w[uses_database uses_framework uses_language deployment_platform auth_method],
         limit: 10
       }
     }.freeze
 
+    # @param shortcut_name [Symbol] :decisions, :architecture, :conventions, or :project_config
+    # @param manager [Store::StoreManager] dual-database manager
+    # @param overrides [Hash] :limit override
+    # @return [Array<Hash>] result hashes with :fact, :receipts (empty), :source ("project"/"global")
     def self.for(shortcut_name, manager, **overrides)
-      config = QUERIES.fetch(shortcut_name)
-      options = config.merge(overrides)
-
-      recall = Recall.new(manager)
-      recall.query(
-        options[:query],
-        limit: options[:limit],
-        scope: options[:scope]
-      )
+      config = SHORTCUTS.fetch(shortcut_name)
+      limit = overrides[:limit] || config[:limit]
+      predicates = config[:predicates]
+
+      collect_facts(manager, predicates, limit)
     end
 
     def self.decisions(manager, **overrides)
@@ -52,5 +65,35 @@ module ClaudeMemory
     def self.project_config(manager, **overrides)
       self.for(:project_config, manager, **overrides)
     end
+
+    # Query both stores for active facts matching the given predicates.
+    # Project facts take precedence (returned first); global facts fill
+    # any remaining slots up to the limit. Does NOT create missing DBs —
+    # callers like activity_logging's "orphan manager" depend on this
+    # surface staying read-only when the project DB hasn't been
+    # initialized yet.
+    def self.collect_facts(manager, predicates, limit)
+      project_store = manager.store_if_exists("project")
+      global_store = manager.store_if_exists("global")
+
+      project_rows = fetch_active_facts(project_store, predicates, limit)
+      global_rows = fetch_active_facts(global_store, predicates, limit)
+
+      results = project_rows.map { |row| {fact: row, receipts: [], source: "project"} } +
+        global_rows.map { |row| {fact: row, receipts: [], source: "global"} }
+
+      results.first(limit)
+    end
+
+    def self.fetch_active_facts(store, predicates, limit)
+      return [] unless store
+
+      Core::FactQueryBuilder.build_facts_dataset(store)
+        .where(Sequel[:facts][:predicate] => predicates,
+          Sequel[:facts][:status] => "active")
+        .reverse_order(Sequel[:facts][:id])
+        .limit(limit)
+        .all
+    end
   end
 end

data/lib/claude_memory/store/prompt_journey_query.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Store
+    # Cross-store query for the dashboard's Prompt Journey panel. OTel
+    # events live in the global DB (writes hit the receiver, which is
+    # process-wide); activity_events with a back-tagged prompt_id can
+    # live in either store (hooks fire per-project, so hook_ingest /
+    # hook_context rows land in the project DB, while global may carry
+    # cross-project events). The query reads from all available stores
+    # and orders the merged stream by occurred_at.
+    #
+    # Accepts either a single store (legacy callers) or a StoreManager.
+    # Returns plain row hashes shaped uniformly so the panel renders
+    # both sources without branching.
+    class PromptJourneyQuery
+      def initialize(store_or_manager)
+        @stores = if store_or_manager.respond_to?(:project_store) || store_or_manager.respond_to?(:global_store)
+          [store_or_manager.respond_to?(:project_store) ? store_or_manager.project_store : nil,
+            store_or_manager.respond_to?(:global_store) ? store_or_manager.global_store : nil].compact
+        else
+          [store_or_manager].compact
+        end
+      end
+
+      # @param prompt_id [String] OTel prompt.id UUID
+      # @return [Array<Hash>] rows ordered by occurred_at ascending
+      def fetch(prompt_id)
+        return [] if prompt_id.nil? || prompt_id.empty?
+
+        rows = @stores.flat_map { |store|
+          otel_rows(store, prompt_id) + activity_rows(store, prompt_id)
+        }
+        rows.sort_by { |r| r[:occurred_at].to_s }
+      end
+
+      private
+
+      def otel_rows(store, prompt_id)
+        return [] unless store&.db&.table_exists?(:otel_events)
+        store.otel_events
+          .where(prompt_id: prompt_id)
+          .order(:occurred_at)
+          .limit(500)
+          .all
+          .map { |row| present_otel(row) }
+      end
+
+      def activity_rows(store, prompt_id)
+        return [] unless store&.db&.table_exists?(:activity_events)
+        return [] unless store.activity_events.columns.include?(:prompt_id)
+        store.activity_events
+          .where(prompt_id: prompt_id)
+          .order(:occurred_at)
+          .limit(500)
+          .all
+          .map { |row| present_activity(row) }
+      end
+
+      def present_otel(row)
+        {
+          source: "otel",
+          id: row[:id],
+          name: row[:event_name],
+          session_id: row[:session_id],
+          prompt_id: row[:prompt_id],
+          occurred_at: row[:occurred_at],
+          attributes_json: row[:attributes_json]
+        }
+      end
+
+      def present_activity(row)
+        {
+          source: "activity",
+          id: row[:id],
+          name: row[:event_type],
+          session_id: row[:session_id],
+          prompt_id: row[:prompt_id],
+          occurred_at: row[:occurred_at],
+          status: row[:status],
+          duration_ms: row[:duration_ms],
+          detail_json: row[:detail_json]
+        }
+      end
+    end
+  end
+end

data/lib/claude_memory/store/schema_manager.rb

@@ -5,7 +5,7 @@ module ClaudeMemory
     # Schema migration and version management for SQLiteStore.
     # Handles Sequel migrations, legacy version syncing, and initial setup.
     module SchemaManager
-      SCHEMA_VERSION = 17
+      SCHEMA_VERSION = 18
 
       private
 

data/lib/claude_memory/store/sqlite_store.rb

@@ -111,6 +111,15 @@ module ClaudeMemory
       # @return [Sequel::Dataset]
       def moment_feedback = @db[:moment_feedback]
 
+      # @return [Sequel::Dataset]
+      def otel_metrics = @db[:otel_metrics]
+
+      # @return [Sequel::Dataset]
+      def otel_events = @db[:otel_events]
+
+      # @return [Sequel::Dataset]
+      def otel_traces = @db[:otel_traces]
+
       # Upsert a thumbs-up/down verdict for a moment. One row per event_id
       # (unique constraint on the column) — repeat clicks overwrite. Returns
       # the persisted row.
@@ -170,6 +179,133 @@ module ClaudeMemory
         )
       end
 
+      # Insert one OTel metric data point. Two value columns let us preserve
+      # int64 precision for counters (token counts) without losing fidelity in
+      # Float — see migration 018.
+      #
+      # @param name [String] OTel metric name (e.g. "claude_code.token.usage")
+      # @param value_type [String] "int" or "double"
+      # @param value_int [Integer, nil] integer value when value_type == "int"
+      # @param value_float [Float, nil] float value when value_type == "double"
+      # @param unit [String, nil] OTel unit string ("tokens", "USD", "s", ...)
+      # @param attributes [Hash, nil] flattened attribute map
+      # @param resource [Hash, nil] resource attribute map
+      # @param recorded_at [String] ISO 8601 timestamp
+      # @return [Integer] inserted row id
+      def insert_otel_metric(name:, value_type:, recorded_at:, value_int: nil, value_float: nil,
+        unit: nil, attributes: nil, resource: nil)
+        otel_metrics.insert(otel_metric_row(
+          name: name, value_type: value_type, recorded_at: recorded_at,
+          value_int: value_int, value_float: value_float, unit: unit,
+          attributes: attributes, resource: resource
+        ))
+      end
+
+      # Bulk insert OTel metric rows in a single SQL statement. Hot-path
+      # callers (the OTLP receiver) batch dozens of points per request;
+      # multi_insert avoids the per-row prepare/bind overhead.
+      def bulk_insert_otel_metrics(rows)
+        return 0 if rows.empty?
+        otel_metrics.multi_insert(rows.map { |r| otel_metric_row(**r) })
+        rows.size
+      end
+
+      # Insert one OTel log-style event row.
+      #
+      # @param event_name [String] e.g. "user_prompt", "tool_result", "api_request"
+      # @param occurred_at [String] ISO 8601 timestamp
+      # @param session_id [String, nil]
+      # @param prompt_id [String, nil] UUID correlating events from one prompt
+      # @param attributes [Hash, nil]
+      # @param resource [Hash, nil]
+      # @return [Integer] inserted row id
+      def insert_otel_event(event_name:, occurred_at:, session_id: nil, prompt_id: nil,
+        attributes: nil, resource: nil)
+        otel_events.insert(otel_event_row(
+          event_name: event_name, occurred_at: occurred_at,
+          session_id: session_id, prompt_id: prompt_id,
+          attributes: attributes, resource: resource
+        ))
+      end
+
+      def bulk_insert_otel_events(rows)
+        return 0 if rows.empty?
+        otel_events.multi_insert(rows.map { |r| otel_event_row(**r) })
+        rows.size
+      end
+
+      # Insert one OTel trace span row. Only used when traces are explicitly
+      # opted in via Configuration#otel_traces_enabled?.
+      #
+      # @param trace_id [String]
+      # @param span_id [String]
+      # @param name [String]
+      # @param recorded_at [String]
+      # @param parent_span_id [String, nil]
+      # @param session_id [String, nil]
+      # @param prompt_id [String, nil]
+      # @param start_unix_nano [Integer, nil]
+      # @param end_unix_nano [Integer, nil]
+      # @param duration_ms [Integer, nil]
+      # @param status_code [String, nil]
+      # @param attributes [Hash, nil]
+      # @param resource [Hash, nil]
+      # @return [Integer] inserted row id
+      def insert_otel_trace_span(trace_id:, span_id:, name:, recorded_at:,
+        parent_span_id: nil, session_id: nil, prompt_id: nil,
+        start_unix_nano: nil, end_unix_nano: nil, duration_ms: nil,
+        status_code: nil, attributes: nil, resource: nil)
+        otel_traces.insert(otel_trace_row(
+          trace_id: trace_id, span_id: span_id, name: name, recorded_at: recorded_at,
+          parent_span_id: parent_span_id, session_id: session_id, prompt_id: prompt_id,
+          start_unix_nano: start_unix_nano, end_unix_nano: end_unix_nano,
+          duration_ms: duration_ms, status_code: status_code,
+          attributes: attributes, resource: resource
+        ))
+      end
+
+      def bulk_insert_otel_traces(rows)
+        return 0 if rows.empty?
+        otel_traces.multi_insert(rows.map { |r| otel_trace_row(**r) })
+        rows.size
+      end
+
+      private
+
+      def otel_metric_row(name:, value_type:, recorded_at:, value_int: nil, value_float: nil,
+        unit: nil, attributes: nil, resource: nil)
+        {
+          name: name, value_type: value_type, value_int: value_int, value_float: value_float,
+          unit: unit, attributes_json: attributes&.to_json, resource_json: resource&.to_json,
+          recorded_at: recorded_at
+        }
+      end
+
+      def otel_event_row(event_name:, occurred_at:, session_id: nil, prompt_id: nil,
+        attributes: nil, resource: nil)
+        {
+          event_name: event_name, session_id: session_id, prompt_id: prompt_id,
+          attributes_json: attributes&.to_json, resource_json: resource&.to_json,
+          occurred_at: occurred_at
+        }
+      end
+
+      def otel_trace_row(trace_id:, span_id:, name:, recorded_at:,
+        parent_span_id: nil, session_id: nil, prompt_id: nil,
+        start_unix_nano: nil, end_unix_nano: nil, duration_ms: nil,
+        status_code: nil, attributes: nil, resource: nil)
+        {
+          trace_id: trace_id, span_id: span_id, parent_span_id: parent_span_id,
+          name: name, session_id: session_id, prompt_id: prompt_id,
+          start_unix_nano: start_unix_nano, end_unix_nano: end_unix_nano,
+          duration_ms: duration_ms, status_code: status_code,
+          attributes_json: attributes&.to_json, resource_json: resource&.to_json,
+          recorded_at: recorded_at
+        }
+      end
+
+      public
+
       # --- Content items ---
 
       # Insert a content item or return the existing id if a duplicate