mailmate 1.4.0 → 1.5.0

data/lib/mailmate/cli/search.rb

@@ -102,7 +102,7 @@ module Mailmate
           return 1
         end
 
-        specs = parse_search(search_string)
+        specs = order_specs(parse_search(search_string))
 
         # Compose + parse the smart-mailbox filter exactly once. The same AST
         # feeds the evaluator, the tier classifier, and the literals extractor.
@@ -157,7 +157,7 @@ module Mailmate
         epoch = Time.at(0)
         rows.sort_by! do |r|
           s = reader && (reader.value_for(r[0].to_i) rescue nil)
-          (s && !s.empty? && (Time.parse(s) rescue nil)) || epoch
+          (s && !s.empty? && (fast_time(s) || (Time.parse(s) rescue nil))) || epoch
         end
         rows.reverse! if mode == :desc
         rows
@@ -349,82 +349,196 @@ module Mailmate
         specs
       end
 
-      # ---- date matching ------------------------------------------------------
+      # Static cost rank per spec field for AND evaluation order: compiled
+      # date compare < header/tag index lookup < body matching (resolves
+      # part-ids and walks every body segment). Used by order_specs.
+      SPEC_COST = {
+        date: 0,
+        from: 1, recipients: 1, cc: 1, subject: 1, address_any: 1, any: 1,
+        tag: 1, keyword: 1,
+        body: 2, message_or_body: 2,
+      }.freeze
 
-      def date_matches?(mail, eml_id, term)
-        d = nil
-        if eml_id
-          s = (Mailmate::IndexReader.for("#date").value_for(eml_id.to_i) rescue nil)
-          if s && !s.empty?
-            d = (Time.parse(s) rescue nil)
-          end
-        end
-        if d.nil? && mail
-          raw = mail.date
-          d = raw.respond_to?(:to_time) ? raw.to_time : raw
+      # Evaluate cheap, selective specs before expensive ones. specs combine
+      # with AND (order-independent), and matches? short-circuits on the
+      # first miss — so `b invoice d 7d` should date-reject 47k messages
+      # before body matching ever runs, not after. Stable within a cost rank
+      # to keep the user's order deterministic.
+      def order_specs(specs)
+        specs.sort_by.with_index { |(field, _term, _negate), i| [SPEC_COST.fetch(field, 1), i] }
+      end
+
+      # ---- date matching ------------------------------------------------------
+      #
+      # The `#date` index stores fixed-format strings ("2026-03-19 18:55:19
+      # -0600", sender-local time with varying UTC offsets — NOT lexically
+      # comparable). date_matches? runs once per candidate message, so the
+      # hot path avoids Time.parse (~10× slower than slicing) and per-call
+      # cutoff arithmetic: terms compile once to an inclusive [lo, hi] range
+      # of YYYYMMDD integers, and the indexed value slices straight to the
+      # same integer form. Calendar-date comparison semantics are unchanged.
+
+      # Compiled day-range for a date term, memoized per term. nil = term
+      # can't match anything. The memo resets when the calendar day rolls
+      # over so relative terms ("1d") stay correct in long-lived processes
+      # (the MCP server).
+      def date_range_for(term)
+        today = Date.today
+        if @date_ranges_day != today
+          @date_ranges_day = today
+          @date_ranges = {}
         end
-        return false unless d
+        return @date_ranges[term] if @date_ranges.key?(term)
+        @date_ranges[term] = compile_date_range(term, today)
+      end
 
+      def compile_date_range(term, today)
         if term =~ /\A(\d+)([dwmy])\z/
           n, u = Regexp.last_match(1).to_i, Regexp.last_match(2)
           cutoff = case u
-                   when "d" then Date.today - n
-                   when "w" then Date.today - (n * 7)
-                   when "m" then Date.today << n
-                   when "y" then Date.today << (n * 12)
+                   when "d" then today - n
+                   when "w" then today - (n * 7)
+                   when "m" then today << n
+                   when "y" then today << (n * 12)
                    end
-          return d.to_date >= cutoff
+          return [ymd_int(cutoff), 9999_12_31]
         end
 
-        norm = term.tr("/.", "-")
-        parts = norm.split("-")
+        parts = term.tr("/.", "-").split("-")
+        y = parts[0].to_i
+        return nil if y.zero?
         case parts.size
-        when 1 then d.year.to_s == parts[0]
-        when 2 then d.year.to_s == parts[0] && d.month == parts[1].to_i
-        when 3 then d.to_date == Date.new(parts[0].to_i, parts[1].to_i, parts[2].to_i)
-        else false
+        when 1 then [y * 10_000 + 101, y * 10_000 + 1231]
+        when 2 then [y * 10_000 + parts[1].to_i * 100 + 1, y * 10_000 + parts[1].to_i * 100 + 31]
+        when 3 then [ymd = y * 10_000 + parts[1].to_i * 100 + parts[2].to_i, ymd]
+        end
+      end
+
+      def ymd_int(d)
+        d.year * 10_000 + d.month * 100 + d.day
+      end
+
+      # "2026-03-19 …" → 20260319 without Time.parse. nil when the value
+      # isn't in the indexed shape (caller falls back to the slow path).
+      def fast_ymd(s)
+        return nil unless s && s.length >= 10 && s.getbyte(4) == 0x2D && s.getbyte(7) == 0x2D
+        y = s[0, 4].to_i
+        m = s[5, 2].to_i
+        d = s[8, 2].to_i
+        return nil if y.zero? || m.zero? || d.zero?
+        y * 10_000 + m * 100 + d
+      end
+
+      def date_matches?(mail, eml_id, term)
+        range = date_range_for(term)
+        return false unless range
+
+        ymd = nil
+        if eml_id
+          s = (reader_for("#date")&.value_for(eml_id.to_i) rescue nil)
+          if s && !s.empty?
+            ymd = fast_ymd(s)
+            if ymd.nil?
+              t = (Time.parse(s) rescue nil)
+              ymd = t && ymd_int(t.to_date)
+            end
+          end
+        end
+        if ymd.nil? && mail
+          raw = mail.date
+          d = raw.respond_to?(:to_time) ? raw.to_time : raw
+          ymd = d && ymd_int(d.to_date)
         end
+        return false unless ymd
+
+        ymd >= range[0] && ymd <= range[1]
       rescue StandardError
         false
       end
 
       # ---- field-value matching -----------------------------------------------
+      #
+      # Match haystacks are RAW BYTES (ASCII-8BIT), not scrubbed UTF-8: the
+      # index values come straight out of the cache slice and the needle is
+      # `term.b`, so substring matching is byte-wise. That's exact for valid
+      # UTF-8 (lead bytes can't alias continuation bytes) and saves the
+      # dup + force_encoding + scrub allocations per header per message —
+      # scrubbing only matters when a value is *emitted*, which extract()
+      # still does via header_index_value.
+
+      # Memoized "<name>#lc" strings — interpolating per lookup costs an
+      # allocation per header per message.
+      LC_NAMES = Hash.new { |h, n| h[n] = "#{n}#lc" }
+
+      # Per-name reader memo for the match loop. IndexReader.for is cached
+      # but not free (cache-key allocation + staleness throttle check per
+      # call), and the loop calls it several times per message. The memo is
+      # keyed to the active db_headers (config swaps in tests) and reset at
+      # the top of collect_rows, so one search run sees one consistent index
+      # snapshot; staleness is re-checked between runs, which is the same
+      # granularity the MCP server needs.
+      def reader_for(name)
+        dbh = Mailmate.config.db_headers
+        if !defined?(@hdr_readers) || @hdr_readers.nil? || @hdr_readers_dbh != dbh
+          @hdr_readers = {}
+          @hdr_readers_dbh = dbh
+        end
+        return @hdr_readers[name] if @hdr_readers.key?(name)
+        @hdr_readers[name] =
+          begin
+            Mailmate::IndexReader.for(name)
+          rescue ArgumentError
+            nil
+          end
+      end
+
+      def reset_run_caches!
+        @hdr_readers = nil
+      end
 
-      # Lowercased index value for a header — tries `<name>#lc` (MailMate's
-      # pre-downcased index) first, falls back to `<name>` + downcase. Returns
-      # nil if neither index has a record for this eml-id.
+      # Lowercased raw index value for a header — tries `<name>#lc`
+      # (MailMate's pre-downcased index) first, falls back to `<name>` +
+      # downcase (byte-wise, i.e. ASCII-only — fine: the #lc index exists
+      # for every header MailMate matches on, so the fallback is for tests
+      # and fresh installs). Returns nil if neither index has a record.
       def header_index_value_lc(eml_id, name)
-        v = header_index_value(eml_id, "#{name}#lc")
+        v = header_index_value_raw(eml_id, LC_NAMES[name])
         return v unless v.nil?
-        raw = header_index_value(eml_id, name)
-        raw&.downcase
+        header_index_value_raw(eml_id, name)&.downcase
       end
 
-      # Substring-match haystack for a filter modifier. Index-first; mail
-      # fallback only kicks in for the no-index case (tests, fresh installs,
-      # messages MailMate hasn't indexed yet).
+      # Unscrubbed twin of header_index_value, for match paths only.
+      def header_index_value_raw(eml_id, name)
+        return nil if eml_id.nil?
+        reader_for(name)&.value_for(eml_id.to_i)
+      end
+
+      # Substring-match haystack for a filter modifier, as raw bytes (mail
+      # fallbacks are downcased then `.b`'d so every return path has the
+      # same encoding). Index-first; mail fallback only kicks in for the
+      # no-index case (tests, fresh installs, unindexed messages).
       def field_value(eml_id, mail, field)
         case field
         when :from
           idx = header_index_value_lc(eml_id, "from")
           return idx if idx && !idx.empty?
-          mail ? [Array(mail.from), mail[:from]&.value.to_s].flatten.join(" ").downcase : ""
+          mail ? [Array(mail.from), mail[:from]&.value.to_s].flatten.join(" ").downcase.b : "".b
         when :recipients
           parts = %w[to cc].map { |n| header_index_value_lc(eml_id, n) }.compact.reject(&:empty?)
           return parts.join(" ") unless parts.empty?
-          mail ? [Array(mail.to), Array(mail.cc), mail[:to]&.value.to_s, mail[:cc]&.value.to_s].flatten.join(" ").downcase : ""
+          mail ? [Array(mail.to), Array(mail.cc), mail[:to]&.value.to_s, mail[:cc]&.value.to_s].flatten.join(" ").downcase.b : "".b
         when :cc
           idx = header_index_value_lc(eml_id, "cc")
           return idx if idx && !idx.empty?
-          mail ? [Array(mail.cc), mail[:cc]&.value.to_s].flatten.join(" ").downcase : ""
+          mail ? [Array(mail.cc), mail[:cc]&.value.to_s].flatten.join(" ").downcase.b : "".b
         when :subject
           idx = header_index_value_lc(eml_id, "subject")
           return idx if idx && !idx.empty?
-          mail ? mail.subject.to_s.downcase : ""
+          mail ? mail.subject.to_s.downcase.b : "".b
         when :address_any
           parts = %w[from to cc reply-to sender].map { |n| header_index_value_lc(eml_id, n) }.compact.reject(&:empty?)
           return parts.join(" ") unless parts.empty?
-          mail ? [mail[:from], mail[:to], mail[:cc], mail[:reply_to], mail[:sender]].compact.map { |h| h.value.to_s }.join(" ").downcase : ""
+          mail ? [mail[:from], mail[:to], mail[:cc], mail[:reply_to], mail[:sender]].compact.map { |h| h.value.to_s }.join(" ").downcase.b : "".b
         end
       end
 
@@ -434,7 +548,7 @@ module Mailmate
       # (Thunderbird/Apple) system flags so substring matches only hit user tags.
       def tag_value(eml_id)
         return "" unless eml_id
-        flags = (Mailmate::IndexReader.for("#flags").flags_for(eml_id.to_i) rescue [])
+        flags = (reader_for("#flags")&.flags_for(eml_id.to_i) || [])
         flags.reject { |f| f.start_with?("\\", "$") }.join(" ").downcase
       end
 
@@ -515,26 +629,112 @@ module Mailmate
 
       def matches?(mail, eml_id, specs, headers_only, path = nil, index_only: false, exclude_quoted: false)
         specs.all? do |field, term, negate|
+          term_b = term.b
           hit =
             case field
             when :from, :recipients, :cc, :subject, :address_any
-              field_value(eml_id, mail, field).include?(term)
+              field_value(eml_id, mail, field).include?(term_b)
             when :tag, :keyword
-              tag_value(eml_id).include?(term)
+              tag_value(eml_id).include?(term_b)
             when :body
-              headers_only ? false : body_value(eml_id, mail, path, index_only: index_only, exclude_quoted: exclude_quoted).include?(term)
+              headers_only ? false : body_matches?(eml_id, mail, path, term, term_b, index_only: index_only, exclude_quoted: exclude_quoted)
             when :message_or_body
-              common = %i[from recipients subject].any? { |f| field_value(eml_id, mail, f).include?(term) }
-              common || (!headers_only && body_value(eml_id, mail, path, index_only: index_only, exclude_quoted: exclude_quoted).include?(term))
+              common = %i[from recipients subject].any? { |f| field_value(eml_id, mail, f).include?(term_b) }
+              common || (!headers_only && body_matches?(eml_id, mail, path, term, term_b, index_only: index_only, exclude_quoted: exclude_quoted))
             when :date
               date_matches?(mail, eml_id, term)
             when :any
-              %i[from recipients subject].any? { |f| field_value(eml_id, mail, f).include?(term) }
+              %i[from recipients subject].any? { |f| field_value(eml_id, mail, f).include?(term_b) }
             end
           negate ? !hit : hit
         end
       end
 
+      # ---- body matching --------------------------------------------------
+      #
+      # Body matching is inverted: instead of fetching and testing every
+      # body segment of every candidate message (which reallocates most of
+      # the body cache per search), one ids_matching scan per body index
+      # finds every part-id containing the term, mapped once to a set of
+      # envelope ids. Per message the test is then a hash lookup. The
+      # per-message segment walk (body_index_records / body_value) survives
+      # as the fallback when the body indexes aren't on disk at all (tests,
+      # fresh installs), and the Mail.read fallback for unindexed messages
+      # under --all is unchanged.
+
+      def body_matches?(eml_id, mail, path, term, term_b, index_only: false, exclude_quoted: false)
+        env = eml_id&.to_i
+        cands = env && body_candidates(term_b, exclude_quoted: exclude_quoted)
+        if cands
+          return true if cands.key?(env)
+          return false if index_only
+          # Indexed but not a candidate = a real non-match; only unindexed
+          # messages get the --all read-the-eml fallback below.
+          return false if body_indexed?(env, exclude_quoted: exclude_quoted)
+        else
+          segs = body_index_records(eml_id, exclude_quoted: exclude_quoted)
+          return segs.any? { |s| s.b.include?(term_b) } unless segs.empty?
+          return false if index_only
+        end
+        return text_body(mail).include?(term) if mail
+        return false if path.nil?
+        begin
+          text_body(Mail.read(path)).include?(term)
+        rescue StandardError
+          false
+        end
+      end
+
+      # Envelope-id candidate set for a body term: every message with at
+      # least one body segment containing the bytes. Returns nil when the
+      # body indexes are unavailable (callers fall back to the per-message
+      # walk). Memoized per (term, exclude_quoted) and pinned to the reader
+      # objects it was built from, so an index rebuild (staleness, reset!)
+      # invalidates naturally; the size cap stops distinct-term buildup in
+      # the long-lived MCP server.
+      def body_candidates(term_b, exclude_quoted: false)
+        names = exclude_quoted ? ["#unquoted#lc"] : ["#unquoted#lc", "#quoted#lc"]
+        readers = names.map { |n| (Mailmate::IndexReader.for(n) rescue nil) }.compact
+        return nil if readers.empty?
+
+        @body_cands ||= {}
+        key = [term_b, exclude_quoted]
+        entry = @body_cands[key]
+        if entry && entry[:readers].size == readers.size &&
+           entry[:readers].zip(readers).all? { |a, b| a.equal?(b) }
+          return entry[:set]
+        end
+
+        @body_cands.clear if @body_cands.size > 32
+        set = {}
+        readers.each do |r|
+          r.ids_matching(term_b).each_key { |pid| set[envelope_of(pid)] = true }
+        end
+        @body_cands[key] = { readers: readers, set: set }
+        set
+      end
+
+      # Map a body-part-id back to its envelope (.eml) id via
+      # #root-body-part; single-part messages have no entry there (the
+      # envelope IS the body part), so fall through to the part-id itself.
+      def envelope_of(part_id)
+        root = (Mailmate::IndexReader.for("#root-body-part").value_for(part_id) rescue nil)
+        root && !root.empty? ? root.to_i : part_id
+      end
+
+      # Does this envelope have any body-index records at all? Distinguishes
+      # "indexed, doesn't contain the term" (no match) from "MailMate hasn't
+      # body-indexed it" (eligible for the --all Mail.read fallback).
+      def body_indexed?(env, exclude_quoted: false)
+        part_ids = Mailmate::PartLookup.body_parts_of(env)
+        part_ids = [env] if part_ids.empty?
+        names = exclude_quoted ? ["#unquoted#lc"] : ["#unquoted#lc", "#quoted#lc"]
+        names.any? do |n|
+          r = (Mailmate::IndexReader.for(n) rescue nil)
+          r && part_ids.any? { |pid| r.key?(pid) }
+        end
+      end
+
       # ---- pre-filter ---------------------------------------------------------
       #
       # Filter modifiers (f/t/s/c/a) now match through MailMate's per-header
@@ -567,12 +767,29 @@ module Mailmate
 
       # ---- timestamp ----------------------------------------------------------
 
+      # Slice-parse a `#date` index value ("2026-03-19 18:55:19 -0600") into a
+      # Time, preserving the embedded UTC offset. ~10× faster than Time.parse.
+      # Returns nil when the value isn't exactly that shape (caller falls back
+      # to Time.parse).
+      def fast_time(s)
+        return nil unless s && s.length >= 25 &&
+                          s.getbyte(4) == 0x2D && s.getbyte(7) == 0x2D &&
+                          s.getbyte(13) == 0x3A && s.getbyte(16) == 0x3A
+        off = s[20, 5]
+        return nil unless off.match?(/\A[+-]\d{4}\z/)
+        Time.new(s[0, 4].to_i, s[5, 2].to_i, s[8, 2].to_i,
+                 s[11, 2].to_i, s[14, 2].to_i, s[17, 2].to_i,
+                 "#{off[0, 3]}:#{off[3, 2]}")
+      rescue ArgumentError
+        nil
+      end
+
       # Absolute send time for an eml_id, preferring the MailMate `#date` index
       # (cheap, no .eml read). Falls back to the parsed mail's Date header.
       def message_time(eml_id, mail)
         s = (Mailmate::IndexReader.for("#date").value_for(eml_id.to_i) rescue nil)
         if s && !s.empty?
-          t = (Time.parse(s) rescue nil)
+          t = fast_time(s) || (Time.parse(s) rescue nil)
           return t if t
         end
         raw = mail&.date
@@ -717,6 +934,7 @@ module Mailmate
       end
 
       def collect_rows(dirs:, specs:, fields:, smart_evaluator:, smart_literals:, filter_only_tier:, load_tier:, opts:)
+        reset_run_caches!
         rows = []
         catch(:done) do
           dirs.each do |dir|

data/lib/mailmate/cli/verify.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require_relative "../flag_check"
+
+module Mailmate
+  module CLI
+    # `mm-verify` — batch-confirm `mm-modify --emit-check` tickets against the
+    # `#flags` index in ONE index-flush wait.
+    #
+    # MailMate flushes `#flags` to disk a few seconds after an AppleScript
+    # action, and it's a single global file. So a batch of N modifies can be
+    # confirmed by waiting once for that flush and reading the index once —
+    # not by polling per message (which would pay the latency N times). Feed
+    # this the tickets `mm-modify --emit-check` printed (a JSON array, or
+    # newline-delimited JSON objects); it polls the index until every ticket's
+    # expectations hold or --check-timeout elapses, then prints a JSON summary.
+    #
+    # Exit: 0 all confirmed, 3 one or more failed, 2 bad input.
+    # @api private
+    module Verify
+      extend self
+
+      def run(argv)
+        opts = { check_timeout: 8.0, poll: 0.25, pretty: true, file: nil }
+        parser = build_parser(opts)
+        parser.parse!(argv)
+
+        raw = read_input(opts, argv)
+        return usage_error(parser, "no ticket input (pass a file, JSON arg, or pipe on stdin)") if raw.nil? || raw.strip.empty?
+
+        tickets =
+          begin
+            parse_tickets(raw)
+          rescue JSON::ParserError => e
+            warn "mm-verify: could not parse tickets as JSON array or NDJSON: #{e.message}"
+            return 2
+          end
+        return usage_error(parser, "no tickets found in input") if tickets.empty?
+
+        summary = verify(tickets, timeout: opts[:check_timeout], poll: opts[:poll])
+        $stdout.puts(opts[:pretty] ? JSON.pretty_generate(summary) : JSON.generate(summary))
+        summary["failed"].zero? ? 0 : 3
+      end
+
+      # Poll the #flags index until every ticket's expectations hold or the
+      # timeout elapses; one index read per poll iteration covers the whole
+      # batch. Returns the summary Hash.
+      def verify(tickets, timeout:, poll:)
+        deadline = Time.now + timeout
+        started  = Time.now
+        results  = nil
+        loop do
+          results = check_all(tickets)
+          break if results.all? { |r| r["ok"] }
+          break if Time.now >= deadline
+          sleep(poll)
+        end
+        passed = results.count { |r| r["ok"] }
+        {
+          "checked"        => results.size,
+          "passed"         => passed,
+          "failed"         => results.size - passed,
+          "waited_seconds" => (Time.now - started).round(2),
+          "results"        => results,
+        }
+      end
+
+      # One pass: read #flags fresh, then evaluate every ticket against it.
+      def check_all(tickets)
+        reader = fresh_flags_reader
+        tickets.map do |t|
+          eml_id = t["eml_id"].to_i
+          exps   = Array(t["expectations"])
+          flags  = reader ? reader.flags_for(eml_id) : []
+          unmet  = exps.reject { |kind, arg| Mailmate::FlagCheck.met?(flags, kind, arg) }
+          {
+            "eml_id"     => eml_id,
+            "message_id" => t["message_id"],
+            "ok"         => unmet.empty?,
+            "flags"      => flags,
+            "unmet"      => unmet.map { |kind, arg| Mailmate::FlagCheck.label(kind, arg) },
+          }
+        end
+      end
+
+      # Force a fresh read of #flags (bypass the staleness throttle so each
+      # poll sees the latest on-disk state). nil if the index is absent.
+      def fresh_flags_reader
+        Mailmate::IndexReader.reset!("#flags")
+        Mailmate::IndexReader.for("#flags")
+      rescue ArgumentError
+        nil
+      end
+
+      # Accepts a JSON array of ticket objects, or newline-delimited JSON
+      # objects (what `mm-modify --emit-check` prints, one per line). A bare
+      # single object is wrapped.
+      def parse_tickets(raw)
+        s = raw.strip
+        if s.start_with?("[")
+          Array(JSON.parse(s))
+        elsif s.start_with?("{") && !s.include?("\n")
+          [JSON.parse(s)]
+        else
+          s.each_line.map(&:strip).reject(&:empty?).map { |line| JSON.parse(line) }
+        end
+      end
+
+      def read_input(opts, argv)
+        return File.read(opts[:file]) if opts[:file]
+        return argv.join("\n") unless argv.empty?
+        return nil if $stdin.tty?
+        $stdin.read
+      end
+
+      def build_parser(opts)
+        OptionParser.new do |o|
+          o.banner = <<~BANNER
+            Usage: mm-verify [tickets.json] [options]
+                   mm-modify <id> <action> --emit-check | ... | mm-verify
+
+            Confirm a batch of `mm-modify --emit-check` tickets against the #flags
+            index, paying the index-flush wait ONCE for the whole batch. Input is a
+            JSON array of tickets, or newline-delimited JSON objects, read from a
+            file (positional or --file), a JSON argument, or stdin.
+
+            Output: a JSON summary {checked, passed, failed, waited_seconds, results}.
+            Exit 0 if all confirmed, 3 if any failed, 2 on bad input.
+          BANNER
+          o.on("--file PATH", "Read tickets from PATH instead of stdin") { |p| opts[:file] = p }
+          o.on("--check-timeout SECONDS", Float, "Max seconds to wait for #flags to reflect the batch (default 8.0)") { |s| opts[:check_timeout] = s }
+          o.on("--poll SECONDS", Float, "Index re-read interval while waiting (default 0.25)") { |s| opts[:poll] = s }
+          o.on("--compact", "Compact JSON output (default pretty)") { opts[:pretty] = false }
+        end
+      end
+
+      def usage_error(parser, msg)
+        warn "mm-verify: #{msg}"
+        warn parser.help
+        2
+      end
+    end
+  end
+end

data/lib/mailmate/eml_lookup.rb

@@ -25,9 +25,11 @@ module Mailmate
     end
 
     # Reverse-lookup: given an RFC Message-ID (with or without angle brackets),
-    # return the local eml-id (integer) or nil. O(n) scan of the message-id
-    # index — fine for one-shot CLI lookups; cache the result if you need it
-    # repeatedly.
+    # return the local eml-id (integer) or nil. Backed by a value→id map built
+    # once per index snapshot (one O(n) pass, then O(1) lookups) — the map is
+    # pinned to the IndexReader object it was built from, so when the index
+    # rebuilds (file changed on disk) the map rebuilds with it. Matters for
+    # the persistent MCP server, where resolve_id is called repeatedly.
     def self.eml_id_for_message_id(message_id)
       needle = message_id.to_s.strip
       return nil if needle.empty?
@@ -36,14 +38,29 @@ module Mailmate
                      [needle, needle[1..-2]] :
                      [needle, "<#{needle}>"]
 
-      Mailmate::IndexReader.for("message-id").each_record do |eml_id, value|
-        return eml_id if candidates.include?(value)
+      map = mid_map
+      candidates.each do |c|
+        id = map[c]
+        return id if id
       end
       nil
     rescue ArgumentError
       nil
     end
 
+    # value→eml-id map over the message-id index. `||=` keeps the FIRST id
+    # recorded for a duplicated Message-ID, matching the old scan's
+    # first-match-wins semantics (duplicates are real: Sent + Received
+    # copies, Gmail label copies).
+    def self.mid_map
+      reader = Mailmate::IndexReader.for("message-id")
+      return @mid_map[:map] if @mid_map && @mid_map[:reader].equal?(reader)
+      map = {}
+      reader.each_record { |eml_id, value| map[value] ||= eml_id }
+      @mid_map = { reader: reader, map: map }
+      map
+    end
+
     # Resolve an identifier to a local eml-id. Accepts:
     #   - eml-id (all digits)              e.g. "183715"
     #   - RFC Message-ID, brackets optional e.g. "<abc@example.com>"

data/lib/mailmate/flag_check.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Mailmate
+  # Shared #flags expectation predicate, used by both the inline check in
+  # `mm-modify` and the batch `mm-verify`. An "expectation" is a [kind, arg]
+  # pair describing the post-action state a single eml-id's flag list should
+  # satisfy; `kind` may be a Symbol (internal) or String (round-tripped
+  # through a JSON check-ticket) — both resolve the same.
+  #
+  # Kinds:
+  #   [:seen, true|false]         \Seen present / absent
+  #   [:flagged, true|false]      \Flagged present / absent
+  #   [:tag_present, "name"]      keyword present
+  #   [:tag_absent, "name"]       keyword absent
+  #   [:no_user_tags, nil]        no non-system keywords (only \… / $… remain)
+  module FlagCheck
+    module_function
+
+    def met?(flags, kind, arg)
+      case kind.to_sym
+      when :seen         then flags.include?("\\Seen") == arg
+      when :flagged      then flags.include?("\\Flagged") == arg
+      when :tag_present  then flags.include?(arg)
+      when :tag_absent   then !flags.include?(arg)
+      when :no_user_tags then flags.none? { |f| !system_flag?(f) }
+      else raise ArgumentError, "unknown flag-check kind: #{kind.inspect}"
+      end
+    end
+
+    # All expectations satisfied by `flags`? `expectations` is an array of
+    # [kind, arg] pairs.
+    def all_met?(flags, expectations)
+      expectations.all? { |kind, arg| met?(flags, kind, arg) }
+    end
+
+    def system_flag?(flag)
+      flag.start_with?("\\", "$")
+    end
+
+    # Human label for an expectation, for verification messages.
+    def label(kind, arg)
+      case kind.to_sym
+      when :seen         then arg ? "read" : "unread"
+      when :flagged      then arg ? "flagged" : "not flagged"
+      when :tag_present  then "tag #{arg.inspect}"
+      when :tag_absent   then "no tag #{arg.inspect}"
+      when :no_user_tags then "no user tags"
+      end
+    end
+  end
+end