claude_memory 0.10.0 → 0.12.0

data/lib/claude_memory/otel/ingestor.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "../core/result"
+
+module ClaudeMemory
+  module OTel
+    # Imperative shell for OTel ingestion. Takes the parsed-row hashes
+    # produced by OtlpJsonEnvelope and writes them in a single batched
+    # transaction. Returns Core::Result so the HTTP server can map outcome
+    # to status code without rescue clauses.
+    #
+    # The ingestor accepts a `:metrics`, `:events`, or `:traces` payload —
+    # one kind per call, matching how OTLP/HTTP separates the three
+    # endpoints. Wrap each batch in transaction_with_retry so a partial
+    # failure mid-insert leaves zero rows behind.
+    class Ingestor
+      def initialize(store)
+        @store = store
+      end
+
+      # @param payload [Hash] one of {metrics: [...]}, {events: [...]},
+      #   {traces: [...]}. Other keys are ignored.
+      # @return [Core::Result] success carries inserted-count Hash;
+      #   failure carries an error message
+      def ingest(payload)
+        return Core::Result.failure("payload must be a Hash") unless payload.is_a?(Hash)
+
+        counts = {metrics: 0, events: 0, traces: 0}
+        @store.transaction_with_retry do
+          counts[:metrics] = insert_metrics(payload[:metrics] || payload["metrics"])
+          counts[:events] = insert_events(payload[:events] || payload["events"])
+          counts[:traces] = insert_traces(payload[:traces] || payload["traces"])
+        end
+        Core::Result.success(counts)
+      rescue Sequel::DatabaseError, Extralite::Error, ArgumentError, KeyError => e
+        Core::Result.failure(e.message)
+      end
+
+      private
+
+      def insert_metrics(rows)
+        rows.is_a?(Array) ? @store.bulk_insert_otel_metrics(rows) : 0
+      end
+
+      def insert_events(rows)
+        rows.is_a?(Array) ? @store.bulk_insert_otel_events(rows) : 0
+      end
+
+      def insert_traces(rows)
+        rows.is_a?(Array) ? @store.bulk_insert_otel_traces(rows) : 0
+      end
+    end
+  end
+end

data/lib/claude_memory/otel/otlp_json_envelope.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "time"
+
+module ClaudeMemory
+  module OTel
+    # Pure functional core for OTLP/HTTP/JSON payloads. Walks the canonical
+    # OTLP envelope shapes (resourceMetrics → scopeMetrics → metrics →
+    # dataPoints; resourceLogs → scopeLogs → logRecords; resourceSpans →
+    # scopeSpans → spans), flattens KeyValue attribute arrays into Ruby
+    # hashes, and returns plain row hashes ready to insert.
+    #
+    # No Time.now, no ENV reads, no DB. Pass a clock object that responds
+    # to `now` (or just `Time`) for fallback timestamps when the payload
+    # omits one. Required keys raise via Hash#fetch; optional containers
+    # default to empty arrays.
+    #
+    # All public methods return Arrays of Hashes whose keys match the
+    # SQLiteStore.insert_otel_* helpers exactly.
+    module OtlpJsonEnvelope
+      module_function
+
+      # @param payload [Hash] parsed OTLP MetricsServiceRequest JSON
+      # @param clock [#now] used for fallback when timeUnixNano is missing
+      # @return [Array<Hash>] rows for SQLiteStore#insert_otel_metric
+      def parse_metrics(payload, clock: Time)
+        rows = []
+        Array(payload["resourceMetrics"]).each do |resource_metric|
+          resource = flatten_attributes(dig_attributes(resource_metric["resource"]))
+          Array(resource_metric["scopeMetrics"]).each do |scope_metric|
+            Array(scope_metric["metrics"]).each do |metric|
+              metric_name = metric.fetch("name")
+              unit = metric["unit"]
+              data_points = collect_data_points(metric)
+              data_points.each do |point|
+                value_type, value_int, value_float = decode_metric_value(point)
+                next if value_type.nil?
+
+                rows << {
+                  name: metric_name,
+                  value_type: value_type,
+                  value_int: value_int,
+                  value_float: value_float,
+                  unit: unit,
+                  attributes: flatten_attributes(point["attributes"]),
+                  resource: resource,
+                  recorded_at: timestamp_from_point(point, clock)
+                }
+              end
+            end
+          end
+        end
+        rows
+      end
+
+      # @param payload [Hash] parsed OTLP LogsServiceRequest JSON
+      # @param clock [#now]
+      # @return [Array<Hash>] rows for SQLiteStore#insert_otel_event
+      def parse_logs(payload, clock: Time)
+        rows = []
+        Array(payload["resourceLogs"]).each do |resource_log|
+          resource = flatten_attributes(dig_attributes(resource_log["resource"]))
+          Array(resource_log["scopeLogs"]).each do |scope_log|
+            Array(scope_log["logRecords"]).each do |record|
+              attributes = flatten_attributes(record["attributes"])
+              rows << {
+                event_name: event_name_for(record, attributes),
+                occurred_at: timestamp_from_record(record, clock),
+                session_id: attributes["session.id"],
+                prompt_id: attributes["prompt.id"],
+                attributes: attributes,
+                resource: resource
+              }
+            end
+          end
+        end
+        rows
+      end
+
+      # @param payload [Hash] parsed OTLP TracesServiceRequest JSON
+      # @param clock [#now]
+      # @return [Array<Hash>] rows for SQLiteStore#insert_otel_trace_span
+      def parse_traces(payload, clock: Time)
+        rows = []
+        Array(payload["resourceSpans"]).each do |resource_span|
+          resource = flatten_attributes(dig_attributes(resource_span["resource"]))
+          Array(resource_span["scopeSpans"]).each do |scope_span|
+            Array(scope_span["spans"]).each do |span|
+              attributes = flatten_attributes(span["attributes"])
+              start_nano = parse_unix_nano(span["startTimeUnixNano"])
+              end_nano = parse_unix_nano(span["endTimeUnixNano"])
+              rows << {
+                trace_id: span.fetch("traceId"),
+                span_id: span.fetch("spanId"),
+                parent_span_id: span["parentSpanId"],
+                name: span.fetch("name"),
+                session_id: attributes["session.id"],
+                prompt_id: attributes["prompt.id"],
+                start_unix_nano: start_nano,
+                end_unix_nano: end_nano,
+                duration_ms: duration_ms_from(start_nano, end_nano),
+                status_code: span.dig("status", "code")&.to_s,
+                attributes: attributes,
+                resource: resource,
+                recorded_at: timestamp_from_unix_nano(start_nano, clock)
+              }
+            end
+          end
+        end
+        rows
+      end
+
+      # Flatten OTel KeyValue array (`[{key:, value: {stringValue: ...}}, ...]`)
+      # into a plain Hash.
+      def flatten_attributes(kv_array)
+        result = {}
+        Array(kv_array).each do |kv|
+          next unless kv.is_a?(Hash)
+          key = kv["key"]
+          next if key.nil? || key.empty?
+          result[key] = decode_any_value(kv["value"])
+        end
+        result
+      end
+
+      def decode_any_value(value)
+        return nil unless value.is_a?(Hash)
+        return value["stringValue"] if value.key?("stringValue")
+        # OTLP JSON encodes int64 as a string to avoid JS precision loss.
+        return decode_int_string(value["intValue"]) if value.key?("intValue")
+        return value["doubleValue"] if value.key?("doubleValue")
+        return value["boolValue"] if value.key?("boolValue")
+        if value.key?("arrayValue")
+          values = value.dig("arrayValue", "values") || []
+          return values.map { |v| decode_any_value(v) }
+        end
+        if value.key?("kvlistValue")
+          kvs = value.dig("kvlistValue", "values") || []
+          return flatten_attributes(kvs)
+        end
+        nil
+      end
+
+      private_class_method :decode_any_value
+
+      def decode_int_string(value)
+        return value if value.is_a?(Integer)
+        return nil if value.nil?
+        Integer(value.to_s, 10)
+      rescue ArgumentError
+        nil
+      end
+
+      private_class_method :decode_int_string
+
+      def dig_attributes(container)
+        container.is_a?(Hash) ? container["attributes"] : nil
+      end
+
+      private_class_method :dig_attributes
+
+      # Pull dataPoints out of whichever metric type wrapper is present.
+      # Histograms and summaries (rare in Claude Code's exports) return
+      # their data points; we record the count value when present.
+      def collect_data_points(metric)
+        %w[sum gauge histogram exponentialHistogram summary].each do |kind|
+          wrapper = metric[kind]
+          next unless wrapper.is_a?(Hash)
+          points = wrapper["dataPoints"]
+          return Array(points) if points
+        end
+        []
+      end
+
+      private_class_method :collect_data_points
+
+      # Returns [value_type, value_int, value_float] tuple. nil value_type
+      # means we couldn't decode anything storable.
+      def decode_metric_value(point)
+        if point.key?("asInt")
+          int_value = decode_int_string(point["asInt"])
+          return [ValueType::INT, int_value, nil] unless int_value.nil?
+        end
+        if point.key?("asDouble")
+          d = point["asDouble"]
+          return [ValueType::DOUBLE, nil, d.to_f] unless d.nil?
+        end
+        # Histogram / summary fall-back: store sum when present, count
+        # otherwise. Skip when neither is available.
+        if point.key?("sum")
+          s = point["sum"]
+          return [ValueType::DOUBLE, nil, s.to_f] unless s.nil?
+        end
+        if point.key?("count")
+          count = decode_int_string(point["count"])
+          return [ValueType::INT, count, nil] unless count.nil?
+        end
+        [nil, nil, nil]
+      end
+
+      private_class_method :decode_metric_value
+
+      def event_name_for(record, attributes)
+        # OTel logs/events: the event name lives on the attribute
+        # "event.name" by convention. Claude Code sets it as
+        # "claude_code.<name>" on its instrumentation scope, so we strip
+        # the prefix when present so panels see "user_prompt", not
+        # "claude_code.user_prompt".
+        raw = attributes["event.name"] || record["eventName"] || record.dig("body", "stringValue") || "log"
+        raw.to_s.sub(/\Aclaude_code\./, "")
+      end
+
+      private_class_method :event_name_for
+
+      def timestamp_from_point(point, clock)
+        nano = parse_unix_nano(point["timeUnixNano"]) || parse_unix_nano(point["startTimeUnixNano"])
+        timestamp_from_unix_nano(nano, clock)
+      end
+
+      private_class_method :timestamp_from_point
+
+      def timestamp_from_record(record, clock)
+        nano = parse_unix_nano(record["timeUnixNano"]) || parse_unix_nano(record["observedTimeUnixNano"])
+        timestamp_from_unix_nano(nano, clock)
+      end
+
+      private_class_method :timestamp_from_record
+
+      def timestamp_from_unix_nano(nano, clock)
+        return clock.now.utc.iso8601 if nano.nil?
+        Time.at(nano / 1_000_000_000.0).utc.iso8601
+      end
+
+      private_class_method :timestamp_from_unix_nano
+
+      def parse_unix_nano(value)
+        return nil if value.nil?
+        return value if value.is_a?(Integer)
+        Integer(value.to_s, 10)
+      rescue ArgumentError
+        nil
+      end
+
+      private_class_method :parse_unix_nano
+
+      def duration_ms_from(start_nano, end_nano)
+        return nil if start_nano.nil? || end_nano.nil?
+        ((end_nano - start_nano) / 1_000_000).to_i
+      end
+
+      private_class_method :duration_ms_from
+    end
+  end
+end

data/lib/claude_memory/otel/prompt_scope.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module OTel
+    # Back-tags activity_events with the OTel prompt.id after telemetry
+    # events arrive. Hook events (hook_ingest, hook_context, ...) fire
+    # ~immediately as the user's turn closes, but Claude Code batches OTel
+    # exports on the OTEL_METRIC_EXPORT_INTERVAL (default 60s), so by the
+    # time we see a prompt.id on the receiver, the activity_events for that
+    # turn already exist with prompt_id = NULL.
+    #
+    # Tagging strategy per (prompt_id, session_id) group:
+    #   1. session_id-match path — for activity_events carrying the same
+    #      session_id, update those that fall in the prompt's time window.
+    #      Hook events (hook_ingest, hook_context, hook_sweep, hook_publish,
+    #      roi_nudge) reliably carry session_id from the Claude Code hook
+    #      payload.
+    #   2. time-window path — for activity_events with NULL session_id
+    #      (recall, store_extraction — MCP-originated; Claude Code doesn't
+    #      thread session_id into plugin MCP calls per reference_mcp_session
+    #      _id_gap), tag by occurred_at falling in the prompt window only.
+    #
+    # Operates on both project_store and global_store when available.
+    # Cross-project tagging (projects other than the dashboard's loaded one)
+    # is out of scope — dashboard is per-project and other project DBs
+    # aren't in the manager.
+    class PromptScope
+      # Bound the prompt window so a long-running turn doesn't sweep up
+      # later activity events that belong to the NEXT prompt. The OTel
+      # spec only emits prompt.id between user_prompt and the next
+      # user_prompt, so the natural max is implicit; we add a safety
+      # ceiling.
+      MAX_WINDOW_SECONDS = 600
+      # Buffer added after the latest OTel event because hook_ingest fires
+      # AFTER the Stop event, which can be a few seconds after the last
+      # api_request.
+      POST_WINDOW_BUFFER_SECONDS = 30
+
+      def initialize(manager)
+        @manager = manager
+      end
+
+      # @param events [Array<Hash>] just-persisted OTel event rows
+      #   (each carrying :prompt_id, :session_id, :occurred_at) — the
+      #   same shape OtlpJsonEnvelope.parse_logs returns.
+      # @return [Hash] {tagged: count, groups: count}
+      def tag(events)
+        return {tagged: 0, groups: 0} if events.nil? || events.empty?
+
+        groups = group_by_prompt(events)
+        return {tagged: 0, groups: 0} if groups.empty?
+
+        tagged = 0
+        groups.each do |key, range|
+          prompt_id, session_id = key
+          [@manager.project_store, @manager.global_store].compact.each do |store|
+            tagged += tag_in_store(store, prompt_id, session_id, range)
+          end
+        end
+        {tagged: tagged, groups: groups.size}
+      rescue Sequel::DatabaseError => e
+        ClaudeMemory.logger.debug("prompt_scope tag failed: #{e.message}")
+        {tagged: 0, groups: 0, error: e.message}
+      end
+
+      private
+
+      # Returns {[prompt_id, session_id_or_nil] => (lo..hi)} where lo/hi
+      # are ISO 8601 strings derived from event occurred_at values.
+      def group_by_prompt(events)
+        events
+          .select { |e| e[:prompt_id] && !e[:prompt_id].to_s.empty? }
+          .group_by { |e| [e[:prompt_id], e[:session_id]] }
+          .each_with_object({}) do |(key, group), out|
+            timestamps = group.map { |e| e[:occurred_at] }.compact.sort
+            next if timestamps.empty?
+            lo = timestamps.first
+            hi = (Time.parse(timestamps.last) + POST_WINDOW_BUFFER_SECONDS).utc.iso8601
+            # Cap window length to MAX_WINDOW_SECONDS so a stale event
+            # batch can't sweep a wide range.
+            ceiling = (Time.parse(lo) + MAX_WINDOW_SECONDS).utc.iso8601
+            hi = [hi, ceiling].min
+            out[key] = (lo..hi)
+          end
+      end
+
+      def tag_in_store(store, prompt_id, session_id, range)
+        return 0 unless store&.db&.table_exists?(:activity_events)
+        return 0 unless store.activity_events.columns.include?(:prompt_id)
+
+        tagged_by_session = 0
+        if session_id && !session_id.to_s.empty?
+          tagged_by_session = store.activity_events
+            .where(session_id: session_id, prompt_id: nil)
+            .where { (occurred_at >= range.first) & (occurred_at <= range.last) }
+            .update(prompt_id: prompt_id)
+        end
+
+        tagged_by_window = store.activity_events
+          .where(session_id: nil, prompt_id: nil)
+          .where { (occurred_at >= range.first) & (occurred_at <= range.last) }
+          .update(prompt_id: prompt_id)
+
+        tagged_by_session + tagged_by_window
+      end
+    end
+  end
+end

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