textus 0.47.1 → 0.50.0

data/lib/textus/boot.rb

@@ -71,49 +71,50 @@ module Textus
       },
     }.freeze
 
-    # Curated agent-facing verb catalog. For verbs that have a Dispatcher contract,
-    # the summary is derived from `contract.summary` at load time (ADR 0039). The
-    # editorial strings below are the fallback for CLI-only verbs without contracts.
-    # CLI_VERBS itself is assigned in textus.rb after Zeitwerk eager_load so that
-    # all contract-declaring files are loaded before derivation runs.
+    # Curated agent-facing verb catalog. This declares which verbs the operator
+    # CLI surfaces and in what order — the editorial presentation. The summary of
+    # each verb is a fact, not presentation: it is derived from `contract.summary`
+    # at load time (ADR 0039). A literal "summary" survives here only for grouped
+    # CLI tokens (schema/key/rule/hook) that aggregate several sub-contracts and so
+    # have no single contract to derive from. CLI_VERBS itself is assigned in
+    # textus.rb after Zeitwerk eager_load so all contract files are present.
     CURATED_CLI_VERBS = [
       { "name" => "boot" },
       { "name" => "list" },
       { "name" => "get" },
-      { "name" => "where", "summary" => "resolve a key to its zone and path without reading" },
+      { "name" => "where" },
       { "name" => "schema", "summary" => "schema operations: 'schema show KEY', 'schema diff', 'schema init', 'schema migrate'" },
       { "name" => "put" },
       { "name" => "propose" },
-      { "name" => "accept",   "summary" => "apply a queued proposal to its target zone; requires the author capability" },
-      { "name" => "key",      "summary" => "key operations: 'key delete', 'key mv', 'key uid'" },
-      { "name" => "build",    "summary" => "materialize derived entries; publish_to and publish_tree fan out copies" },
-      { "name" => "fetch" },
-      { "name" => "freshness", "summary" => "per-entry freshness report (status, age, ttl, on_stale)" },
-      { "name" => "audit",    "summary" => "query .textus/audit.log with filters (key, role, since, correlation-id, ...)" },
-      { "name" => "blame",    "summary" => "audit rows for one key joined with git commit metadata" },
-      { "name" => "rule",     "summary" => "inspect effective rules: 'rule list', 'rule explain KEY'" },
-      { "name" => "doctor",   "summary" => "health-check the store (missing schemas, illegal keys, sentinel drift, etc.)" },
-      { "name" => "hook",     "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
+      { "name" => "accept" },
+      { "name" => "key", "summary" => "key operations: 'key delete', 'key mv', 'key uid'" },
+      { "name" => "build" },
+      { "name" => "tend" },
+      { "name" => "audit" },
+      { "name" => "blame" },
+      { "name" => "rule", "summary" => "inspect effective rules: 'rule list', 'rule explain KEY'" },
+      { "name" => "doctor" },
+      { "name" => "hook", "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
       { "name" => "pulse" },
       { "name" => "capabilities" },
     ].freeze
 
-    # Build the CLI verb catalog by deriving each summary from the corresponding
-    # Dispatcher contract when one exists, falling back to the editorial string for
-    # CLI-only verbs without a contract (e.g. accept, build, where). Called once
-    # from textus.rb after eager_load so all contract files are present.
-    def self.build_cli_verbs
-      by_contract = Dispatcher::VERBS.values
-                                     .select { |k| k.respond_to?(:contract?) && k.contract? }
-                                     .to_h { |k| [k.contract.verb.to_s, k.contract.summary] }
+    # verb token => contract.summary, for every Dispatcher verb that carries a
+    # contract. The single source for a verb's one-line summary (ADR 0039).
+    def self.contract_summaries
+      Dispatcher::VERBS.values
+                       .select { |k| k.respond_to?(:contract?) && k.contract? }
+                       .to_h { |k| [k.contract.verb.to_s, k.contract.summary] }
+    end
 
+    # Build the CLI verb catalog: each summary is derived from its contract when
+    # one exists, falling back to the curated editorial string for grouped tokens
+    # (schema/key/rule/hook). Called once from textus.rb after eager_load.
+    def self.build_cli_verbs
+      summaries = contract_summaries
       CURATED_CLI_VERBS.map do |entry|
-        derived = by_contract[entry["name"]]
-        if derived
-          entry.merge("summary" => derived)
-        else
-          entry
-        end
+        derived = summaries[entry["name"]]
+        derived ? entry.merge("summary" => derived) : entry
       end
     end
 
@@ -130,7 +131,8 @@ module Textus
         # Both verb lists derive from the MCP catalog (ADR 0056, ADR 0057): the
         # agent's real read and write surface, named as verbs the agent calls —
         # not CLI strings. read_verbs can neither advertise a verb the agent
-        # cannot call (audit/freshness/doctor are CLI-only) nor omit one it can
+        # cannot call (audit/doctor are CLI-only; freshness is a Ruby-only
+        # internal scan, ADR 0085) nor omit one it can
         # (schema_show/rules); write_verbs drops the old `put KEY --as=… --stdin` CLI
         # framing (role is connection-resolved over MCP; there is no stdin).
         # writable_zones / propose_zone below carry the agent's write authority.
@@ -196,8 +198,20 @@ module Textus
       )
     end
 
-    def self.build(container:)
+    def self.build(container:, lean: false)
       manifest = container.manifest
+      etag = Textus::Etag.for_contract(container.root)
+
+      if lean
+        return {
+          "protocol" => PROTOCOL_ID,
+          "store_root" => container.root,
+          "zones" => zones_for(manifest),
+          "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
+          "contract_etag" => etag,
+        }
+      end
+
       {
         "protocol" => PROTOCOL_ID,
         "store_root" => container.root,
@@ -208,6 +222,7 @@ module Textus
         "cli_verbs" => CLI_VERBS.map(&:dup),
         "agent_protocol" => agent_protocol(manifest),
         "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
+        "contract_etag" => etag,
         "docs" => { "spec" => "SPEC.md", "example" => "examples/project/" },
       }
     end

data/lib/textus/builder/renderer/json.rb

@@ -6,7 +6,7 @@ module Textus
       class Json < Renderer
         def call(mentry:, data:)
           content = mentry.template ? parse_rendered_template!(mentry, data) : default_shape(mentry, data)
-          final = InjectMeta.call(content, mentry)
+          final = mentry.provenance ? InjectMeta.call(content, mentry) : content
           Entry.for_format("json").serialize(meta: {}, body: "", content: final)
         end
 

data/lib/textus/cli/runner.rb

@@ -137,10 +137,11 @@ module Textus
       BEHAVIORAL_HATCHES = %i[get put build].freeze
 
       # Contract verbs whose CLI is a plain `< Verb` command, not a projection at
-      # all — worker verbs and composite reports assembled outside the contract:
-      #   fetch, fetch_all — background intake workers (not request/response)
-      #   boot, doctor     — composite reports
-      NON_PROJECTED_CLI = %i[fetch fetch_all boot doctor].freeze
+      # all — composite reports assembled outside the contract:
+      #   boot, doctor — composite reports
+      # (fetch/fetch_all were removed in ADR 0079: FetchWorker is now internal,
+      # driven by get's read-through orchestrator and the tend sweep.)
+      NON_PROJECTED_CLI = %i[boot doctor].freeze
 
       # The installer skips generation for either category.
       HAND_AUTHORED_VERBS = (BEHAVIORAL_HATCHES + NON_PROJECTED_CLI).freeze

data/lib/textus/cli/verb/boot.rb

@@ -3,9 +3,10 @@ module Textus
     class Verb
       class Boot < Verb
         command_name "boot"
+        option :lean, "--lean"
 
         def call(store)
-          emit(store.boot)
+          emit(store.boot(lean: !!lean))
         end
       end
     end

data/lib/textus/cli.rb

@@ -123,7 +123,6 @@ module Textus
           textus where KEY
           textus get KEY
           textus put KEY --stdin [--fetch=NAME] --as=ROLE
-          textus freshness [--prefix=KEY] [--zone=Z]
           textus fetch KEY
           textus fetch all [--prefix=KEY] [--zone=Z]
           textus audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]

data/lib/textus/dispatcher.rb

@@ -7,14 +7,11 @@ module Textus
       # Write
       put: Textus::Write::Put,
       propose: Textus::Write::Propose,
-      delete: Textus::Write::Delete,
-      mv: Textus::Write::Mv,
+      key_delete: Textus::Write::KeyDelete,
+      key_mv: Textus::Write::KeyMv,
       accept: Textus::Write::Accept,
       reject: Textus::Write::Reject,
       build: Textus::Write::Build,
-      fetch: Textus::Write::FetchWorker,
-      fetch_all: Textus::Write::FetchAll,
-      retain: Textus::Write::RetentionSweep,
 
       # Read
       get: Textus::Read::Get,
@@ -24,7 +21,6 @@ module Textus
       blame: Textus::Read::Blame,
       audit: Textus::Read::Audit,
       freshness: Textus::Read::Freshness,
-      stale: Textus::Read::Stale,
       deps: Textus::Read::Deps,
       rdeps: Textus::Read::Rdeps,
       pulse: Textus::Read::Pulse,
@@ -35,14 +31,13 @@ module Textus
       validate_all: Textus::Read::ValidateAll,
       doctor: Textus::Read::Doctor,
       boot: Textus::Read::Boot,
-      retainable: Textus::Read::Retainable,
       capabilities: Textus::Read::Capabilities,
 
       # Maintenance
-      migrate: Textus::Maintenance::Migrate,
       zone_mv: Textus::Maintenance::ZoneMv,
       key_mv_prefix: Textus::Maintenance::KeyMvPrefix,
       key_delete_prefix: Textus::Maintenance::KeyDeletePrefix,
+      tend: Textus::Maintenance::Tend,
       rule_lint: Textus::Maintenance::RuleLint,
     }.freeze
 

data/lib/textus/doctor/check/generator_drift.rb

@@ -0,0 +1,28 @@
+module Textus
+  module Doctor
+    class Check
+      # ADR 0079: generator/build drift — a derived/external entry whose sources
+      # changed since its generated.at. Dependency-based (not age-based), so it
+      # stays OUT of the lifecycle/freshness unification and lives here as a
+      # health signal. This is the surviving home for what the removed `stale`
+      # verb reported.
+      class GeneratorDrift < Check
+        def call
+          gen = Textus::Domain::Staleness::GeneratorCheck.new(
+            manifest: manifest,
+            file_stat: Textus::Ports::Storage::FileStat.new,
+          )
+          manifest.data.entries.flat_map { |m| gen.rows_for(m) }.map do |row|
+            {
+              "code" => "generator_drift",
+              "level" => "warning",
+              "subject" => row["key"],
+              "message" => row["reason"],
+              "fix" => "rebuild the entry: `textus build`",
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/lifecycle_action_invalid.rb

@@ -0,0 +1,39 @@
+module Textus
+  module Doctor
+    class Check
+      # ADR 0079: refresh is valid only for intake entries; drop/archive are
+      # invalid for intake entries (they would re-fetch, not prune).
+      class LifecycleActionInvalid < Check
+        def call
+          manifest.data.entries.filter_map do |mentry|
+            policy = manifest.rules.for(mentry.key).lifecycle
+            next if policy.nil?
+
+            intake = mentry.is_a?(Textus::Manifest::Entry::Intake)
+            bad = (policy.on_expire == :refresh && !intake) || (policy.destructive? && intake)
+            next unless bad
+
+            issue_for(mentry, policy, intake)
+          end
+        end
+
+        private
+
+        def issue_for(mentry, policy, intake)
+          {
+            "code" => "lifecycle.action_invalid",
+            "level" => "error",
+            "subject" => mentry.key,
+            "message" => "on_expire: #{policy.on_expire} is not valid for a " \
+                         "#{intake ? "intake" : "stored"} entry",
+            "fix" => if intake
+                       "use on_expire: refresh|warn for intake entries"
+                     else
+                       "use on_expire: drop|archive|warn for stored entries"
+                     end,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/rule_ambiguity.rb

@@ -6,7 +6,7 @@ module Textus
       # guard). Ties are non-deterministic in the parser's pick step, so
       # they're a configuration smell — surface them.
       class RuleAmbiguity < Check
-        SLOTS = %i[fetch handler_allowlist guard].freeze
+        SLOTS = %i[lifecycle handler_allowlist guard].freeze
 
         def call
           out = []

data/lib/textus/doctor.rb

@@ -27,6 +27,8 @@ module Textus
       Check::OrphanedPublishTargets,
       Check::PublishTreeIndexOverlap,
       Check::ProposalTargets,
+      Check::LifecycleActionInvalid,
+      Check::GeneratorDrift,
     ].freeze
 
     ALL_CHECKS = CHECKS.map(&:name_key).freeze

data/lib/textus/domain/lifecycle.rb

@@ -0,0 +1,83 @@
+require "time"
+
+module Textus
+  module Domain
+    # Unified lifecycle reporter (ADR 0079): which entries are past their ttl,
+    # and the on_expire action that applies. Replaces both Staleness::IntakeCheck
+    # and Retention. Age basis: _meta.last_fetched_at (intake) when present, else
+    # file mtime (stored). `self.verdict` is the pure per-entry decision that BOTH
+    # this reporter and `Read::Get` (Plan 2) call, so the basis logic lives once.
+    class Lifecycle
+      # Pure: is the entry past its ttl? -> [expired(bool), reason(String|nil)].
+      def self.verdict(policy:, last_fetched_at:, mtime:, now:)
+        ttl = policy.ttl_seconds
+        return [false, nil] if ttl.nil?
+
+        basis = parse_time(last_fetched_at) || mtime
+        return [true, "never recorded"] if basis.nil?
+
+        age = (now - basis).to_i
+        age > ttl ? [true, "ttl exceeded (age=#{age}s, ttl=#{ttl}s)"] : [false, nil]
+      end
+
+      def self.parse_time(str)
+        return nil if str.nil?
+
+        Time.parse(str.to_s)
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def initialize(manifest:, file_stat:, clock:)
+        @manifest  = manifest
+        @file_stat = file_stat
+        @clock     = clock
+      end
+
+      def call(prefix: nil, zone: nil)
+        @manifest.data.entries
+                 .select { |m| entry_matches?(m, prefix: prefix, zone: zone) }
+                 .flat_map { |m| rows_for(m) }
+      end
+
+      private
+
+      def entry_matches?(mentry, prefix:, zone:)
+        return false if zone && mentry.zone != zone
+        return false if prefix && !(mentry.key == prefix || mentry.key.start_with?("#{prefix}."))
+
+        true
+      end
+
+      def rows_for(mentry)
+        policy = @manifest.rules.for(mentry.key).lifecycle
+        return [] if policy.nil?
+
+        @manifest.resolver.enumerate(prefix: mentry.key).filter_map do |row|
+          path = row[:path]
+          next unless @file_stat.exists?(path)
+
+          expired, _reason = self.class.verdict(
+            policy: policy,
+            last_fetched_at: last_fetched_at_of(mentry, path),
+            mtime: @file_stat.mtime(path),
+            now: @clock.now,
+          )
+          next unless expired
+
+          {
+            "key" => row[:key], "path" => path,
+            "action" => policy.on_expire.to_s, "expired" => true
+          }
+        end
+      end
+
+      # Reads _meta.last_fetched_at from the on-disk envelope (intake basis).
+      def last_fetched_at_of(mentry, path)
+        Entry.for_format(mentry.format).parse(@file_stat.read(path), path: path)["_meta"]["last_fetched_at"]
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/base_guards.rb

@@ -11,8 +11,8 @@ module Textus
         # composable-only, added per-key via rules[].guard (ADR 0031).
         BASE = {
           put: %w[zone_writable_by],
-          delete: %w[zone_writable_by],
-          mv: %w[zone_writable_by],
+          key_delete: %w[zone_writable_by],
+          key_mv: %w[zone_writable_by],
           accept: %w[author_held target_is_canon],
           reject: %w[author_held],
           fetch: %w[zone_writable_by],

data/lib/textus/domain/policy/lifecycle.rb

@@ -0,0 +1,35 @@
+module Textus
+  module Domain
+    module Policy
+      # Unified per-entry lifecycle policy (ADR 0079): one ttl + one action.
+      # Replaces the separate Fetch (ttl/on_stale) and Retention
+      # (expire_after/archive_after) policies. The action's destructiveness
+      # decides WHERE it runs: lazy actions (refresh/warn) on get/list reads;
+      # destructive actions (drop/archive) only on the tend sweep.
+      class Lifecycle
+        LAZY        = %i[refresh warn].freeze
+        DESTRUCTIVE = %i[drop archive].freeze
+        ALLOWED     = (LAZY + DESTRUCTIVE).freeze
+
+        attr_reader :on_expire, :budget_ms
+
+        def initialize(ttl:, on_expire:, budget_ms: nil)
+          action = on_expire.is_a?(Symbol) ? on_expire : on_expire.to_s.to_sym
+          unless ALLOWED.include?(action)
+            raise Textus::UsageError.new(
+              "lifecycle on_expire must be one of #{ALLOWED.join("|")}, got #{on_expire.inspect}",
+            )
+          end
+
+          @ttl       = ttl
+          @on_expire = action
+          @budget_ms = budget_ms
+        end
+
+        def ttl_seconds = Textus::Domain::Duration.seconds(@ttl)
+        def destructive? = DESTRUCTIVE.include?(@on_expire)
+        def lazy?        = LAZY.include?(@on_expire)
+      end
+    end
+  end
+end

data/lib/textus/domain/staleness.rb

@@ -1,16 +1,19 @@
 module Textus
   module Domain
     class Staleness
-      def initialize(manifest:, file_stat:, clock:)
+      # ADR 0079: intake (age-based) staleness moved to the unified lifecycle
+      # path (Domain::Lifecycle / freshness); only generator/build drift —
+      # dependency-based, surfaced by the doctor `generator_drift` check —
+      # remains here.
+      def initialize(manifest:, file_stat:, clock: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = manifest
         @generator_check = GeneratorCheck.new(manifest: manifest, file_stat: file_stat)
-        @intake_check    = IntakeCheck.new(manifest: manifest, file_stat: file_stat, clock: clock)
       end
 
       def call(prefix: nil, zone: nil)
         @manifest.data.entries
                  .select { |m| entry_matches?(m, prefix: prefix, zone: zone) }
-                 .flat_map { |m| @generator_check.rows_for(m) + @intake_check.rows_for(m) }
+                 .flat_map { |m| @generator_check.rows_for(m) }
       end
 
       private

data/lib/textus/envelope/io/writer.rb

@@ -84,7 +84,7 @@ module Textus
           @file_store.delete(path)
           prune_empty_parents(path)
           @audit_log.append(
-            role: @call.role, verb: "delete", key: key,
+            role: @call.role, verb: "key_delete", key: key,
             etag_before: etag_before, etag_after: nil,
             extras: @call.correlation_id ? { "correlation_id" => @call.correlation_id } : nil
           )
@@ -121,7 +121,7 @@ module Textus
           extras["correlation_id"] = @call.correlation_id if @call.correlation_id
 
           @audit_log.append(
-            role: @call.role, verb: "mv", key: to_key,
+            role: @call.role, verb: "key_mv", key: to_key,
             etag_before: etag_before, etag_after: etag_after,
             extras: extras
           )

data/lib/textus/hooks/context.rb

@@ -45,7 +45,7 @@ module Textus
 
       # write (authorized + audited)
       def put(key, **)          = @scope.put(key, **)
-      def delete(key, **)       = @scope.delete(key, **)
+      def delete(key, **)       = @scope.key_delete(key, **)
 
       def audit(verb, key:, **)
         @scope.container.audit_log.append(role: @role, verb: verb, key: key, **)

data/lib/textus/init.rb

@@ -41,7 +41,7 @@ module Textus
                 local: { via: local }
       rules:
         - match: feeds.machines.**
-          fetch: { ttl: 1h, on_stale: warn } # meaningful on a long-running server
+          lifecycle: { ttl: 1h, on_expire: warn } # meaningful on a long-running server
     YAML
 
     HOOKS_README = <<~MD
@@ -72,7 +72,7 @@ module Textus
       ```
 
       The intake handler above is paired with a manifest entry plus a
-      top-level `rules:` block for freshness (ttl/on_stale live in
+      top-level `rules:` block for lifecycle (ttl/on_expire live in
       rules, not in the entry):
 
       ```yaml
@@ -86,9 +86,9 @@ module Textus
 
       rules:
         - match: feeds.foo
-          fetch:
+          lifecycle:
             ttl: 10m
-            on_stale: timed_sync   # warn | sync | timed_sync (default: warn)
+            on_expire: refresh   # refresh | warn (intake); drop | archive (stored)
       ```
 
       Events: :resolve_intake, :transform_rows, :validate (rpc — return value used)

data/lib/textus/maintenance/key_delete_prefix.rb

@@ -41,7 +41,7 @@ module Textus
       private
 
       def delete
-        Write::Delete.new(container: @container, call: @call)
+        Write::KeyDelete.new(container: @container, call: @call)
       end
     end
   end

data/lib/textus/maintenance/key_mv_prefix.rb

@@ -1,7 +1,7 @@
 module Textus
   module Maintenance
     # Bulk-rename every leaf key under `from_prefix` to `to_prefix`.
-    # Calls Write::Mv directly for each entry — emits one audit row per file moved.
+    # Calls Write::KeyMv directly for each entry — emits one audit row per file moved.
     class KeyMvPrefix
       extend Textus::Contract::DSL
 
@@ -61,7 +61,7 @@ module Textus
       end
 
       def mv
-        Write::Mv.new(container: @container, call: @call)
+        Write::KeyMv.new(container: @container, call: @call)
       end
     end
   end

data/lib/textus/maintenance/tend.rb

@@ -0,0 +1,110 @@
+require "fileutils"
+
+module Textus
+  module Maintenance
+    # The destructive-only lifecycle sweep (ADR 0079, supersedes the composite
+    # 0078 body). Drives off the unified Domain::Lifecycle reporter: it applies
+    # destructive actions a read never performs (drop = delete via Write::KeyDelete;
+    # archive = copy to <store>/archive/ then delete) and refreshes cold expired
+    # intake entries (on_expire: refresh) via Write::FetchWorker. Non-destructive
+    # annotation (warn) is left to the lazy `get`/`freshness` path. Adds no new
+    # authority — every sub-op runs with the CALLER's own `call` (role), and is
+    # gated exactly as on its own.
+    class Tend
+      extend Textus::Contract::DSL
+
+      verb     :tend
+      summary  "Run the destructive lifecycle sweep: drop/archive expired entries, refresh cold intake, report health."
+      surfaces :cli, :mcp
+      cli      "tend"
+      arg :prefix,  String, description: "restrict the sweep to keys under this dotted prefix"
+      arg :zone,    String, description: "restrict the sweep to entries in this zone"
+      arg :dry_run, :boolean, default: false,
+                              description: "when true, report what the sweep WOULD do without applying; " \
+                                           "defaults to false, so omitting it drops/archives/refreshes immediately"
+
+      def initialize(container:, call:)
+        @container = container
+        @call      = call
+      end
+
+      def call(prefix: nil, zone: nil, dry_run: false)
+        rows = Textus::Domain::Lifecycle.new(
+          manifest: @container.manifest,
+          file_stat: Textus::Ports::Storage::FileStat.new,
+          clock: Textus::Ports::Clock,
+        ).call(prefix: prefix, zone: zone)
+
+        health = Read::Doctor.new(container: @container, call: @call).call
+        return dry_run_result(rows, health) if dry_run
+
+        apply_result(apply(rows), health)
+      end
+
+      private
+
+      def dry_run_result(rows, health)
+        {
+          "protocol" => Textus::PROTOCOL, "ok" => true, "dry_run" => true,
+          "would_drop" => action_keys(rows, "drop"),
+          "would_archive" => action_keys(rows, "archive"),
+          "would_refresh" => action_keys(rows, "refresh"),
+          "health" => health
+        }
+      end
+
+      def apply_result(result, health)
+        {
+          "protocol" => Textus::PROTOCOL,
+          "ok" => result[:failed].empty?,
+          "dry_run" => false,
+          "dropped" => result[:dropped], "archived" => result[:archived],
+          "refreshed" => result[:refreshed], "failed" => result[:failed],
+          "health" => health
+        }
+      end
+
+      def action_keys(rows, action)
+        rows.select { |r| r["action"] == action }.map { |r| r["key"] }
+      end
+
+      def apply(rows)
+        out = { dropped: [], archived: [], refreshed: [], failed: [] }
+        delete  = Write::KeyDelete.new(container: @container, call: @call)
+        refresh = Write::FetchWorker.new(container: @container, call: @call)
+
+        rows.each do |row|
+          key = row["key"]
+          begin
+            case row["action"]
+            when "drop"
+              delete.call(key)
+              out[:dropped] << key
+            when "archive"
+              archive_leaf(row)
+              delete.call(key)
+              out[:archived] << key
+            when "refresh"
+              refresh.run(key)
+              out[:refreshed] << key
+            end
+          rescue Textus::Error => e
+            out[:failed] << { "key" => key, "error" => e.message }
+          end
+        end
+        out
+      end
+
+      # Copy the leaf into <store>/archive/<relative-path> before deletion.
+      # (Lifted from the retired RetentionSweep#archive_leaf.)
+      def archive_leaf(row)
+        src  = row["path"]
+        root = @container.root.to_s
+        rel  = src.delete_prefix("#{root}/")
+        dest = File.join(root, "archive", rel)
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(src, dest)
+      end
+    end
+  end
+end