railwatch 0.9.3 → 1.0.0

data/app/models/railwatch/telemetry/execution.rb

@@ -1,152 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    # A request, job attempt, scheduled task, command, or channel action. The parent of
-    # every other telemetry row via execution_id.
-    class Execution < TelemetryRecord
-      KINDS = %w[request job_attempt scheduled_task command channel_action].freeze
-
-      scope :of_kind, ->(kind) { where(kind: kind) }
-      scope :requests, -> { where(kind: "request") }
-      scope :jobs, -> { where(kind: "job_attempt") }
-      scope :scheduled, -> { where(kind: "scheduled_task") }
-      scope :commands, -> { where(kind: "command") }
-      scope :channels, -> { where(kind: "channel_action") }
-      scope :recent, -> { order(occurred_at: :desc) }
-      scope :between, ->(from, to) { where(occurred_at: from..to) }
-      scope :failed, -> { where("status >= 500 OR outcome = 'failed'") }
-
-      # Executions of `kind` in [from, to] whose name contains `text`, or
-      # (with previews: true) whose exception preview does. A LIKE on the rows
-      # themselves reads every execution in the window until it has a page:
-      # 32 s for a week of the platform's own requests when the text is rare.
-      # Names come from a few hundred groups, so the text is matched against
-      # the window's rollups and the rows are fetched by group_hash. Rollups
-      # trail ingest by up to a minute, so the last FRESH_NAMES are matched on
-      # the rows themselves. Only failures carry a preview, and a partial
-      # index holds just those rows.
-      #
-      # Each branch names its index and the outer lookup is by rowid, so the
-      # plan does not depend on planner statistics (an embedded install's are
-      # sampled, and sampled statistics make kind look selective). When the
-      # text is common the old walk is the fast one -- a page of matches
-      # turns up in the first few thousand rows -- so a text the rollups say
-      # matches DENSE_MATCHES rows or more keeps it. On a copy of the
-      # platform's own tenant, a week of job attempts: a text matching
-      # nothing took 657 ms walking and 27 ms here; one matching 32,766 took
-      # 11 ms walking and 215 ms here.
-      FRESH_NAMES = 5.minutes
-      DENSE_MATCHES = 1_000
-
-      # `range` is used as given, so an exclusive or empty one (FilterQuery's
-      # after:/before: can narrow a window to nothing) stays that way.
-      def self.named_like(kind, text, range, previews: false)
-        from, to = range.begin, range.end
-        pattern = "%#{sanitize_sql_like(text)}%"
-        window = where(kind: kind, occurred_at: range)
-        groups = Rollup.for_type(kind).between(from, to).where("name LIKE ? ESCAPE '\\'", pattern)
-        if !TelemetryRecord.sqlite? || groups.sum(:count) >= DENSE_MATCHES
-          like = previews ? "name LIKE :pattern ESCAPE '\\' OR exception_preview LIKE :pattern ESCAPE '\\'" : "name LIKE :pattern ESCAPE '\\'"
-          return window.where(like, pattern: pattern)
-        end
-
-        by_group = indexed_by("index_executions_on_group_hash_and_occurred_at")
-          .where(group_hash: groups.distinct.select(:group_hash), occurred_at: range, kind: kind)
-        fresh = where(kind: kind, occurred_at: [ from, to - FRESH_NAMES ].max..to).where("name LIKE ? ESCAPE '\\'", pattern)
-        ids = [ by_group, fresh ]
-        ids << indexed_by("idx_executions_with_preview").where(kind: kind, occurred_at: range)
-          .where.not(exception_preview: nil).where("exception_preview LIKE ? ESCAPE '\\'", pattern) if previews
-        from("#{quoted_table_name} NOT INDEXED").where(kind: kind, occurred_at: range)
-          .where(ids.map { |branch| "#{quoted_table_name}.id IN (#{branch.select(:id).to_sql})" }.join(" OR "))
-      end
-
-      # Executions of `kind` in `range` that are in one of `groups`, or recent
-      # enough (FRESH_NAMES) that their rollup may not exist yet. Each branch
-      # names its index and the outer lookup is by rowid, as in named_like:
-      # an OR over the two conditions made SQLite walk the whole window.
-      def self.in_groups_or_fresh(kind, groups, range)
-        by_group = indexed_by("index_executions_on_group_hash_and_occurred_at").where(group_hash: groups, occurred_at: range, kind: kind)
-        fresh = where(kind: kind, occurred_at: [ range.begin, range.end - FRESH_NAMES ].max..range.end)
-        return where(kind: kind, occurred_at: range).where(group_hash: groups).or(fresh) unless TelemetryRecord.sqlite?
-
-        from("#{quoted_table_name} NOT INDEXED").where(kind: kind, occurred_at: range)
-          .where([ by_group, fresh ].map { |branch| "#{quoted_table_name}.id IN (#{branch.select(:id).to_sql})" }.join(" OR "))
-      end
-
-      def self.indexed_by(index) = unscoped.from("#{quoted_table_name} INDEXED BY #{index}")
-      private_class_method :indexed_by
-
-      # Servers that reported an execution since `time`. Asked once per kind:
-      # there is no index led by occurred_at alone, so the obvious
-      # `where(occurred_at: time..).distinct.pluck(:server)` scans the whole
-      # table -- 15 to 26 seconds every five minutes on the platform's own
-      # 500k-row tenant, from SilentHostCheckJob -- while (kind, occurred_at)
-      # seeks straight to the window for each of the five kinds.
-      def self.servers_since(time)
-        KINDS.flat_map { |kind| where(kind: kind, occurred_at: time..).distinct.pluck(:server) }.uniq
-      end
-
-      # The schedule string each task key last ran with: the newest
-      # scheduled_task row per key carries it in detail. A task's runs share
-      # its group (the digest of its key), so that row is the last entry of
-      # its group_hash index -- one seek per key, a few dozen keys. A single
-      # MAX(id) GROUP BY task_key read every scheduled run ever kept instead:
-      # 10 s on the platform's own tenant.
-      def self.latest_schedules(keys)
-        keys.index_with do |key|
-          scheduled.where(group_hash: Record.group_hash(key), task_key: key).order(occurred_at: :desc)
-            .pick(Arel.sql("json_extract(detail, '$.schedule')"))
-        end.compact
-      end
-
-      CHILDREN = {
-        queries: Query, exceptions: Exception, cache_events: CacheEvent, mails: Mail,
-        broadcasts: Broadcast, outgoing_requests: OutgoingRequest, storage_ops: StorageOp,
-        view_renders: ViewRender, logs: Log, enqueued_jobs: EnqueuedJob, transactions: Transaction,
-        notifications: Notification, spans: Span, profiles: Profile, attachments: Attachment,
-        llm_calls: LlmCall
-      }.freeze
-
-      CHILDREN.each do |name, klass|
-        define_method(name) { klass.where(execution_id: execution_id) }
-      end
-
-      # All children merged and ordered for the waterfall timeline.
-      def timeline
-        CHILDREN.flat_map { |name, klass| klass.timeline_scope(execution_id).map { |r| r.timeline_entry(name, occurred_at) } }
-                .sort_by { |e| e[:offset] }
-      end
-
-      def failed?
-        (status && status >= 500) || outcome == "failed"
-      end
-
-      def duration_ms
-        duration / 1000.0
-      end
-
-      def queue_latency_ms
-        queue_latency && (queue_latency / 1000.0).round(1)
-      end
-
-      # The row every list surface shows for an execution: what the kind has
-      # in common, then what it adds.
-      def as_row
-        row = { execution_id: execution_id, kind: kind, name: name, status: status, outcome: outcome, duration: duration_ms.round(2),
-                occurred_at: occurred_at, deploy: deploy, server: server, user_ref: user_ref, tenant: app_tenant,
-                exception_preview: exception_preview }
-        case kind
-        when "request" then row.merge(method: self[:method], inertia_component: inertia_component, queries: counters["queries"])
-        when "job_attempt" then row.merge(queue: queue, attempt: attempt, job_id: job_id, queue_latency: queue_latency_ms)
-        when "scheduled_task" then row.merge(task_key: task_key)
-        else row
-        end
-      end
-
-      def children_count
-        counters.values.sum
-      end
-    end
-  end
-end

data/app/models/railwatch/telemetry/export_delivery.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    # One immutable delivery waiting to be sent, or the record of one that no
-    # longer is. The body is the exact bytes that will go on the wire, kept
-    # until the delivery reaches a terminal state and then freed: a retry has
-    # to be the same delivery, and the receiver recognises it by those bytes.
-    class ExportDelivery < TelemetryRecord
-      DISPOSITIONS = %w[acked rejected expired discarded].freeze
-
-      belongs_to :export_destination
-
-      scope :live, -> { where.not(state: "done") }
-      scope :due, ->(now = Time.current) { live.where(state: "pending").where(next_attempt_at: ..now) }
-      scope :overdue, ->(now = Time.current) { live.where(expires_at: ...now) }
-      scope :oldest_first, -> { order(:id) }
-
-      def live? = state != "done"
-
-      def sending? = state == "sending"
-
-      # True when this claim is still the one allowed to finish the delivery.
-      # A sender that stalled past its lease may wake and complete its request
-      # anyway; the receiver's receipt makes that harmless, but it must not be
-      # able to overwrite what the new owner has since recorded.
-      def held_by?(token, generation)
-        sending? && claim_token == token && claim_generation == generation
-      end
-    end
-  end
-end

data/app/models/railwatch/telemetry/export_destination.rb

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    # Where this database mirrors its telemetry, and everything durable about
-    # that relationship: who we are to the receiver, which token we were bound
-    # with, whether it is currently taking deliveries, and who holds the lease
-    # to send them.
-    class ExportDestination < TelemetryRecord
-      STATES = %w[ready deferred unauthorized inactive].freeze
-      COUNTERS = %w[acked rejected expired discarded shed].freeze
-
-      has_many :export_deliveries, dependent: :delete_all
-
-      validates :state, inclusion: { in: STATES }
-
-      def self.digest(value) = Digest::SHA256.hexdigest(value.to_s)
-
-      # The binding for this url and token. A different token for the same url
-      # is a different binding decision, not a silent rebind: queued bytes
-      # were admitted under the old credential and must not follow the new one
-      # to whatever tenant it belongs to.
-      def self.bind!(url:, token:, now: Time.current, retried: false)
-        row = find_or_initialize_by(url_sha256: digest(url))
-        row.url = url
-        row.producer_id ||= SecureRandom.uuid
-        fingerprint = digest(token)
-        if row.persisted? && row.credential_sha256 != fingerprint
-          row.update!(credential_sha256: fingerprint, state: "unauthorized", reason: "credential_changed",
-                      retry_at: nil)
-        else
-          row.credential_sha256 = fingerprint
-          row.created_at ||= now
-          row.save!
-        end
-        row
-      rescue ActiveRecord::RecordNotUnique
-        # Two processes binding for the first time at once. One row wins; the
-        # loser wants that row, not an error.
-        raise if retried
-
-        bind!(url: url, token: token, now: now, retried: true)
-      end
-
-      # A pause the receiver asked for ends when it said it would. Only a
-      # credential problem needs a person: everything else is a delay, and a
-      # delay that never ends is an outage we caused ourselves.
-      # Needs a person before anything can move again: a credential that was
-      # changed, or a destination taken out of service. Queueing into one
-      # just fills it with work that rebind! will throw away.
-      def blocked? = %w[unauthorized inactive].include?(state)
-
-      def sendable?(now: Time.current)
-        return false unless %w[ready deferred].include?(state)
-
-        retry_at.nil? || retry_at <= now
-      end
-
-      def bump!(counter, by = 1)
-        return unless COUNTERS.include?(counter.to_s)
-
-        self.counters = counters.merge(counter.to_s => counters.fetch(counter.to_s, 0) + by)
-      end
-    end
-  end
-end

data/app/models/railwatch/telemetry/health_sample.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    # Periodic Puma / Solid Queue health sample from one process: thread pool
-    # utilisation, socket backlog, connection pool pressure, queue depth and
-    # the age of the oldest ready job.
-    class HealthSample < TelemetryRecord
-      # The gem reports every 15s, so a process that has not sampled in ten
-      # minutes is gone rather than idle.
-      LIVE_WINDOW = 10.minutes
-      BUCKET = 5.minutes
-
-      scope :recent, -> { order(sampled_at: :desc) }
-      scope :between, ->(from, to) { where(sampled_at: from..to) }
-
-      # The newest sample from each (server, pid) pair seen since `time`: one
-      # row per process still reporting.
-      def self.live(time = LIVE_WINDOW.ago)
-        where(id: where(sampled_at: time..).group(:server, :pid).select(Arel.sql("MAX(id)"))).order(:server, :pid)
-      end
-
-      # Health over the window, one point per BUCKET: thread utilisation is a
-      # percentage averaged across the processes that sampled into the bucket,
-      # backlog is summed across them, and the queue figures are the worst
-      # seen (any process's reading covers the whole queue).
-      def self.series(from, to, bucket: BUCKET)
-        slice = bucket_expression(bucket)
-        between(from, to).group(slice).order(slice)
-          .pluck(slice,
-                 Arel.sql("AVG(CASE WHEN threads_max > 0 THEN threads_busy * 100.0 / threads_max END)"),
-                 Arel.sql("SUM(backlog)"), Arel.sql("MAX(queue_depth)"), Arel.sql("MAX(queue_latency)"))
-          .map do |t, utilisation, backlog, depth, latency|
-            { t: t, utilisation: utilisation.to_f.round(1), backlog: backlog.to_i,
-             queue_depth: depth.to_i, queue_latency: (latency.to_i / 1000.0).round(1) }
-          end
-      end
-
-      # Deepest depth reported for each queue across `samples`, most backed up
-      # first. Every worker reports the same shared queue, so the readings are
-      # merged with max, not summed.
-      def self.queue_depths(samples)
-        depths = samples.each_with_object({}) do |sample, out|
-          # A process without a job backend reports queues: nil, not {}.
-          (sample.detail["queues"] || {}).each { |queue, depth| out[queue] = [ out[queue].to_i, depth.to_i ].max }
-        end
-        depths.sort_by { |_queue, depth| -depth }.map { |queue, depth| { queue: queue, depth: depth } }
-      end
-
-      # The recurring task keys Solid Queue is running, from the newest live
-      # sample that carries a manifest (the gem sends one on every health
-      # sample). nil when no live process has reported one: an older gem, or
-      # nothing alive to ask.
-      def self.recurring_task_keys(since: LIVE_WINDOW.ago)
-        manifest = where(sampled_at: since..).where("json_extract(detail, '$.recurring_tasks') IS NOT NULL")
-          .recent.pick(Arel.sql("json_extract(detail, '$.recurring_tasks')"))
-        manifest && JSON.parse(manifest).keys
-      end
-
-      def self.bucket_expression(bucket)
-        seconds = bucket.to_i
-        Arel.sql("strftime('%Y-%m-%dT%H:%M:00Z', (strftime('%s', sampled_at) / #{seconds}) * #{seconds}, 'unixepoch')")
-      end
-      private_class_method :bucket_expression
-
-      def thread_utilisation
-        return nil if threads_max.to_i.zero?
-        threads_busy.to_f / threads_max
-      end
-    end
-  end
-end

data/app/models/railwatch/telemetry/ingest_batch.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    # One row per batch written into the telemetry database. In embedded mode
-    # it is also the delivery ledger: `batch_id` is the reporter's stable id
-    # for the batch (unique, so a replay is a no-op) and `followups` is the
-    # work the batch still owes outside its own transaction, nil once done.
-    class IngestBatch < TelemetryRecord
-      scope :recent, -> { order(received_at: :desc) }
-      scope :with_pending_followups, -> { where.not(followups: nil).order(:received_at) }
-
-      def self.committed(batch_id)
-        batch_id.present? ? find_by(batch_id: batch_id) : nil
-      end
-
-      # Runs the follow-ups a batch left behind and clears them. Safe to run
-      # more than once: the grouping commits a FollowupReceipt per (batch,
-      # group) in the railwatch database together with the occurrence count,
-      # so a second run finds the receipts and counts nothing. Clearing the
-      # outbox here is only what stops the maintenance drain from picking the
-      # row up again; it is not what makes the replay safe.
-      def drain_followups!(environment)
-        work = followups || {}
-        ids = Array(work["group_exception_ids"])
-        GroupExceptionsJob.new.perform(environment, ids, batch_id: batch_id) if ids.any?
-        update_columns(followups: nil)
-      end
-    end
-  end
-end

data/app/models/railwatch/telemetry/llm_call.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    class LlmCall < TelemetryRecord
-      include Child
-
-      # A tool invocation is a call in the same pipeline, so it shares this
-      # table; it just has a name where a model call has a model.
-      TOOL = "tool"
-
-      scope :models, -> { where.not(operation: TOOL) }
-      scope :tools, -> { where(operation: TOOL) }
-
-      NANOS_PER_DOLLAR = 1_000_000_000.0
-
-      # Dollars, or nil when the call is unpriced. Callers must render the
-      # difference: an unpriced call is not a free one.
-      def cost
-        cost_nanos && cost_nanos / NANOS_PER_DOLLAR
-      end
-
-      # What the app paid for, which is the count a bill is drawn from.
-      def total_tokens
-        [ input_tokens, output_tokens, cache_read_tokens, cache_write_tokens ].compact.sum
-      end
-
-      def timeline_label
-        tool? ? tool_name.to_s : "#{provider}/#{model}"
-      end
-
-      def tool?
-        operation == TOOL
-      end
-    end
-  end
-end

data/app/models/railwatch/telemetry/log.rb

@@ -1,91 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    class Log < TelemetryRecord
-      include Child
-
-      # Wraps each hit inside a snippet. One character for both ends so the
-      # frontend can split on it and mark the odd-numbered pieces; U+001F is
-      # not something a log line can realistically contain.
-      SNIPPET_MARK = "\u001F"
-
-      # "quoted phrase" | -excluded | bare, in the order they were typed.
-      TERM = /-?"[^"]*"|\S+/
-
-      scope :fts, ->(text) {
-        next none if text.to_s.strip.empty?
-        next where("message LIKE ?", "%#{sanitize_sql_like(text)}%") unless fts_available?
-        match = match_expression(text)
-        match ? where("logs.id IN (SELECT rowid FROM logs_fts WHERE logs_fts MATCH ?)", match) : none
-      }
-
-      class << self
-        # Free text -> an FTS5 MATCH expression. Quoted phrases stay whole,
-        # every other word becomes a prefix token so "widg" finds "widgets",
-        # and a leading "-" excludes -- but only when something positive is
-        # left to exclude from, since FTS5's NOT needs a left operand. Every
-        # term is emitted as a quoted string, which is what keeps FTS5 syntax
-        # (NEAR, *, :, parens) inert instead of raising a "syntax error".
-        # Returns nil when the text has nothing searchable in it.
-        def match_expression(text)
-          terms = text.to_s.scan(TERM).filter_map { |term| parse_term(term) }
-          positive = terms.reject(&:first).map(&:last)
-          negative = terms.select(&:first).map(&:last)
-          if positive.empty?
-            positive = negative
-            negative = []
-          end
-          return nil if positive.empty?
-          [ positive.join(" "), *negative.map { |term| "NOT #{term}" } ].join(" ")
-        end
-
-        # id => message with SNIPPET_MARK around each hit, for the rows the
-        # page is about to render. Empty unless we actually ran an FTS query.
-        def fts_snippets(ids, text)
-          return {} if ids.empty? || !fts_available?
-          match = match_expression(text)
-          return {} if match.nil?
-          sql = sanitize_sql_array([ "SELECT rowid, snippet(logs_fts, 0, ?, ?, ?, 24) FROM logs_fts WHERE logs_fts MATCH ? AND rowid IN (?)",
-            SNIPPET_MARK, SNIPPET_MARK, "…", match, ids ])
-          connection.select_rows(sql).to_h
-        end
-
-        # Postgres telemetry databases (SCOPE.md keeps them supported) have no
-        # logs_fts, and neither does a database created before the index was
-        # added. Every telemetry database is built from the same schema, so
-        # this is a process-wide fact rather than a per-environment one.
-        def fts_available?
-          return @fts_available if defined?(@fts_available)
-          @fts_available = connection.adapter_name.match?(/sqlite/i) &&
-            connection.select_value("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'logs_fts'").present?
-        end
-
-        private
-
-        # "term" -> [negated?, fts5 term], or nil if there is nothing left of
-        # it once the quotes and the minus sign come off.
-        def parse_term(term)
-          negated = term.start_with?("-") && term.length > 1
-          body = negated ? term[1..] : term
-          phrase = body.start_with?('"') && body.end_with?('"') && body.length > 1
-          body = body[1..-2].to_s if phrase
-          return nil unless body.match?(/[[:alnum:]]/)
-          [ negated, phrase ? quote(body) : "#{quote(body)}*" ]
-        end
-
-        def quote(term) = %("#{term.gsub('"', '""')}")
-      end
-
-      def as_row
-        { id: id, level: level, message: message.first(2000), tags: tags, occurred_at: occurred_at, deploy: deploy,
-          execution_id: execution_id, execution_source: execution_source, execution_preview: execution_preview,
-          source: source, tenant: app_tenant, user_ref: user_ref, context: context }
-      end
-
-      def timeline_label
-        message.to_s.first(120)
-      end
-    end
-  end
-end

data/app/models/railwatch/telemetry/mail.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    class Mail < TelemetryRecord
-      include Child
-
-      def timeline_label
-        mailer.to_s.first(120)
-      end
-    end
-  end
-end

data/app/models/railwatch/telemetry/n_plus_one.rb

@@ -1,92 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    class NPlusOne < TelemetryRecord
-      include Child
-
-      # A bound value in the SQL the gem stores. Railwatch::SqlNormalizer has
-      # already rewritten literals to "?" and one-element IN lists to "IN (?)"
-      # before an n+1 record is written; the bare-number branch only covers SQL
-      # that reached us unnormalized.
-      BIND = /(?:=\s*(?:\?|-?\d+)|IN\s*\(\s*(?:\?|-?\d+)\s*\))/i
-
-      # Matched against `shape`, which strips identifier quoting so one set of
-      # patterns covers SQLite/Postgres ("comments") and MySQL (`comments`).
-      # POLYMORPHIC has to be tried before CHILD_LOAD: an imageable_id filter
-      # matches both, and only the first one reads it as a polymorphic owner.
-      POLYMORPHIC = /\ASELECT\s+(?:\w+\.)?\*\s+FROM\s+(\w+)\s+WHERE\s+(?:\w+\.)?(\w+)_id\s*#{BIND}\s+AND\s+(?:\w+\.)?\2_type\s*#{BIND}/i
-      COUNT_LOAD = /\ASELECT\s+COUNT\(\*\)\s+(?:AS\s+\w+\s+)?FROM\s+(\w+)\s+WHERE\s+(?:\w+\.)?(\w+)_id\s*#{BIND}/i
-      EXISTS_LOAD = /\ASELECT\s+(?:1\s+AS\s+one|EXISTS\s*\(\s*SELECT\s+1)\b.*?\sFROM\s+(\w+)\s+WHERE\s+(?:\w+\.)?(\w+)_id\s*#{BIND}/i
-      CHILD_LOAD = /\ASELECT\s+(?:\w+\.)?\*\s+FROM\s+(\w+)\s+WHERE\s+(?:\w+\.)?(\w+)_id\s*#{BIND}/i
-      PARENT_LOAD = /\ASELECT\s+(?:\w+\.)?\*\s+FROM\s+(\w+)\s+WHERE\s+(?:\w+\.)?id\s*#{BIND}/i
-
-      def timeline_label
-        sql.to_s.first(120)
-      end
-
-      # A concrete fix for the repeated statement, read off its SQL shape:
-      # {kind:, parent:, association:, code:, explanation:}, or nil when the
-      # statement isn't a shape a preload or counter cache can fix.
-      def suggestion
-        s = shape
-        polymorphic_load(s) || count_load(s) || exists_load(s) || child_load(s) || parent_load(s)
-      end
-
-      private
-
-      def shape
-        sql.to_s.delete('"`').squeeze(" ").strip
-      end
-
-      def polymorphic_load(s)
-        m = POLYMORPHIC.match(s) or return nil
-        table, as = m[1], m[2]
-        { kind: "polymorphic", parent: nil, association: table,
-          code: ".includes(:#{table})",
-          explanation: "Each owner loads its #{table} in a separate query. #{table} is polymorphic (belongs_to :#{as}), " \
-                       "so add .includes(:#{table}) on the collection you iterate#{at_source}." }
-      end
-
-      def count_load(s)
-        m = COUNT_LOAD.match(s) or return nil
-        table, parent = m[1], m[2].classify
-        { kind: "counter_cache", parent: parent, association: table,
-          code: "# app/models/#{m[1].singularize}.rb\nbelongs_to :#{m[2]}, counter_cache: true\n\n# then read\n#{m[2]}.#{table}_count",
-          explanation: "Each #{parent} counts its #{table} with its own COUNT query#{at_source}. " \
-                       "A counter cache keeps the total on #{parent.tableize}.#{table}_count, so #{m[2]}.#{table}_count needs no query." }
-      end
-
-      def exists_load(s)
-        m = EXISTS_LOAD.match(s) or return nil
-        table, parent = m[1], m[2].classify
-        { kind: "exists", parent: parent, association: table,
-          code: "#{parent}.includes(:#{table})\n\n# then\n#{m[2]}.#{table}.any?",
-          explanation: "Each #{parent} checks whether it has #{table} with its own query#{at_source}. " \
-                       "Preload with #{parent}.includes(:#{table}) and call .any? on the loaded collection, or add a counter cache." }
-      end
-
-      def child_load(s)
-        m = CHILD_LOAD.match(s) or return nil
-        table, parent = m[1], m[2].classify
-        { kind: "has_many", parent: parent, association: table,
-          code: "#{parent}.includes(:#{table})",
-          explanation: "Each #{parent} loads its #{table} in a separate query#{at_source}. " \
-                       "Preload them with #{parent}.includes(:#{table}) where the #{parent.tableize} are loaded." }
-      end
-
-      def parent_load(s)
-        m = PARENT_LOAD.match(s) or return nil
-        association = m[1].singularize
-        { kind: "belongs_to", parent: nil, association: association,
-          code: ".includes(:#{association})",
-          explanation: "Each row loads its #{association} one at a time. " \
-                       "Add .includes(:#{association}) on the collection you iterate#{at_source}." }
-      end
-
-      def at_source
-        source.present? ? " at #{source}" : ""
-      end
-    end
-  end
-end

data/app/models/railwatch/telemetry/notification.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    class Notification < TelemetryRecord
-      include Child
-
-      def timeline_label
-        notifier.to_s.first(120)
-      end
-    end
-  end
-end

data/app/models/railwatch/telemetry/outgoing_request.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    class OutgoingRequest < TelemetryRecord
-      include Child
-
-      def timeline_label
-        url.to_s.first(120)
-      end
-    end
-  end
-end

data/app/models/railwatch/telemetry/person.rb

@@ -1,50 +0,0 @@
-# frozen_string_literal: true
-
-module Railwatch
-  module Telemetry
-    # A monitored application's user, as seen in telemetry. Keyed by ref
-    # ("tenant:id" or "id") so the same person across tenants stays distinct.
-    class Person < TelemetryRecord
-      scope :recent, -> { order(last_seen_at: :desc) }
-
-      def self.touch_from_record(rec, at:)
-        touch_all([ [ rec, at ] ])
-        find_by(ref: rec["id"].to_s)
-      end
-
-      # One upsert per batch instead of a find-and-save per user record: the
-      # gem emits a user record once per user per hour per process, so a busy
-      # batch carries dozens. ON CONFLICT keeps first_seen_at and only
-      # overwrites name/email/tenant when the new value is present.
-      def self.touch_all(pairs)
-        rows = pairs.filter_map do |rec, at|
-          ref = rec["id"].to_s
-          next if ref.empty?
-          { ref: ref, name: rec["name"].presence, email: rec["email"].presence, app_tenant: rec["tenant"].presence,
-            first_seen_at: at, last_seen_at: at, requests_count: 0, exceptions_count: 0 }
-        end
-        return 0 if rows.empty?
-
-        # Latest timestamp wins when the same ref repeats within a batch.
-        rows = rows.group_by { |r| r[:ref] }.map { |_ref, dup| dup.max_by { |r| r[:last_seen_at] } }
-        upsert_all(rows, unique_by: :ref, record_timestamps: false,
-                   on_duplicate: Arel.sql(<<~SQL.squish))
-                     name = COALESCE(excluded.name, people.name),
-                     email = COALESCE(excluded.email, people.email),
-                     app_tenant = COALESCE(excluded.app_tenant, people.app_tenant),
-                     first_seen_at = COALESCE(people.first_seen_at, excluded.first_seen_at),
-                     last_seen_at = MAX(people.last_seen_at, excluded.last_seen_at)
-                   SQL
-        rows.size
-      end
-
-      def executions
-        Execution.where(user_ref: ref)
-      end
-
-      def display_name
-        name.presence || email.presence || ref
-      end
-    end
-  end
-end