protege 0.1.0.alpha.1

data/app/models/protege/message.rb

@@ -0,0 +1,401 @@
+# frozen_string_literal: true
+
+module Protege
+  # Persisted record of a single email — inbound or outbound — in the Protege pipeline.
+  #
+  # +Message+ is the application's source of truth for everything the engine reasons about: the web
+  # UI, the inbox, and the +ThreadHistoryResolver+ resolver all read from this model. The underlying
+  # +ActionMailbox::InboundEmail+ is retained only as a raw delivery-pipeline artifact; application
+  # logic never queries it directly. Every message belongs to exactly one +EmailThread+ and one
+  # +Persona+, and inbound messages link back to the +InboundEmail+ they were ingested from.
+  #
+  # == Lifecycle (inbound)
+  #
+  #   pending     → received, InferenceJob not yet queued
+  #   processing  → InferenceJob is running
+  #   processed   → InferenceJob completed successfully
+  #   failed      → InferenceJob raised; error captured in +last_processing_error+
+  #   bounced     → no matching persona; handled in AgentMailbox before a job is queued
+  #
+  # == Lifecycle (outbound)
+  #
+  # Outbound messages are persisted by +MessageObserver+ once delivery succeeds and carry no
+  # +processing_status+ — they are terminal records of what the agent sent.
+  class Message < ApplicationRecord
+    # ── Concerns ────────────────────────────────────────────────────────────
+
+    include BroadcastableMessage
+
+    # ── Associations ────────────────────────────────────────────────────────
+
+    belongs_to :persona,       class_name: 'Protege::Persona'
+    belongs_to :email_thread,  class_name: 'Protege::EmailThread', inverse_of: :messages
+    # Optional: only inbound messages originate from an ActionMailbox record.
+    belongs_to :inbound_email, class_name: 'ActionMailbox::InboundEmail', optional: true
+
+    has_many_attached :attachments
+
+    # Tool calls+results the agent recorded while replying to this message; replayed by
+    # +ThreadHistoryResolver+ and destroyed with the message.
+    has_many :tool_uses, as: :source, class_name: 'Protege::ToolUse', dependent: :destroy
+
+    # ── Serialization ───────────────────────────────────────────────────────
+
+    # Recipient lists are stored as JSON arrays so multi-recipient headers round-trip intact.
+    with_options coder: JSON do
+      serialize :to_addresses
+      serialize :cc_addresses
+      serialize :bcc_addresses
+    end
+
+    # ── Enums ───────────────────────────────────────────────────────────────
+
+    # Whether the message was received by or sent from the engine.
+    enum :direction, { inbound: 'inbound', outbound: 'outbound' }
+
+    # Inbound-only processing state machine; see the lifecycle notes on the class.
+    enum :processing_status, {
+      pending:    'pending',
+      processing: 'processing',
+      processed:  'processed',
+      failed:     'failed',
+      bounced:    'bounced'
+    }
+
+    # ── Validations ─────────────────────────────────────────────────────────
+
+    # Message-ID is the dedup key; uniqueness keeps retries idempotent.
+    validates :message_id,   presence: true, uniqueness: true
+    validates :direction,    presence: true
+    validates :from_address, presence: true
+    validates :sent_at,      presence: true
+
+    # ── Scopes ──────────────────────────────────────────────────────────────
+
+    # Messages the operator has not yet opened in the UI.
+    scope :unread, -> { where(read_at: nil) }
+
+    # ── Callbacks ───────────────────────────────────────────────────────────
+
+    # Refresh the thread's denormalised counters once the new message is committed.
+    after_create_commit :update_thread_stats
+
+    # ── Class methods ───────────────────────────────────────────────────────
+
+    class << self
+      # Ingest an +ActionMailbox::InboundEmail+ into a persisted, processing +Message+.
+      #
+      # Finds or creates the owning +EmailThread+, copies all mail-derived attributes onto the
+      # record, and transitions it to +processing+. Keyed on +inbound_email_id+, so calling it
+      # again for the same inbound email updates the existing record rather than duplicating it —
+      # making it safe to invoke on job retry.
+      #
+      # @param inbound_email [ActionMailbox::InboundEmail] the raw received email
+      # @param persona [Protege::Persona] the persona the email routed to
+      # @return [Protege::Message] the saved message in the +processing+ state
+      def ingest!(inbound_email:, persona:)
+        mail   = inbound_email.mail
+        thread = EmailThread.find_or_create_for(mail:, persona:)
+
+        find_or_initialize_by(inbound_email_id: inbound_email.id).tap do |record|
+          record.assign_from_mail(mail:, thread:, persona:, inbound_email:)
+          record.start_processing!
+        end
+      end
+
+      # Build (but do not save) a +Message+ from a +Mail::Message+ object.
+      #
+      # Used for outbound messages constructed outside the mailbox ingress path. The caller owns
+      # any further field assignment and the eventual +save!+.
+      #
+      # @param mail [Mail::Message] the parsed email to copy attributes from
+      # @param direction [Symbol, String] +:inbound+ or +:outbound+
+      # @param thread [Protege::EmailThread] the owning thread
+      # @param persona [Protege::Persona] the persona the message belongs to
+      # @param inbound_email [ActionMailbox::InboundEmail, nil] the source record, if any
+      # @param attach_from_mail [Boolean] rebuild attachments from the mail's parts (true for inbound,
+      #   whose files arrive as bytes); pass false for outbound, where the caller attaches known blobs.
+      # @return [Protege::Message] an unsaved message with attributes assigned
+      def build_from_mail(mail:, direction:, thread:, persona:, inbound_email: nil, attach_from_mail: true)
+        new.tap do |record|
+          record.assign_from_mail(mail:, thread:, persona:, inbound_email:, attach_from_mail:)
+          record.direction = direction
+        end
+      end
+
+      private
+
+      # Extract the decoded plain-text body from a mail object.
+      #
+      # Prefers the +text/plain+ part of a multipart message; for a single-part message, returns
+      # the decoded body only when its content type is +text/plain+.
+      #
+      # @param mail [Mail::Message] the email to read
+      # @return [String, nil] the decoded plain-text body, or nil when absent
+      def extract_text_body(mail)
+        if mail.multipart?
+          mail.text_part&.decoded
+        else
+          mail.content_type&.start_with?('text/plain') ? mail.decoded : nil
+        end
+      end
+
+      # Extract the decoded HTML body from a mail object.
+      #
+      # Prefers the +text/html+ part of a multipart message; for a single-part message, returns the
+      # decoded body only when its content type is +text/html+.
+      #
+      # @param mail [Mail::Message] the email to read
+      # @return [String, nil] the decoded HTML body, or nil when absent
+      def extract_html_body(mail)
+        if mail.multipart?
+          mail.html_part&.decoded
+        else
+          mail.content_type&.start_with?('text/html') ? mail.decoded : nil
+        end
+      end
+    end
+
+    # ── Instance methods ────────────────────────────────────────────────────
+
+    # The message's best plain-text content for replay or display.
+    #
+    # Prefers the plain-text body; when that is blank, falls back to the HTML body with its tags
+    # stripped, so an HTML-only email still yields readable text. Returns +nil+ when the message
+    # carries neither — letting callers (e.g. the +ThreadHistoryResolver+ resolver) skip empty turns.
+    #
+    # @return [String, nil] the readable body, or +nil+ when both bodies are blank
+    def readable_body
+      text = text_body.to_s.strip
+      return text unless text.empty?
+
+      html = ActionController::Base.helpers.strip_tags(html_body.to_s).strip
+      html unless html.empty?
+    end
+
+    # The standard email-style header block for this message: From / To / Cc / Date / Subject, one line
+    # each, in that fixed order. Every line is always rendered — a field with no value is shown blank
+    # (e.g. +Cc:+), never omitted — so every turn has the same predictable shape for the model. Folded
+    # into {#to_llm_text} as plain text, deliberately kept in the +content+ string rather than added as
+    # new message metadata.
+    #
+    # @return [String] the five-line header block
+    def content_header
+      [
+        "From: #{from_address}",
+        "To: #{Array(to_addresses).join(', ')}",
+        "Cc: #{Array(cc_addresses).join(', ')}",
+        "Date: #{sent_at&.utc&.strftime('%Y-%m-%d %H:%M UTC')}",
+        "Subject: #{subject}"
+      ].join("\n")
+    end
+
+    # The canonical plain-text serialization of this message for the model: the standard
+    # {#content_header} block, the readable body, and — when the message has attachments — the note the
+    # app already builds for them (see {#attachment_parts_with_note}). This is the single "message as
+    # text" artifact both the reply opening turn and the +ThreadHistoryResolver+ replay, so a turn is
+    # self-describing. Always includes the header; callers deciding whether to skip an empty turn test
+    # the message's body/attachments, not this.
+    #
+    # @return [String] the header, body, and attachment note joined into one string
+    def to_llm_text
+      note = attachment_parts_with_note.last.text if attachments.attached?
+      compose_llm_text(note:)
+    end
+
+    # This message expressed as provider content — the reply path's opening user turn. The text is
+    # {#to_llm_text} (header + body + attachment note); when the message carries viewable attachments
+    # (images/PDFs) their vision parts are appended so a multimodal model sees the files themselves.
+    # Returns a plain string when there are no attachments.
+    #
+    # @return [String, Array<Object>] the serialized text, or that text plus attachment vision parts
+    def content_parts
+      return to_llm_text unless attachments.attached?
+
+      vision, note = attachment_parts_with_note
+      [Protege::TextPart.new(text: compose_llm_text(note: note.text)), *vision]
+    end
+
+    # Walk this message's attachments once, returning +[[vision_parts], note_part]+ — each viewable file
+    # rendered as its vision part (via {Protege::StoredFile#to_part}) and a single trailing
+    # {Protege::TextPart} note naming every attachment (unviewable ones included) with its blob id.
+    # Callers flatten both into content, or take just the note part (e.g. thread-history replay).
+    #
+    # @return [Array(Array<Object>, Protege::TextPart)] the vision parts and the note part
+    def attachment_parts_with_note
+      vision  = []
+      entries = []
+
+      attachments.each do |attachment|
+        file = Protege::StoredFile.new(attachment.blob)
+        vision << file.to_part if file.viewable?
+        entries << file.summary
+      end
+
+      [vision, Protege::TextPart.new(text: attachment_note_text(entries))]
+    end
+
+    # Copy every RFC 2822-derived attribute from a +Mail::Message+ onto this record.
+    #
+    # Shared by both {.ingest!} and {.build_from_mail}. Sets the thread/persona associations and
+    # then delegates the header, body, and threading field groups to private helpers so the work
+    # stays within Active Record's metrics budget. Does not save.
+    #
+    # @param mail [Mail::Message] the parsed email to read attributes from
+    # @param thread [Protege::EmailThread] the owning thread
+    # @param persona [Protege::Persona] the persona the message belongs to
+    # @param inbound_email [ActionMailbox::InboundEmail, nil] the source record, if any
+    # @param attach_from_mail [Boolean] rebuild attachments from the mail's MIME parts; true for inbound
+    #   (files arrive as bytes), false for outbound (the caller attaches the known blobs by reference).
+    # @return [void]
+    def assign_from_mail(mail:, thread:, persona:, inbound_email: nil, attach_from_mail: true)
+      self.email_thread  = thread
+      self.persona       = persona
+      self.inbound_email = inbound_email
+
+      assign_envelope_from(mail)
+      assign_threading_from(mail)
+      assign_bodies_from(mail)
+      assign_attachments_from(mail) if attach_from_mail
+    end
+
+    # Mark this message as in-progress and persist it.
+    #
+    # Called at the start of inference (by +InferenceJob+ via {.ingest!}, and by
+    # +ConsoleInferenceJob+ directly). Defaults the direction to +:inbound+, stamps the start time,
+    # increments the attempt counter, and captures the current correlation ID for tracing.
+    #
+    # @return [void]
+    # @raise [ActiveRecord::RecordInvalid] when the record fails validation
+    def start_processing!
+      self.direction             = direction || :inbound
+      self.processing_status     = :processing
+      self.processing_started_at = Time.current
+      self.processing_attempts   = processing_attempts.to_i + 1
+      self.correlation_id        = Protege::Current.correlation_id
+      save!
+    end
+
+    # Transition the message to +processed+ and record the completion time.
+    #
+    # @return [void]
+    # @raise [ActiveRecord::RecordInvalid] when the update fails validation
+    def mark_processed!
+      update!(processing_status: :processed, processing_completed_at: Time.current)
+    end
+
+    # Transition the message to +failed+ and capture the error for later inspection.
+    #
+    # Stores the error class, message, and the first five backtrace lines in
+    # +last_processing_error+ so a failed job can be triaged without re-running it.
+    #
+    # @param error [Exception] the error raised during processing
+    # @return [void]
+    # @raise [ActiveRecord::RecordInvalid] when the update fails validation
+    def mark_failed!(error)
+      update!(
+        processing_status:     :failed,
+        last_processing_error: "#{error.class}: #{error.message}\n#{error.backtrace.first(5).join("\n")}"
+      )
+    end
+
+    private
+
+    # Assemble {#to_llm_text} from the standard header, the readable body (when present), and an optional
+    # attachment note. The header is always included, so the result is never blank. The note is passed in
+    # so a caller that already walked the attachments (see {#content_parts}) need not walk them twice.
+    #
+    # @param note [String, nil] the attachment note text, when the message has attachments
+    # @return [String] the composed text
+    def compose_llm_text(note:)
+      [content_header, readable_body.presence, note].compact.join("\n\n")
+    end
+
+    # Assign the envelope (addressing) headers from a mail object.
+    #
+    # Addresses are stored as received (the Mail gem already drops display names; case is preserved)
+    # since these columns are presentation values — normalization for routing happens on demand via
+    # +Gateway::Mail::Address+, never at write time.
+    #
+    # @param mail [Mail::Message] the email to read
+    # @return [void]
+    def assign_envelope_from(mail)
+      self.from_address  = Array(mail.from).first.to_s
+      self.to_addresses  = Array(mail.to)
+      self.cc_addresses  = Array(mail.cc)
+      self.bcc_addresses = Array(mail.bcc)
+      self.reply_to      = Array(mail.reply_to).first
+      self.subject       = mail.subject.to_s
+    end
+
+    # Assign the identity and threading headers (Message-ID, In-Reply-To, References) from a mail
+    # object, normalized through +Gateway::Mail+ to canonical angle-bracketed form.
+    #
+    # @param mail [Mail::Message] the email to read
+    # @return [void]
+    def assign_threading_from(mail)
+      self.message_id        = Gateway.canonical_message_id(mail.message_id)
+      self.in_reply_to       = Gateway.parse_message_id(mail.in_reply_to.presence)
+      self.references_header = Gateway.reference_ids(mail.references).join(' ').presence
+    end
+
+    # Assign the decoded bodies and the sent timestamp from a mail object.
+    #
+    # Falls back to the current time when the email carries no Date header.
+    #
+    # @param mail [Mail::Message] the email to read
+    # @return [void]
+    def assign_bodies_from(mail)
+      self.text_body = self.class.send(:extract_text_body, mail)
+      self.html_body = self.class.send(:extract_html_body, mail)
+      self.sent_at   = mail.date&.to_time || Time.current
+    end
+
+    # Persist the mail's attachments onto this record's Active Storage collection.
+    #
+    # Each +Mail+ attachment part is attached with its original filename and content type, decoding the
+    # part's transfer encoding via +#decoded+. The bare +#mime_type+ is stored (not +#content_type+,
+    # which carries header parameters like +; name="photo.jpg"+) so downstream type checks match cleanly.
+    # Skipped entirely when the record already has attachments, so re-running ingestion (which is
+    # retry-safe and keyed on +inbound_email_id+) never duplicates them. Inline parts are persisted
+    # alongside regular ones — the engine does not distinguish them yet.
+    #
+    # @param mail [Mail::Message] the email to read attachments from
+    # @return [void]
+    def assign_attachments_from(mail)
+      return if attachments.attached?
+      return if mail.attachments.blank?
+
+      mail.attachments.each do |part|
+        attachments.attach(
+          io:           StringIO.new(part.decoded),
+          filename:     part.filename,
+          content_type: part.mime_type
+        )
+      end
+    end
+
+    # Format the bracketed attachment listing for {#attachment_parts_with_note} from a list of per-file
+    # summaries — a concise line of every attachment (filename, type, human size, and id) so the model
+    # knows what arrived, including unviewable files, and the ids the tools accept.
+    #
+    # @param entries [Array<String>] each attachment's {Protege::StoredFile#summary}
+    # @return [String] the joined "[Attachments: …]" note
+    def attachment_note_text(entries)
+      "[Attachments: #{entries.join('; ')}]"
+    end
+
+    # Keep the owning thread's denormalised counters current after a new message commits.
+    #
+    # Uses +update_columns+ to bump +last_message_at+ and recount messages without firing further
+    # callbacks or validations.
+    #
+    # @return [void]
+    def update_thread_stats
+      email_thread.update_columns(
+        last_message_at: Time.current,
+        message_count:   email_thread.messages.count
+      )
+    end
+  end
+end

data/app/models/protege/persona.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module Protege
+  # Active Record base class for every Protege persona — the agent identity behind an email address.
+  #
+  # Personas are single-table-inheritance (STI) records: each concrete agent is a subclass defined
+  # in the host application and persisted in +protege_personas+, discriminated by the +type+ column.
+  # A persona owns the conversations addressed to it (+EmailThread+, +Message+) and declares the
+  # resolver chain that the Orchestrator runs to build the inference context for each turn.
+  #
+  # The +email_address+ is operator-chosen and must line up with the host's MX records. Inbound
+  # routing supports RFC 5233 subaddressing: +alice+thread123@example.com+ routes to the persona
+  # whose canonical address is +alice@example.com+ (see {.lookup}).
+  #
+  # @example Define a persona in the host application
+  #   class Agent < Protege::Persona
+  #     self.display_name = 'AI Agent'
+  #
+  #     resolvers do |chain|
+  #       chain.use Protege::ThreadHistoryResolver
+  #     end
+  #   end
+  class Persona < ApplicationRecord
+    self.table_name = 'protege_personas'
+
+    # Keep the Personas sidebar live (append/replace/remove).
+    include BroadcastablePersona
+
+    # Narrow the tool catalogue per persona: the code-declared +tools+ grant minus the operator's
+    # +disabled_tool_ids+ override (see +ToolScoped+).
+    include ToolScoped
+
+    # ── Associations ──────────────────────────────────────────────────────────
+
+    with_options dependent: :destroy do
+      # The persona's runtime inbound access rules — the dashboard-editable, narrowing layer of the
+      # access-control guardrail (see +AccessRule+ and +AccessControl+). Destroyed with the persona.
+      has_many :access_rules, class_name: 'Protege::AccessRule'
+
+      # Every email the persona has sent or received. Each +Message+ carries a denormalised
+      # +persona_id+, so this is the scoping seam for per-persona reads such as the +SearchEmailsTool+
+      # tool. Destroyed with the persona.
+      has_many :messages, class_name: 'Protege::Message'
+
+      # The persona's standing, cron-scheduled duties — the Loop layer (see +Responsibility+). Dashboard
+      # CRUD is nested under the persona; runs the duty's +responsibility_resolvers+ chain. Destroyed
+      # with the persona.
+      has_many :responsibilities, class_name: 'Protege::Responsibility'
+
+      # Every conversation addressed to the persona. Carries a +persona_id+ FK with no DB-level cascade,
+      # so it must be destroyed with the persona (its messages cascade in turn) — otherwise a permanent
+      # delete would orphan threads / raise a foreign-key error.
+      has_many :email_threads, class_name: 'Protege::EmailThread'
+    end
+
+    # ── Validations ─────────────────────────────────────────────────────────
+
+    with_options presence: true do
+      # STI discriminator must be present so the correct subclass is instantiated on load.
+      validates :type
+      validates :name,          uniqueness: true
+
+      # Address must be unique and well-formed; it is the routing key for inbound mail.
+      validates :email_address, uniqueness: true,
+                                format:     { with: URI::MailTo::EMAIL_REGEXP }
+    end
+
+    # ── Scopes ──────────────────────────────────────────────────────────────
+
+    default_scope { order(:name) }
+
+    # Only personas currently enabled to receive and answer mail (i.e. not archived).
+    scope :active,       -> { where(archived_at: nil) }
+
+    # Personas that have been archived (soft-removed): kept for history, out of routing.
+    scope :archived,     -> { where.not(archived_at: nil) }
+
+    # ── Display name ────────────────────────────────────────────────────────
+
+    # Backing store for the human label. Held on a +class_attribute+ rather than an instance
+    # variable so Active Record's schema-loading callbacks cannot reset it between requests.
+    class_attribute :_display_name, instance_accessor: false
+
+    # ── Class methods ───────────────────────────────────────────────────────
+
+    class << self
+      # Return the human-readable label for this persona subclass.
+      #
+      # Falls back to the demodulized class name when no explicit label has been set, so an
+      # unconfigured +Foo::Agent+ subclass reads as +"Agent"+.
+      #
+      # @return [String, nil] the configured label, or the demodulized class name
+      def display_name
+        _display_name || name&.demodulize
+      end
+
+      # Set the human-readable label for this persona subclass.
+      #
+      # @param val [String] the label to display in the UI
+      # @return [String] the assigned label
+      def display_name=(val)
+        self._display_name = val
+      end
+
+      # Return the resolver chain that assembles context for threaded email replies — the reactive
+      # path — optionally mutating it in a block.
+      #
+      # Each subclass lazily builds and owns its own +Orchestrator::ResolverChain+; chains are not
+      # shared with the parent class. Passing a block yields the chain so resolvers can be appended.
+      #
+      # @yieldparam chain [Orchestrator::ResolverChain] the subclass's reply chain
+      # @return [Orchestrator::ResolverChain] the (possibly mutated) chain
+      def message_resolvers(&block)
+        @message_resolvers ||= Orchestrator::ResolverChain.new
+        block&.call(@message_resolvers)
+        @message_resolvers
+      end
+
+      # Append a single resolver to the reply chain.
+      #
+      # @param klass [Class] the resolver class to register
+      # @param args [Array] positional arguments forwarded to the resolver
+      # @param kwargs [Hash] keyword arguments forwarded to the resolver
+      # @return [Class] self, to allow chaining further +message_resolver+ calls
+      def message_resolver(klass, *args, **kwargs)
+        message_resolvers { |chain| chain.use(klass, *args, **kwargs) }
+        self
+      end
+
+      # Return the resolver chain that assembles context for scheduled responsibility runs — the
+      # proactive path (the Loop layer) — optionally mutating it in a block.
+      #
+      # Held separately from the reply chain so a persona can present different context when acting on
+      # its own initiative (e.g. a task prompt, no inbound thread) than when answering mail. Like the
+      # reply chain it is lazily built and owned per subclass, never shared with the parent.
+      #
+      # @yieldparam chain [Orchestrator::ResolverChain] the subclass's responsibility chain
+      # @return [Orchestrator::ResolverChain] the (possibly mutated) chain
+      def responsibility_resolvers(&block)
+        @responsibility_resolvers ||= Orchestrator::ResolverChain.new
+        block&.call(@responsibility_resolvers)
+        @responsibility_resolvers
+      end
+
+      # Append a single resolver to the responsibility chain.
+      #
+      # @param klass [Class] the resolver class to register
+      # @param args [Array] positional arguments forwarded to the resolver
+      # @param kwargs [Hash] keyword arguments forwarded to the resolver
+      # @return [Class] self, to allow chaining further +responsibility_resolver+ calls
+      def responsibility_resolver(klass, *args, **kwargs)
+        responsibility_resolvers { |chain| chain.use(klass, *args, **kwargs) }
+        self
+      end
+
+      # Find the active persona that owns the given address, honouring subaddressing.
+      #
+      # Parses the address through +Gateway::Mail::Address+ and matches its +routing_key+ (the
+      # tag-stripped, lowercased +local@domain+) against the canonical +email_address+. So
+      # +Alice+thread9@Example.com+ resolves to the persona at +alice@example.com+. Returns nil for
+      # blank or malformed input.
+      #
+      # @param address [String, nil] the recipient address from an inbound email
+      # @return [Protege::Persona, nil] the matching active persona, or nil when none routes
+      def lookup(address)
+        active.find_by(email_address: Gateway.routing_key(address))
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    # ── Instance methods ────────────────────────────────────────────────────
+
+    # Return this persona's resolver chains by delegating to the class-level chains — the reply chain
+    # (+message_resolvers+) and the scheduled-run chain (+responsibility_resolvers+).
+    #
+    # @return [Orchestrator::ResolverChain] the chain declared on this persona's subclass
+    delegate :message_resolvers, :responsibility_resolvers, to: :class
+
+    # ── Archive state ─────────────────────────────────────────────────────────
+    # +active+/+archived+ are derived from +archived_at+ (no boolean column): +active?+ is what inbound
+    # routing (+.active+ scope, {.lookup}) and the status dot read, so archiving a persona removes it from
+    # service while keeping all its history.
+
+    # Whether the persona is active (not archived).
+    #
+    # @return [Boolean]
+    def active?
+      archived_at.nil?
+    end
+
+    # Whether the persona has been archived (soft-removed): out of routing + scheduled runs, data kept.
+    #
+    # @return [Boolean]
+    def archived?
+      archived_at.present?
+    end
+
+    # Archive the persona — stops inbound routing and scheduled responsibility runs; data is preserved.
+    #
+    # @return [void]
+    def archive!
+      update!(archived_at: Time.current)
+    end
+
+    # Return an archived persona to active service.
+    #
+    # @return [void]
+    def unarchive!
+      update!(archived_at: nil)
+    end
+
+    # Find one of this persona's own message attachments by its Active Storage attachment id.
+    #
+    # Scopes the lookup to attachments whose record is one of *this* persona's messages. The file tools
+    # now resolve by *blob* id (see +Protege::StoredFile.find+), so this persona-scoped lookup is
+    # currently unused by them — it is retained to become the scoping filter for the deferred
+    # authorization pass (see the blob-currency spec §9). Returns +nil+ when the id is unknown or
+    # belongs to a different persona.
+    #
+    # @param id [Integer, String] the +ActiveStorage::Attachment+ id
+    # @return [ActiveStorage::Attachment, nil] the scoped attachment, or nil
+    def find_attachment(id:)
+      ActiveStorage::Attachment
+        .where(name: 'attachments', record_type: 'Protege::Message', record_id: messages.select(:id))
+        .find_by(id:)
+    end
+  end
+end