railwatch 0.1.4 → 0.2.0

data/app/jobs/railwatch/rollup_job.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # Recomputes the hourly rollups for one bucket from raw rows. Idempotent:
+  # runs again whenever new rows land in that hour. Debounced twice: Ingest::
+  # Batch enqueues at most one run per bucket per minute, and Solid Queue's
+  # concurrency control discards an enqueue while a run for that bucket is
+  # already queued or running (the default :block would let a busy hour pile
+  # up thousands of identical jobs). RollupCatchupJob sweeps the current and
+  # previous hour on its recurring schedule for anything either debounce
+  # dropped; an embedded install instead runs this once an hour for the
+  # previous hour from Railwatch::Maintenance, since its batches already
+  # fold themselves into the current hour as they land.
+  class RollupJob < ApplicationJob
+    queue_as :rollups
+    limits_concurrency to: 1, key: ->(environment, bucket) { "#{environment.id}:#{bucket.to_i}" }, duration: 10.minutes, on_conflict: :discard
+
+    SOURCES = {
+      "request" => [ Telemetry::Execution, ->(r) { r.requests }, ->(row) { row.name } ],
+      "job_attempt" => [ Telemetry::Execution, ->(r) { r.jobs }, ->(row) { row.name } ],
+      "scheduled_task" => [ Telemetry::Execution, ->(r) { r.scheduled }, ->(row) { row.name } ],
+      "command" => [ Telemetry::Execution, ->(r) { r.commands }, ->(row) { row.name } ],
+      "channel_action" => [ Telemetry::Execution, ->(r) { r.channels }, ->(row) { row.name } ],
+      "query" => [ Telemetry::Query, ->(r) { r }, ->(row) { row.sql.first(255) } ],
+      "outgoing_request" => [ Telemetry::OutgoingRequest, ->(r) { r }, ->(row) { "#{row.method} #{row.host}" } ],
+      "cache_event" => [ Telemetry::CacheEvent, ->(r) { r }, ->(row) { "#{row.store} #{row.key}" } ],
+      "mail" => [ Telemetry::Mail, ->(r) { r }, ->(row) { row.mailer } ],
+      "visit" => [ Telemetry::Visit, ->(r) { r }, ->(row) { row.component } ],
+      "span" => [ Telemetry::Span, ->(r) { r }, ->(row) { row.name } ],
+      "notification" => [ Telemetry::Notification, ->(r) { r }, ->(row) { row.notifier || row.delivery_method } ],
+      "view_render" => [ Telemetry::ViewRender, ->(r) { r }, ->(row) { row.identifier } ],
+      "transaction" => [ Telemetry::Transaction, ->(r) { r }, ->(row) { "#{row.connection} · #{row.outcome}" } ],
+      "llm_call" => [ Telemetry::LlmCall, ->(r) { r.models }, ->(row) { "#{row.model} · #{row.operation}" } ],
+      "llm_tool" => [ Telemetry::LlmCall, ->(r) { r.tools }, ->(row) { row.tool_name.to_s } ]
+    }.freeze
+
+    # SQLite binds at most 32,766 variables per statement; a rollup row is 14.
+    INSERT_SLICE = 500
+
+    def perform(environment, bucket)
+      bucket = bucket.utc.beginning_of_hour
+      range = bucket...(bucket + 1.hour)
+      # Recomputing a busy hour is thousands of queries; recording each of
+      # them into Railwatch's own telemetry was 70% of everything this platform
+      # ingested about itself. The job record still ships with its duration.
+      environment.with_telemetry do
+        Railwatch.ignore { recompute(environment, bucket, range) }
+      end
+    end
+
+    private
+
+    # Every group of one type is written in one transaction: the hour's
+    # rollups for that type replace each other atomically, and the write lock
+    # is held only for the writes. Rails opens each SQLite transaction
+    # IMMEDIATE, so reading the hour inside it would hold every other writer
+    # off the tenant file for the whole read -- a busy hour is tens of
+    # seconds, and ingest gets five before it gives up. On 2026-09-05 one
+    # 37-second recompute failed every batch that arrived while it ran.
+    def recompute(environment, bucket, range)
+      SOURCES.each do |type, (klass, scope, namer)|
+        Railwatch.span("rollup.#{type}", bucket: bucket.iso8601) do
+          rows = scope.call(klass).where(occurred_at: range).select(:id, :group_hash, :duration, *(klass == Telemetry::Execution ? %i[name status outcome kind] : %i[]), *(klass == Telemetry::Query ? [ Telemetry::Query::SQL ] : []), *(klass == Telemetry::OutgoingRequest ? %i[method host status_code] : []), *(klass == Telemetry::CacheEvent ? %i[store key type] : []), *(klass == Telemetry::Mail ? %i[mailer failed] : []), *(klass == Telemetry::Visit ? %i[component status] : []), *(klass == Telemetry::Notification ? %i[notifier delivery_method failed] : []), *(klass == Telemetry::ViewRender ? %i[identifier kind] : []), *(klass == Telemetry::Transaction ? %i[outcome connection] : []), *(klass == Telemetry::Span ? %i[name status] : []), *(klass == Telemetry::LlmCall ? %i[operation model tool_name status input_tokens output_tokens cache_read_tokens cache_write_tokens cost_nanos finish_reason attachments] : []))
+          groups = rows.group_by(&:group_hash).except(nil)
+          next if groups.empty?
+          rows = groups.map do |group_hash, group|
+            Telemetry::Rollup.fresh_attributes(
+              record_type: type, group_hash: group_hash, name: namer.call(group.first).to_s, bucket: bucket,
+              durations: group.map(&:duration),
+              errors: group.count { |r| error?(type, r) },
+              client_errors: group.count { |r| type == "request" && r.status.to_i.between?(400, 499) },
+              extra: extra_for(type, group))
+          end
+          # One DELETE and a few INSERTs per type instead of a SELECT, a DELETE
+          # and an INSERT per group: a busy hour of queries is 2,000 groups,
+          # and this job was 20,000 of the platform's own N+1 records a week.
+          Telemetry::Rollup.transaction do
+            # The hour was read outside this transaction (above), so a batch
+            # that landed in between has already been folded into the row
+            # about to be replaced (Ingest::RollupAbsorber). A stored count
+            # higher than the recomputed one means exactly that: keep the
+            # stored row rather than overwrite it with a snapshot that
+            # predates the batch. The next run picks the group up.
+            stored = Telemetry::Rollup.where(record_type: type, group_hash: groups.keys, bucket: bucket).pluck(:group_hash, :count).to_h
+            rows = rows.reject { |row| stored[row[:group_hash]].to_i > row[:count] }
+            next if rows.empty?
+
+            Telemetry::Rollup.where(record_type: type, group_hash: rows.map { |row| row[:group_hash] }, bucket: bucket).delete_all
+            rows.each_slice(INSERT_SLICE) { |slice| Telemetry::Rollup.insert_all(slice) }
+          end
+        end
+      end
+    end
+
+    def error?(type, row)
+      case type
+      when "request" then row.status.to_i >= 500
+      when "job_attempt", "scheduled_task", "channel_action" then row.outcome == "failed"
+      when "command" then row.status.to_i != 0
+      when "outgoing_request" then row.status_code.to_i >= 500 || row.status_code.to_i.zero?
+      when "mail" then row.failed
+      when "visit" then row.status == "error"
+      when "notification" then row.failed
+      when "transaction" then row.outcome == "rollback"
+      when "span", "llm_call", "llm_tool" then row.status == "failed"
+      else false
+      end
+    end
+
+    def extra_for(type, group)
+      case type
+      when "cache_event"
+        { hits: group.count { |r| r.type == "hit" }, misses: group.count { |r| r.type == "miss" || r.type == "generate" } }
+      when "view_render"
+        { kind: group.group_by(&:kind).max_by { |_kind, rows| rows.size }&.first }
+      when "llm_call"
+        { input_tokens: group.sum { |r| r.input_tokens.to_i }, output_tokens: group.sum { |r| r.output_tokens.to_i },
+         cache_read_tokens: group.sum { |r| r.cache_read_tokens.to_i }, cache_write_tokens: group.sum { |r| r.cache_write_tokens.to_i },
+         cost_nanos: group.sum { |r| r.cost_nanos.to_i },
+         priced: group.count { |r| r.cost_nanos },
+         unpriced: group.count { |r| r.cost_nanos.nil? },
+         # A cut-off answer is not an error and will never show in the error
+         # rate, so it needs counting on its own or it stays invisible.
+         truncated: group.count { |r| r.finish_reason == "max_tokens" },
+         with_attachments: group.count { |r| r.attachments.to_i.positive? } }
+      else {}
+      end
+    end
+  end
+end

data/app/jobs/railwatch/scheduled_task_scan_job.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Railwatch
+  class ScheduledTaskScanJob < ApplicationJob
+    queue_as :default
+
+    def perform
+      [ Environment.current ].each { |env| CheckScheduledTasksJob.perform_later(env) }
+    end
+  end
+end

data/app/models/concerns/railwatch/detection_snapshotting.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # Issue.record_occurrence! replaces `sample` wholesale on every breach, but the
+  # typed detector snapshot is durable context, not the latest reading. Capturing
+  # it costs a telemetry query per detector run, so re-capture only when the
+  # issue is newly open and otherwise carry the stored snapshot forward.
+  module DetectionSnapshotting
+    private
+
+    def carry_detection(issue, outcome)
+      detection = if outcome == :new || outcome == :regressed
+        yield
+      else
+        issue.sample_previously_was&.dig("detection")
+      end
+      issue.update!(sample: issue.sample.merge("detection" => detection)) if detection
+    end
+  end
+end

data/app/models/railwatch/alert.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module Railwatch
+  class Alert < ApplicationRecord
+    self.table_name = "railwatch_alerts"
+    MAX_DELIVERY_ATTEMPTS = 5
+    DELIVERY_LEASE = 5.minutes
+    ENQUEUE_LEASE = 5.minutes
+    RETRY_DELAYS = [ 1.minute, 5.minutes, 15.minutes, 1.hour ].freeze
+
+    # An alert is always addressed to an integration; the rule is only why it
+    # fired, and a "Send test" delivery has no rule behind it at all.
+    # No integrations in an embedded install yet: alerts are recorded, not delivered.
+    def integration = nil
+
+    def integration=(_)
+      nil
+    end
+    belongs_to :alert_rule, optional: true
+    belongs_to :issue, optional: true
+    belongs_to :summary_alert, class_name: "Alert", optional: true
+    has_many :summarized_alerts, class_name: "Alert", foreign_key: :summary_alert_id,
+      dependent: :nullify, inverse_of: :summary_alert
+
+    # `delivering` is a leased claim. A process that disappears while holding
+    # one is recovered by ReconcileAlertDeliveriesJob after DELIVERY_LEASE.
+    STATUSES = %w[pending delivering sent failed skipped collapsed summarized].freeze
+    TERMINAL_STATUSES = %w[sent failed skipped summarized].freeze
+
+    attr_accessor :suppress_auto_enqueue
+
+    before_validation :inherit_integration, on: :create
+    before_validation :assign_delivery_metadata, on: :create
+    after_create_commit :enqueue_initial_work, unless: :suppress_auto_enqueue
+
+    # How far back reconciliation looks. An alert older than this that is
+    # still pending or collapsed predates the outbox (a row an old container
+    # wrote, or one left over from before this shipped); delivering it now
+    # would page someone about something that happened hours ago.
+    RECONCILE_WINDOW = 1.hour
+
+    scope :due_for_delivery, ->(now = Time.current) {
+      where(status: "pending").where(created_at: (now - RECONCILE_WINDOW)..)
+        .where("next_delivery_at IS NULL OR next_delivery_at <= ?", now)
+        .where("delivery_enqueued_until IS NULL OR delivery_enqueued_until <= ?", now)
+    }
+    scope :with_stale_delivery_lease, ->(now = Time.current) {
+      where(status: "delivering").where("delivery_lease_expires_at <= ?", now)
+    }
+    scope :overdue_collapsed, ->(now = Time.current) {
+      where(status: "collapsed").where(created_at: (now - RECONCILE_WINDOW)..(now - AlertRule::BURST_WINDOW))
+    }
+
+    # Reserve a queue hand-off. If the process dies after this write and before
+    # perform_later, reconciliation retries once this short reservation expires.
+    def enqueue_delivery!(wait_until: nil)
+      reserved_until = nil
+      target = nil
+      with_lock do
+        return false unless status == "pending"
+
+        target = [ wait_until, next_delivery_at, Time.current ].compact.max
+        return false if delivery_enqueued_until&.future?
+
+        reserved_until = target + ENQUEUE_LEASE
+        update!(delivery_enqueued_until: reserved_until)
+      end
+
+      if target.future?
+        DeliverAlertJob.set(wait_until: target).perform_later(self)
+      else
+        DeliverAlertJob.perform_later(self)
+      end
+      true
+    rescue StandardError
+      Alert.where(id: id, status: "pending", delivery_enqueued_until: reserved_until)
+        .update_all(delivery_enqueued_until: nil, updated_at: Time.current) if reserved_until
+      raise
+    end
+
+    # Atomically turns one queued job into the only worker allowed to deliver.
+    # Duplicate jobs and jobs for terminal alerts return nil without I/O.
+    def claim_delivery!
+      with_lock do
+        return unless status == "pending"
+        return if next_delivery_at.present? && next_delivery_at.future?
+
+        token = SecureRandom.uuid
+        update!(status: "delivering", delivery_attempts: delivery_attempts + 1,
+          delivery_key: delivery_key.presence || SecureRandom.uuid,
+          delivery_lease_id: token, delivery_lease_expires_at: DELIVERY_LEASE.from_now,
+          delivery_enqueued_until: nil)
+        token
+      end
+    end
+
+    def perform_claimed_delivery!(token)
+      if integration.enabled?
+        integration.deliver(self)
+        finish_claim!(token, "sent")
+      else
+        finish_claim!(token, "skipped")
+      end
+    end
+
+    # Persists retry intent before another job is scheduled. A crash at the
+    # following queue boundary is recovered by ReconcileAlertDeliveriesJob.
+    def fail_claim!(token, exception)
+      message = "#{exception.class}: #{exception.message}".first(1000)
+      retry_at = nil
+      with_lock do
+        return unless owns_delivery_claim?(token)
+
+        if delivery_attempts >= MAX_DELIVERY_ATTEMPTS
+          update!(status: "failed", error: message, next_delivery_at: nil,
+            delivery_lease_id: nil, delivery_lease_expires_at: nil, delivery_enqueued_until: nil)
+        else
+          retry_at = RETRY_DELAYS.fetch(delivery_attempts - 1).from_now
+          update!(status: "pending", error: message, next_delivery_at: retry_at,
+            delivery_lease_id: nil, delivery_lease_expires_at: nil, delivery_enqueued_until: nil)
+        end
+        integration.update_columns(last_error: message)
+      end
+      retry_at
+    end
+
+    # A lease expiry is indistinguishable from a worker dying after the remote
+    # endpoint accepted the message but before `sent` committed. Retrying is
+    # required for at-least-once delivery; webhook consumers can deduplicate by
+    # delivery_key / Idempotency-Key.
+    def recover_stale_delivery!
+      retryable = false
+      with_lock do
+        return false unless status == "delivering" && delivery_lease_expires_at&.past?
+
+        message = error.presence || "Delivery lease expired before completion"
+        if delivery_attempts >= MAX_DELIVERY_ATTEMPTS
+          update!(status: "failed", error: message, next_delivery_at: nil,
+            delivery_lease_id: nil, delivery_lease_expires_at: nil, delivery_enqueued_until: nil)
+        else
+          update!(status: "pending", error: message, next_delivery_at: Time.current,
+            delivery_lease_id: nil, delivery_lease_expires_at: nil, delivery_enqueued_until: nil)
+          retryable = true
+        end
+      end
+      retryable
+    end
+
+    # Explicit operator action: terminal failures get a fresh, bounded attempt
+    # budget. Sent/skipped alerts are intentionally not replayed by this path.
+    def retry_delivery!
+      with_lock do
+        return false unless status == "failed"
+
+        update!(status: "pending", error: nil, delivery_attempts: 0,
+          next_delivery_at: Time.current, delivery_enqueued_until: nil,
+          delivery_lease_id: nil, delivery_lease_expires_at: nil)
+      end
+      enqueue_delivery!
+    end
+
+    # Synchronous delivery is retained for "Send test", whose HTTP response
+    # must report the real destination outcome. Normal alerts use the leased job
+    # path above.
+    def deliver!
+      return self if TERMINAL_STATUSES.include?(status)
+      return update!(status: "skipped") unless integration.enabled?
+
+      integration.deliver(self)
+      mark_sent!
+      self
+    rescue StandardError => e
+      message = "#{e.class}: #{e.message}".first(1000)
+      update!(status: "failed", error: message)
+      integration.update_columns(last_error: message)
+      raise
+    end
+
+    private
+
+    def enqueue_initial_work
+      # An embedded install has no integration to deliver to and no delivery
+      # jobs to enqueue on; the alert is recorded and that is the end of it.
+      return if integration.nil?
+
+      if status == "pending"
+        enqueue_delivery!
+      elsif status == "collapsed" && alert_rule
+        SummarizeAlertBurstJob.set(wait_until: created_at + AlertRule::BURST_WINDOW).perform_later(alert_rule)
+      end
+    end
+
+    def assign_delivery_metadata
+      self.delivery_key ||= SecureRandom.uuid
+      self.next_delivery_at ||= Time.current if status.blank? || status == "pending"
+    end
+
+    def inherit_integration
+      self.integration ||= alert_rule&.integration
+    end
+
+    def owns_delivery_claim?(token)
+      status == "delivering" && delivery_lease_id == token
+    end
+
+    def finish_claim!(token, outcome)
+      with_lock do
+        return false unless owns_delivery_claim?(token)
+
+        attributes = { status: outcome, error: nil, next_delivery_at: nil,
+                      delivery_lease_id: nil, delivery_lease_expires_at: nil,
+                      delivery_enqueued_until: nil }
+        attributes[:sent_at] = Time.current if outcome == "sent"
+        update!(attributes)
+        if outcome == "sent"
+          integration.update_columns(last_delivered_at: Time.current, last_error: nil)
+          issue&.activities&.create!(kind: "alert", data: { event: event, integration: integration.kind })
+        end
+        true
+      end
+    end
+
+    def mark_sent!
+      update!(status: "sent", sent_at: Time.current, error: nil)
+      integration.update_columns(last_delivered_at: Time.current, last_error: nil)
+      issue&.activities&.create!(kind: "alert", data: { event: event, integration: integration.kind })
+    end
+  end
+end

data/app/models/railwatch/alert_rule.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Railwatch
+  class AlertRule < ApplicationRecord
+    self.table_name = "railwatch_alert_rules"
+    TITLE_PATTERN_MAX_LENGTH = 256
+    TITLE_PATTERN_TIMEOUT = 0.01
+    EVENTS = %w[new_issue regressed_issue resolved_issue ignored_issue assigned_issue threshold anomaly silent_host quota crash_free_drop].freeze
+
+    # A deploy that breaks one page opens dozens of issues in a minute, and
+    # each one used to be its own Slack message. These two events are the ones
+    # that arrive in bursts.
+    BURST_EVENTS = %w[new_issue regressed_issue].freeze
+    BURST_WINDOW = 60.seconds
+    # Deliver this many individually, then fold the rest of the window into one
+    # summary message.
+    BURST_LIMIT = 5
+
+    def application = Application.current
+    def integration = nil
+    has_many :alerts, dependent: :destroy
+
+    validates :event, inclusion: { in: EVENTS }
+    validate :valid_title_pattern
+
+    # De-duplicate: one alert per issue per event per 30 minutes.
+    def fire!(event:, issue: nil, payload: {})
+      # Serialize the duplicate/burst decision per rule. The alert is born in
+      # its final outbox state, so its after-commit hook can never enqueue a row
+      # that is about to become collapsed.
+      with_lock do
+        return if issue && alerts.where(issue: issue, event: event).where("created_at > ?", 30.minutes.ago).exists?
+
+        status = bursting?(event, issue) ? "collapsed" : "pending"
+        alerts.create!(event: event, issue: issue, payload: payload, status: status)
+      end
+    end
+
+    # Optional narrowing of what this rule notifies about, stored in `filters`:
+    # environment_ids, kinds, min_priority, title_pattern. An absent or empty
+    # filter matches everything; an issue-less alert (quota, silent_host) is
+    # only narrowed by environment, via payload[:environment_id].
+    def matches?(issue:, payload: {})
+      return false unless environment_matches?(issue, payload)
+      return true unless issue
+      kind_matches?(issue) && priority_matches?(issue) && title_matches?(issue)
+    end
+
+    private
+
+    def valid_title_pattern
+      pattern = filters["title_pattern"].to_s
+      return if pattern.blank?
+
+      if pattern.length > TITLE_PATTERN_MAX_LENGTH
+        errors.add(:filters, "title pattern is too long (maximum is #{TITLE_PATTERN_MAX_LENGTH} characters)")
+        return
+      end
+      return unless regular_expression_pattern?(pattern)
+
+      compile_title_pattern(pattern)
+    rescue RegexpError => e
+      errors.add(:filters, "title pattern is not a valid regular expression: #{e.message}")
+    end
+
+    # True once this rule has already fired BURST_LIMIT issue alerts inside the
+    # window. Only alerts that carry an issue are counted, so summary rows can
+    # never inflate the next window's tally.
+    def bursting?(event, issue)
+      return false unless BURST_EVENTS.include?(event) && issue
+      alerts.where(event: event, created_at: BURST_WINDOW.ago..).where.not(issue_id: nil).count >= BURST_LIMIT
+    end
+
+    def environment_matches?(issue, payload)
+      ids = Array(filters["environment_ids"]).compact_blank.map(&:to_i)
+      return true if ids.empty?
+      ids.include?((issue&.environment_id || payload[:environment_id] || payload["environment_id"]).to_i)
+    end
+
+    def kind_matches?(issue)
+      kinds = Array(filters["kinds"]).compact_blank
+      kinds.empty? || kinds.include?(issue.kind)
+    end
+
+    def priority_matches?(issue)
+      minimum = filters["min_priority"]
+      return true if minimum.blank? || Issue::PRIORITIES.exclude?(minimum)
+      Issue::PRIORITIES.index(issue.priority) >= Issue::PRIORITIES.index(minimum)
+    end
+
+    # A pattern wrapped in slashes is a regular expression, anything else is a
+    # case-insensitive substring.
+    def title_matches?(issue)
+      pattern = filters["title_pattern"].to_s
+      return true if pattern.blank?
+      if regular_expression_pattern?(pattern)
+        begin
+          return issue.title.match?(compile_title_pattern(pattern))
+        rescue Regexp::TimeoutError
+          # A pattern that backtracks past its budget matches nothing rather
+          # than stalling every alert behind it.
+          Rails.logger.warn("alert rule title pattern timed out alert_rule_id=#{id}")
+          return false
+        rescue RegexpError
+          # An unparsable regexp degrades to a substring match on its source, so
+          # a rule saved before this was validated does not silently go dark.
+          pattern = pattern[1..-2]
+        end
+      end
+      issue.title.downcase.include?(pattern.downcase)
+    end
+
+    def regular_expression_pattern?(pattern)
+      pattern.start_with?("/") && pattern.end_with?("/") && pattern.length > 2
+    end
+
+    def compile_title_pattern(pattern)
+      Regexp.new(pattern[1..-2], Regexp::IGNORECASE, timeout: TITLE_PATTERN_TIMEOUT)
+    end
+  end
+end

data/app/models/railwatch/anomaly_rule.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # "Alert when p95 of GET /checkout is more than 3 standard deviations above
+  # its 7-day baseline for the same time of day." Evaluated by
+  # DetectAnomaliesJob against hourly rollups.
+  class AnomalyRule < ApplicationRecord
+    self.table_name = "railwatch_anomaly_rules"
+    MIN_BASELINE_DAYS = 3
+    MAX_BASELINE_DAYS = 30
+    MAX_DEVIATION = 10
+    MAX_WINDOW_MINUTES = 1_440
+    TARGET_KINDS = %w[requests jobs queries outgoing_requests scheduled_tasks].freeze
+    METRICS = %w[p95 avg count error_rate].freeze
+
+    def environment = Environment.current
+
+    validates :target_kind, inclusion: { in: TARGET_KINDS }
+    validates :metric, inclusion: { in: METRICS }
+    validates :target, presence: true, length: { maximum: 256 }
+    validates :deviation, numericality: { greater_than: 0, less_than_or_equal_to: MAX_DEVIATION }
+    validates :window_minutes, numericality: { only_integer: true, greater_than: 0,
+                                               less_than_or_equal_to: MAX_WINDOW_MINUTES }
+    validates :baseline_days, numericality: { only_integer: true, greater_than_or_equal_to: MIN_BASELINE_DAYS,
+                                              less_than_or_equal_to: MAX_BASELINE_DAYS }
+
+    scope :enabled, -> { where(enabled: true) }
+
+    def description
+      "#{target_kind} #{target == '*' ? 'all' : target}: #{metric} > #{deviation}σ above #{baseline_days}-day baseline"
+    end
+  end
+end

data/app/models/railwatch/application.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # The one application an embedded install monitors: the host. Not a table.
+  # Issue keys need a prefix and a counter; the rest of what the platform's
+  # Application carries (account, repository links, alert rules) is either
+  # fixed here or empty.
+  class Application
+    ID = 1
+
+    attr_reader :id, :name, :slug
+
+    def self.current = @current ||= new
+    def self.find(id)
+      raise ActiveRecord::RecordNotFound, "Application #{id}" unless id.to_i == ID
+      current
+    end
+
+    def initialize
+      @id = ID
+      @name = Rails.application.class.module_parent_name
+      @slug = @name.parameterize
+    end
+
+    def issue_prefix = Railwatch.config.issue_prefix || @name.upcase.gsub(/[^A-Z0-9]/, "")[0, 4].presence || "APP"
+    def repository_url = Railwatch.config.repository_url
+    def default_branch = "main"
+    def environments = [ Environment.current ]
+    def alert_rules = AlertRule.where(application_id: ID)
+    def account = Railwatch::Embedded::Account
+    def issues = Issue.where(application_id: ID)
+
+    # Issue numbers are per application on the platform (APP-1, APP-2, ...),
+    # allocated under a row lock on the application. There is no row here, so
+    # the meta database's own write lock serialises it: Issue creation already
+    # runs inside a transaction, and SQLite allows one writer.
+    def next_issue_number!
+      (Issue.where(application_id: ID).maximum(:number) || 0) + 1
+    end
+
+    include GlobalID::Identification
+    def to_global_id(...) = GlobalID.create(self, app: "railwatch")
+  end
+end

data/app/models/railwatch/application_record.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # Base class for what the engine owns about the monitored application besides
+  # telemetry: issues and their comments and activity, deploys, saved views,
+  # thresholds, anomaly rules, alert rules and alerts. These are authored and
+  # permanent where telemetry is derived and pruned, so they live in their own
+  # database (`railwatch` in the host's database.yml) and never in the host's
+  # primary.
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+    begin
+      connects_to database: { writing: :railwatch, reading: :railwatch }
+    rescue ActiveRecord::AdapterNotSpecified, LoadError
+      # No `railwatch` entry in this environment's database.yml, or an entry
+      # whose adapter gem is not in the bundle yet (LoadError). A cloud-transport
+      # app has none and still eager-loads this class in production, and so
+      # does the --local installer's own boot, before it has written the
+      # entry -- so loading must not raise. Using it must, though: without
+      # connects_to this class would inherit ActiveRecord::Base's PRIMARY
+      # connection, and its tables are unprefixed, so a query would read and
+      # a write would corrupt the host application's own tables. Every route
+      # into the connection goes through connection_pool, so refusing here
+      # fails closed for reads and writes alike.
+      def self.connection_pool
+        raise Railwatch::DatabaseNotConfigured,
+              "the `railwatch` database (issues, comments, saved views and deploys) is not configured for the " \
+              "#{Rails.env} environment; run `bin/rails generate railwatch:install --local` " \
+              "or add it to config/database.yml (docs/embedded.md)"
+      end
+    end
+  end
+end

data/app/models/railwatch/comment.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Railwatch
+  class Comment < ApplicationRecord
+    self.table_name = "railwatch_comments"
+    SOURCES = %w[railwatch linear].freeze
+
+    belongs_to :issue
+    def user
+      viewer_id && User.find_by(id: viewer_id)
+    end
+
+    def user=(u)
+      self.viewer_id = u&.id&.to_s
+    end
+
+    validates :body, presence: true
+    validates :source, inclusion: { in: SOURCES }
+    validates :user, presence: true, if: -> { source == "railwatch" }
+    validates :author_name, presence: true, if: -> { source == "linear" }
+
+    after_create :record_activity
+    after_create_commit :enqueue_linear_sync
+
+    private
+
+    def record_activity
+      issue.activities.create!(kind: "comment", user: user,
+        data: { comment_id: id, body: body, source: source, author_name: author_name })
+    end
+
+    def enqueue_linear_sync
+      nil unless source == "railwatch"
+    end
+  end
+end