easy_sync 0.0.5 → 2.0.0

data/lib/easy_sync/jbod/scrub_pool.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module EasySync
+  module Jbod
+    # Runs `scrub` against several drives at once: one thread per drive, one
+    # drive per thread (never two readers on the same spindle). The work is
+    # I/O-bound (MRI releases the GVL during blocking File#read), so threads
+    # are enough - no processes, no new gems, none of the process-group
+    # signal-forwarding CLAUDE.md warns sync needs. See docs/parallel-scrub.md
+    # for the full design and the measured numbers.
+    class ScrubPool
+      # +open_manifest+ is a lambda returning a fresh Manifest (one per
+      # worker: SQLite in WAL, one connection per thread). +scrubber_options+
+      # are passed to every worker's Scrubber.new besides manifest/clock/out.
+      # +lock+ is the RunLock the caller already holds; workers call
+      # +lock.note+ with the full set of drives currently being scrubbed
+      # every time that set changes. +deadline+, if given, is a Time shared
+      # by every worker (the same one passed to scrubber_options[:deadline]).
+      def initialize(jobs:, open_manifest:, lock:, scrubber_options: {}, clock: Time, deadline: nil, out: $stdout)
+        @jobs = jobs
+        @open_manifest = open_manifest
+        @lock = lock
+        @scrubber_options = scrubber_options
+        @clock = clock
+        @deadline = deadline
+        @out = out
+      end
+
+      # +targets+ are MountedDrive structs. Returns their Scrubber::Result,
+      # one per target, in target order (not completion order).
+      def run(targets)
+        return [] if targets.empty?
+
+        queue = Queue.new
+        targets.each_with_index { |target, i| queue << [i, target] }
+        results = Array.new(targets.size)
+        active = {}
+        active_mutex = Mutex.new
+        worker_count = [@jobs, targets.size].min
+
+        # Opened here, on the calling thread, before any worker starts:
+        # Manifest#initialize runs migrate!, and doing that from several
+        # threads at once on a brand new manifest invites SQLite lock errors.
+        manifests = Array.new(worker_count) { @open_manifest.call }
+
+        threads = manifests.map do |worker_manifest|
+          scrubber = Scrubber.new(worker_manifest, clock: @clock, out: @out, deadline: @deadline, **@scrubber_options)
+          Thread.new do
+            # #wait_for/#cancel already surface a worker's exception (or the
+            # Interrupt cancellation itself raises) through the caller;
+            # Ruby's default per-thread stderr report would just be noise on
+            # top of that.
+            Thread.current.report_on_exception = false
+            work(scrubber, queue, results, active, active_mutex)
+          end
+        end
+
+        begin
+          wait_for(threads)
+        ensure
+          manifests.each(&:close)
+        end
+        results.compact
+      end
+
+      private
+
+      def work(scrubber, queue, results, active, active_mutex)
+        loop do
+          break if @deadline && @clock.now >= @deadline
+
+          index, target = begin
+            queue.pop(true)
+          rescue ThreadError # empty
+            break
+          end
+
+          note_active(active, active_mutex) { active[target.friendly_name] = true }
+          begin
+            results[index] = scrubber.run(target)
+          ensure
+            note_active(active, active_mutex) { active.delete(target.friendly_name) }
+          end
+        end
+      end
+
+      def note_active(active, mutex)
+        mutex.synchronize do
+          yield
+          @lock.note(*active.keys)
+        end
+      end
+
+      # Polls rather than blocking on Thread#join in target order, so a
+      # worker that dies out of order (its target was smaller, or it simply
+      # failed sooner) is noticed - and its siblings cancelled - right away
+      # instead of only once every earlier thread happens to finish too.
+      #
+      # On Ctrl-C (Interrupt arrives here, since this is what the main thread
+      # is blocked in) or an exception raised inside a worker: cancel every
+      # other worker with Thread#raise(Interrupt) so each stops at its next
+      # file boundary and flushes what it already has, join them all
+      # (swallowing the Interrupt that cancellation itself causes), then
+      # re-raise the original problem - never silently.
+      def wait_for(threads)
+        loop do
+          threads.each do |t|
+            next if t.alive?
+
+            begin
+              t.join
+            rescue Exception => e
+              cancel(threads)
+              raise e
+            end
+          end
+          break if threads.all? { |t| !t.alive? }
+
+          sleep 0.02
+        end
+      rescue Interrupt => e
+        cancel(threads)
+        raise e
+      end
+
+      def cancel(threads)
+        threads.each { |t| t.raise(Interrupt) if t.alive? }
+        threads.each do |t|
+          t.join
+        rescue Exception
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/easy_sync/jbod/scrubber.rb

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+require 'find'
+require 'digest'
+
+module EasySync
+  module Jbod
+    # `easy_sync scrub`: reads every tracked file on one mounted drive back off
+    # the platter and compares it to its SHA-256 baseline, so bit rot is caught
+    # before it gets uploaded to the offsite backup as a "change". Read-only on
+    # the drive - it only ever writes to the manifest. See
+    # docs/integrity-scan.md for the full design.
+    class Scrubber
+      NOCACHE_CMD = 48   # F_NOCACHE, macOS only; best effort elsewhere
+      CHUNK_SIZE = 8 * 1024 * 1024
+      COMMIT_INTERVAL = 30   # seconds; also committed on exit, including Ctrl-C
+
+      Result = Struct.new(:drive, :baselined, :ok, :repaired, :corrupt, :unreadable, :unresolved, :removed, :changed,
+                          :bytes_read, :elapsed_seconds, :stopped_reason, keyword_init: true) do
+        def initialize(**)
+          super
+          %i[baselined ok repaired corrupt unreadable unresolved removed changed].each { |m| self[m] ||= 0 }
+          self.bytes_read ||= 0
+          self.elapsed_seconds ||= 0.0
+        end
+
+        def completed? = stopped_reason.nil?
+        def findings? = corrupt.positive? || unreadable.positive? || unresolved.positive?
+        def mb_per_s = elapsed_seconds.to_f.zero? ? 0.0 : (bytes_read.to_f / elapsed_seconds) / (1024 * 1024)
+      end
+
+      def initialize(manifest, excludes: [], clock: Time, out: $stdout, deadline: nil, dry_run: false)
+        @manifest = manifest
+        @excludes = Array(excludes)
+        @clock = clock
+        @out = out
+        @deadline = deadline
+        @dry_run = dry_run
+      end
+
+      # +mounted_drive+ is a MountedDrive struct. Returns a Result.
+      def run(mounted_drive)
+        drive_serial = mounted_drive.serial_number
+        mount_point = mounted_drive.mount_point
+        started = @clock.now
+        result = Result.new(drive: mounted_drive.friendly_name)
+        folders = @manifest.folders_on(drive_serial)
+
+        if @dry_run
+          dry_walk(drive_serial, mount_point, folders, result)
+        else
+          walk(drive_serial, mount_point, folders, result)
+          hash_phase(drive_serial, mount_point, result, started) unless result.stopped_reason
+        end
+        result.elapsed_seconds = @clock.now - started
+        report(result) unless @dry_run
+        result
+      end
+
+      private
+
+      # -- 1a: reconcile (walk) --------------------------------------------
+
+      # A folder is only reconciled from a walk that completed: reconciling a
+      # partial list would delete the rows (and baselines) of every file the
+      # walk never reached, and re-baseline them later from whatever is on
+      # disk by then - hiding any rot in between.
+      def walk(drive_serial, mount_point, folders, result)
+        folders.each do |folder|
+          root = File.join(mount_point, folder.folder_path)
+          next unless Dir.exist?(root)
+
+          found = walk_folder(root, root_only: folder.root?)
+          unless marker_present?(mount_point)
+            result.stopped_reason = :unmounted
+            return
+          end
+          if found.nil?
+            @out.puts "WARNING: #{folder.folder_path}: could not walk it completely; its tracked files were left as they were"
+            next
+          end
+
+          _added, removed, changed = @manifest.reconcile_checksums(drive_serial, folder.folder_path, found)
+          result.removed += removed
+          result.changed += changed
+        end
+        @manifest.prune_checksums(drive_serial, folders.map(&:folder_path))
+      end
+
+      # {relative_path => [size_bytes, mtime]} for every regular file under
+      # +root+, skipping symlinks and anything matching an exclude pattern
+      # (pruned, so an excluded directory's contents are never even visited).
+      # nil if the walk could not finish (a directory vanished or could not be
+      # read); a single file vanishing mid-walk is just left out. A root-files
+      # unit (+root_only+) owns only the files directly in +root+: every
+      # subdirectory there is some other folder's.
+      def walk_folder(root, root_only: false)
+        found = {}
+        Find.find(root, ignore_error: false) do |path|
+          next if path == root
+
+          name = File.basename(path)
+          next Find.prune if excluded?(name) || (root_only && File.directory?(path) && !File.symlink?(path))
+
+          begin
+            stat = File.lstat(path)
+          rescue Errno::ENOENT
+            next
+          end
+          next Find.prune if stat.symlink?
+
+          found[path.delete_prefix("#{root}/")] = [stat.size, stat.mtime.to_i] if stat.file?
+        end
+        found
+      rescue SystemCallError
+        nil
+      end
+
+      def excluded?(name)
+        @excludes.any? { |pat| File.fnmatch(pat, name, File::FNM_DOTMATCH) }
+      end
+
+      # -- 1b/1c: work queue, hash, record ---------------------------------
+
+      # In WAL (Jbod::ScrubPool runs several of these against one manifest at
+      # once), a connection holds the single write lock from its first write
+      # until commit; keeping a transaction open for a whole COMMIT_INTERVAL
+      # would make every other worker's write wait that long. So outcomes are
+      # buffered here and only actually written in the short transactions
+      # #flush opens - milliseconds, not seconds.
+      def hash_phase(drive_serial, mount_point, result, started)
+        rows = @manifest.checksum_frontier(drive_serial)
+        return if rows.empty?
+
+        total_files = rows.size
+        total_bytes = rows.sum { |r| r.size_bytes.to_i }
+        done = 0
+        pending = []
+
+        last_commit = @clock.now
+        begin
+          rows.each do |row|
+            # One clock read per file: reused for the deadline check, the
+            # commit-interval check and the timestamp written to the row, so
+            # a test (or a real clock) only has to advance once per file.
+            t = @clock.now
+            if @deadline && t >= @deadline
+              result.stopped_reason = :deadline
+              break
+            end
+            unless marker_present?(mount_point)
+              result.stopped_reason = :unmounted
+              break
+            end
+            if hash_one(drive_serial, mount_point, row, result, at: t.utc.iso8601, pending: pending) == :unmounted
+              result.stopped_reason = :unmounted
+              break
+            end
+            done += 1
+            if t - last_commit >= COMMIT_INTERVAL
+              flush(pending)
+              progress(result, done, total_files, total_bytes, t - started)
+              last_commit = t
+            end
+          end
+        ensure
+          # A Thread#raise(Interrupt) from Jbod::ScrubPool cancelling this
+          # worker must not land here and abort a flush half-way: everything
+          # in +pending+ was fully read and is valid to record.
+          Thread.handle_interrupt(Interrupt => :never) { flush(pending) }
+        end
+      end
+
+      def flush(pending)
+        return if pending.empty?
+
+        @manifest.db.transaction(:immediate) { pending.each { |args, kwargs| @manifest.checksum_hashed(*args, **kwargs) } }
+        pending.clear
+      end
+
+      # One line per commit, so a multi-day scrub leaves a readable trail in
+      # the log instead of being silent for hours between drive summaries.
+      def progress(result, done, total_files, total_bytes, elapsed)
+        pct = total_bytes.positive? ? ((100.0 * result.bytes_read) / total_bytes).round : 100
+        rate = elapsed.positive? ? result.bytes_read / elapsed : 0
+        remaining = total_bytes - result.bytes_read
+        eta = rate.positive? && remaining.positive? ? Placement.format_duration(remaining / rate) : '0s'
+        @out.puts "  #{result.drive}: #{done}/#{total_files} files, #{Placement.format_bytes(result.bytes_read)} " \
+                  "of #{Placement.format_bytes(total_bytes)} (#{pct}%), #{format('%.1f', rate / (1024 * 1024))} MB/s, " \
+                  "ETA #{eta}"
+      end
+
+      def marker_present?(mount_point)
+        File.file?(File.join(mount_point, MARKER_FILE))
+      end
+
+      # Returns :unmounted, leaving the row untouched, when the read failed
+      # because the drive went away mid-file: that says nothing about the
+      # file. Any other unexpected error skips just this file.
+      def hash_one(drive_serial, mount_point, row, result, at:, pending:)
+        path = File.join(mount_point, row.folder_path, row.relative_path)
+        begin
+          hex, bytes = sha256_of(path)
+        rescue SystemCallError => e
+          return :unmounted unless marker_present?(mount_point)
+
+          case e
+          when Errno::ENOENT
+            pending << [[drive_serial, row.folder_path, row.relative_path], { outcome: :vanished }]
+          when Errno::EIO
+            record_read_error(drive_serial, row, result, at: at, pending: pending)
+          else
+            @out.puts "WARNING: #{row.label}: #{e.message}; skipped, left as it was"
+          end
+          return
+        end
+        result.bytes_read += bytes
+        record_hash(drive_serial, row, hex, result, at: at, pending: pending)
+      end
+
+      def sha256_of(path)
+        digest = Digest::SHA256.new
+        bytes = 0
+        File.open(path, 'rb') do |io|
+          begin
+            io.fcntl(NOCACHE_CMD, 1)
+          rescue SystemCallError, NotImplementedError
+            nil # best effort: not every filesystem/platform supports F_NOCACHE
+          end
+          PageCache.evict(io)
+          while (chunk = io.read(CHUNK_SIZE))
+            digest.update(chunk)
+            bytes += chunk.bytesize
+          end
+        end
+        [digest.hexdigest, bytes]
+      end
+
+      # A row reaches the frontier with status <> 'ok' only when it has
+      # already been refetched by sync (see Manifest#checksum_frontier), so
+      # that alone tells us this hash is confirming a repair, not a first
+      # check.
+      def record_hash(drive_serial, row, digest, result, at:, pending:)
+        key = [drive_serial, row.folder_path, row.relative_path]
+        repair_check = !row.ok?
+        if row.digest.nil?
+          # A flagged row with no digest was unreadable on its very first
+          # read; its first good read is a repair, which also clears the flags.
+          outcome = repair_check ? :repaired : :baseline
+          pending << [key, { outcome: outcome, digest: digest, at: at }]
+          repair_check ? (result.repaired += 1) : (result.baselined += 1)
+        elsif digest == row.digest
+          outcome = repair_check ? :repaired : :confirmed
+          pending << [key, { outcome: outcome, digest: digest, at: at }]
+          repair_check ? (result.repaired += 1) : (result.ok += 1)
+        elsif repair_check
+          pending << [key, { outcome: :unresolved }]
+          result.unresolved += 1
+        else
+          pending << [key, { outcome: :corrupt, at: at }]
+          result.corrupt += 1
+        end
+      end
+
+      def record_read_error(drive_serial, row, result, at:, pending:)
+        key = [drive_serial, row.folder_path, row.relative_path]
+        if row.ok?
+          pending << [key, { outcome: :unreadable, at: at }]
+          result.unreadable += 1
+        else
+          pending << [key, { outcome: :unresolved }]
+          result.unresolved += 1
+        end
+      end
+
+      # -- dry run ----------------------------------------------------------
+
+      # Walks and reports what a real run would add/drop/reset, plus the
+      # current hash queue (an approximation: it reads the frontier as it
+      # stands now, not as the walk above would leave it). Touches nothing.
+      def dry_walk(drive_serial, mount_point, folders, result)
+        added = removed = changed = 0
+        folders.each do |folder|
+          root = File.join(mount_point, folder.folder_path)
+          next unless Dir.exist?(root)
+
+          found = walk_folder(root) or next
+          existing = @manifest.checksum_rows(drive_serial, folder.folder_path).to_h { |r| [r.relative_path, r] }
+          found.each do |rel, (size, mtime)|
+            row = existing[rel]
+            if row.nil?
+              added += 1
+            elsif row.size_bytes != size || row.mtime != mtime
+              changed += 1
+            end
+          end
+          existing.each_key { |rel| removed += 1 unless found.key?(rel) }
+        end
+
+        frontier = @manifest.checksum_frontier(drive_serial)
+        bytes = frontier.sum { |r| r.size_bytes.to_i }
+        @out.puts "DRY RUN #{result.drive}: would add #{added}, drop #{removed}, reset #{changed} tracked file" \
+                  "#{'s' if (added + removed + changed) != 1}; would hash #{frontier.size} file#{'s' if frontier.size != 1} " \
+                  "(#{Placement.format_bytes(bytes)}), about #{Placement.format_duration(bytes / (150.0 * 1024 * 1024))} at 150 MB/s"
+      end
+
+      # -- reporting ----------------------------------------------------------
+
+      def report(result)
+        @out.puts "#{result.drive}: #{result.baselined} new baseline#{'s' if result.baselined != 1}, #{result.ok} ok, " \
+                  "#{result.repaired} repaired, #{result.corrupt} CORRUPT, #{result.unreadable} UNREADABLE, " \
+                  "#{result.unresolved} UNRESOLVED, #{result.removed} removed, #{result.changed} changed " \
+                  "(#{Placement.format_bytes(result.bytes_read)} read, #{format('%.1f', result.mb_per_s)} MB/s)"
+        case result.stopped_reason
+        when :deadline then @out.puts "  stopped: --for deadline reached; the next scrub of #{result.drive} continues from here"
+        when :unmounted then @out.puts "  stopped: #{result.drive} was unmounted mid-run"
+        end
+      end
+    end
+  end
+end

data/lib/easy_sync/jbod/share_scan.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module EasySync
+  module Jbod
+    # What a share's top level holds, by the one rule `sync` uses to decide
+    # its units: each visible, non-excluded subfolder is one unit; visible,
+    # non-excluded loose files together are one more.
+    module ShareScan
+      module_function
+
+      def subfolders(path, excludes)
+        entries(path, excludes).select { |n| File.directory?(File.join(path, n)) }
+      end
+
+      def loose_files(path, excludes)
+        entries(path, excludes).select { |n| File.file?(File.join(path, n)) }
+      end
+
+      def entries(path, excludes)
+        Dir.children(path).sort.reject do |n|
+          n.start_with?('.') || Array(excludes).any? { |pat| File.fnmatch?(pat, n) }
+        end
+      end
+    end
+  end
+end

data/lib/easy_sync/jbod/sync_eta.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module EasySync
+  module Jbod
+    # Estimates time remaining for a sync run in progress, from what it has
+    # actually done so far this run: folders it copied real bytes for (their
+    # rate extrapolates to every not-yet-synced folder still queued) plus
+    # folders it merely re-verified (their average time extrapolates to every
+    # already-synced folder not yet touched this run, unless that folder has
+    # a verify of its own from an earlier run, which is used instead: a
+    # share's folders run together, so the first few verifies of a run can
+    # be one slow share's (many small files over SMB) and say nothing about
+    # thousands of single-file movie folders still to come). The two behave nothing
+    # alike - an unchanged folder verifies in under a second, a first-time
+    # folder moves real bytes over the network - so averaging them together
+    # would be meaningless; this keeps them separate instead. Shared by
+    # `status` and the dashboard so the two never drift apart.
+    class SyncEta
+      # +status+ is :waiting_for_first_folder (nothing has finished this run
+      # yet), :waiting_for_first_transfer (only verifies so far, no rate to
+      # extrapolate from), or :estimate (the only one with usable +seconds+).
+      Estimate = Struct.new(:status, :never_synced_count, :never_synced_bytes, :to_reverify, :seconds,
+                            keyword_init: true)
+
+      def self.for(manifest, started_at) = new(manifest, started_at).estimate
+
+      def initialize(manifest, started_at)
+        @manifest = manifest
+        @started_at = started_at
+      end
+
+      # nil when the run has nothing left to estimate (every folder was
+      # already touched this run as of the moment it started).
+      def estimate
+        since = @started_at.utc.iso8601
+        runs = @manifest.sync_runs_since(since)
+        return Estimate.new(status: :waiting_for_first_folder) if runs.empty?
+
+        transfers, verifies = runs.partition { |r| r.bytes_transferred.to_i.positive? }
+        transfer_seconds = duration_of(transfers)
+        transfer_rate = transfer_seconds.positive? ? transfers.sum { |r| r.bytes_transferred.to_i } / transfer_seconds : nil
+        avg_verify_seconds = verifies.empty? ? duration_of(runs) / runs.size : duration_of(verifies) / verifies.size
+
+        folders = @manifest.folders
+        never_synced = folders.select { |f| f.last_synced_at.nil? }
+        reverify = folders.select { |f| f.last_synced_at && f.last_synced_at < since }
+        return nil if never_synced.empty? && reverify.empty?
+
+        if never_synced.any? && transfer_rate.nil?
+          return Estimate.new(status: :waiting_for_first_transfer, never_synced_count: never_synced.size,
+                              never_synced_bytes: never_synced.sum { |f| f.size_bytes.to_i })
+        end
+
+        transfer_part = transfer_rate ? never_synced.sum { |f| f.size_bytes.to_i } / transfer_rate : 0
+        history = @manifest.last_verify_seconds(before: since)
+        reverify_part = reverify.sum { |f| history.fetch(f.folder_path, avg_verify_seconds) }
+        Estimate.new(status: :estimate, never_synced_count: never_synced.size, to_reverify: reverify.size,
+                    seconds: transfer_part + reverify_part)
+      end
+
+      private
+
+      def duration_of(runs) = runs.sum { |r| Time.parse(r.finished_at) - Time.parse(r.started_at) }
+    end
+  end
+end

data/lib/easy_sync/jbod/tripwire.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module EasySync
+  module Jbod
+    # Decides whether a sync would overwrite too much of the backup at once:
+    # far more existing files replaced or gone on the NAS than a media library
+    # ever changes normally, which is what ransomware looks like. Pure logic
+    # over the per-folder Mirror::Check results; Runner acts on the Decision.
+    # See docs/tripwire.md.
+    class Tripwire
+      # +scope+ is 'folder' when the folder tripped on its own, 'run' when it
+      # only counts towards a run-wide trip.
+      Trip = Struct.new(:folder_path, :replaced, :missing, :files_on_drive, :samples, :scope, :accepted,
+                        keyword_init: true) do
+        def changed = replaced + missing
+      end
+
+      # +trips+ includes accepted ones (they are still recorded). +blocked+
+      # is the folder keys not to copy this run; with +run_tripped+ nothing
+      # is copied at all. +run_changed+ is the changed-file total the run
+      # threshold was compared against (accepted folders left out).
+      Decision = Struct.new(:trips, :run_tripped, :run_changed, :total_changed, keyword_init: true) do
+        def blocked = trips.reject(&:accepted).map(&:folder_path)
+        def tripped? = !blocked.empty?
+      end
+
+      attr_reader :run_files, :folder_files, :folder_ratio
+
+      def self.from_settings(settings)
+        new(run_files: settings.fetch(:tripwire_run_files, 500), folder_files: settings.fetch(:tripwire_folder_files, 50),
+            folder_ratio: settings.fetch(:tripwire_folder_ratio, 0.25))
+      end
+
+      def initialize(run_files:, folder_files:, folder_ratio:)
+        @run_files = run_files.to_i
+        @folder_files = folder_files.to_i
+        @folder_ratio = folder_ratio.to_f
+      end
+
+      # 0 turns the tripwire off entirely: nothing ever trips.
+      def enabled? = run_files.positive?
+
+      # +checks+ maps folder key => Mirror::Check. +accept+ is true (accept
+      # every trip this run), an array of folder keys, or nil.
+      def decide(checks, accept: nil)
+        accepted = ->(key) { accept == true || Array(accept).include?(key) }
+        total = checks.sum { |_, c| c.changed }
+        run_changed = checks.sum { |key, c| accepted.call(key) ? 0 : c.changed }
+        return Decision.new(trips: [], run_tripped: false, run_changed: run_changed, total_changed: total) unless enabled?
+
+        # Accepting everything still records the trip it let through.
+        run_trip = run_changed >= run_files || (accept == true && total >= run_files)
+        trips = checks.filter_map do |key, check|
+          alone = folder_trips?(check)
+          next unless alone || (run_trip && check.changed.positive?)
+
+          trip(key, check, scope: alone ? 'folder' : 'run', accepted: accepted.call(key))
+        end
+        Decision.new(trips: trips, run_tripped: run_changed >= run_files, run_changed: run_changed, total_changed: total)
+      end
+
+      # Both halves: enough files that it isn't a 3-file folder with one
+      # re-tag, and a big enough share that it isn't routine churn in a
+      # huge one.
+      def folder_trips?(check)
+        changed = check.changed
+        return false if changed < folder_files || changed.zero?
+
+        changed.fdiv([check.files_on_drive, changed].max) >= folder_ratio
+      end
+
+      private
+
+      def trip(key, check, scope:, accepted:)
+        Trip.new(folder_path: key, replaced: check.replaced.size, missing: check.missing_files.size,
+                 files_on_drive: check.files_on_drive, samples: check.samples, scope: scope, accepted: accepted)
+      end
+    end
+  end
+end