textus 0.47.1 → 0.49.0

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

data/lib/textus/manifest/rules.rb

@@ -1,8 +1,8 @@
 module Textus
   class Manifest
     class Rules
-      RuleSet = ::Data.define(:fetch, :handler_allowlist, :guard, :retention)
-      EMPTY_SET = RuleSet.new(fetch: nil, handler_allowlist: nil, guard: nil, retention: nil)
+      RuleSet = ::Data.define(:handler_allowlist, :guard, :lifecycle)
+      EMPTY_SET = RuleSet.new(handler_allowlist: nil, guard: nil, lifecycle: nil)
 
       def self.parse(raw)
         new(Array(raw).map { |b| Block.new(b) })
@@ -15,17 +15,16 @@ module Textus
       attr_reader :blocks
 
       def for(key)
-        slots = { fetch: [], handler_allowlist: [], guard: [], retention: [] }
+        slots = { handler_allowlist: [], guard: [], lifecycle: [] }
         @blocks.each do |b|
           next unless Textus::Domain::Policy::Matcher.matches?(b.match, key)
 
           slots.each_key { |slot| slots[slot] << b if b.public_send(slot) }
         end
         RuleSet.new(
-          fetch: pick(slots[:fetch], :fetch, key),
           handler_allowlist: pick(slots[:handler_allowlist], :handler_allowlist, key),
           guard: pick(slots[:guard], :guard, key),
-          retention: pick(slots[:retention], :retention, key),
+          lifecycle: pick(slots[:lifecycle], :lifecycle, key),
         )
       end
 
@@ -44,29 +43,17 @@ module Textus
       end
 
       class Block
-        attr_reader :match, :fetch, :handler_allowlist, :guard, :retention
+        attr_reader :match, :handler_allowlist, :guard, :lifecycle
 
         def initialize(raw)
           @match = raw["match"] or raise Textus::UsageError.new("rule block missing match:")
-          @fetch = parse_fetch(raw["fetch"])
           @handler_allowlist = parse_handler_allowlist(raw["intake_handler_allowlist"])
           @guard = parse_guard(raw["guard"])
-          @retention = parse_retention(raw["retention"])
+          @lifecycle = parse_lifecycle(raw["lifecycle"])
         end
 
         private
 
-        def parse_fetch(h)
-          return nil if h.nil?
-
-          Textus::Domain::Policy::Fetch.new(
-            ttl: h["ttl"],
-            on_stale: h["on_stale"] || "warn",
-            sync_budget_ms: h["sync_budget_ms"],
-            fetch_timeout_seconds: h["fetch_timeout_seconds"],
-          )
-        end
-
         def parse_handler_allowlist(arr)
           return nil if arr.nil?
 
@@ -83,12 +70,13 @@ module Textus
           h
         end
 
-        def parse_retention(h)
+        def parse_lifecycle(h)
           return nil if h.nil?
 
-          Textus::Domain::Policy::Retention.new(
-            expire_after: h["expire_after"],
-            archive_after: h["archive_after"],
+          Textus::Domain::Policy::Lifecycle.new(
+            ttl: h["ttl"],
+            on_expire: h["on_expire"],
+            budget_ms: h["budget_ms"],
           )
         end
       end

data/lib/textus/manifest/schema.rb

@@ -32,10 +32,8 @@ module Textus
       PUBLISH_KEYS = %w[to tree].freeze
       COMPUTE_KEYS = %w[kind select pluck sort_by limit transform command sources].freeze
       INTAKE_KEYS  = %w[handler config].freeze
-      RULE_KEYS    = %w[match fetch intake_handler_allowlist guard retention].freeze
-      FETCH_KEYS = %w[ttl on_stale sync_budget_ms fetch_timeout_seconds].freeze
-      FETCH_TIMEOUT_SECONDS_CEILING = 3600
-      RETENTION_KEYS = %w[expire_after archive_after].freeze
+      RULE_KEYS    = %w[match intake_handler_allowlist guard lifecycle].freeze
+      LIFECYCLE_KEYS = %w[ttl on_expire budget_ms].freeze
       AUDIT_KEYS = %w[max_size keep].freeze
 
       # Syntactic shape of an `owner:` subject token (the `patrick` in
@@ -136,11 +134,7 @@ module Textus
         Array(rules).each_with_index do |r, i|
           path = "$.rules[#{i}]"
           walk(r, RULE_KEYS, path)
-          if r["fetch"].is_a?(Hash)
-            walk(r["fetch"], FETCH_KEYS, "#{path}.fetch")
-            validate_fetch_timeout!(r["fetch"]["fetch_timeout_seconds"], "#{path}.fetch.fetch_timeout_seconds")
-          end
-          walk(r["retention"], RETENTION_KEYS, "#{path}.retention") if r["retention"].is_a?(Hash)
+          walk(r["lifecycle"], LIFECYCLE_KEYS, "#{path}.lifecycle") if r["lifecycle"].is_a?(Hash)
         end
       end
 
@@ -217,15 +211,6 @@ module Textus
         OWNER_SUBJECT_PATTERN.match?(subject)
       end
 
-      def self.validate_fetch_timeout!(value, path)
-        return if value.nil?
-        return if value.is_a?(Integer) && value.positive? && value <= FETCH_TIMEOUT_SECONDS_CEILING
-
-        raise BadManifest.new(
-          "fetch_timeout_seconds at '#{path}' must be a positive integer ≤ #{FETCH_TIMEOUT_SECONDS_CEILING} (got #{value.inspect})",
-        )
-      end
-
       def self.walk(hash, allowed, path)
         return unless hash.is_a?(Hash)
 

data/lib/textus/ports/audit_log.rb

@@ -23,7 +23,7 @@ module Textus
           parsed = parse_row(line.chomp)
           next unless parsed
           next unless parsed["key"] == key
-          next unless %w[put delete].include?(parsed["verb"])
+          next unless %w[put delete key_delete].include?(parsed["verb"])
 
           last_role = parsed["role"]
         end

data/lib/textus/ports/audit_subscriber.rb

@@ -10,7 +10,7 @@ module Textus
     # rescue and the failure is a bus-internal concern, not a domain
     # event subscribers should be able to filter by key glob).
     #
-    # Lifecycle audit rows for verb: "put" / "delete" / "rename" are written
+    # Lifecycle audit rows for verb: "put" / "key_delete" / "key_mv" are written
     # by Envelope::IO::Writer directly (it owns the
     # audit-append-as-final-step invariant); this subscriber covers the
     # hook-failure case the writer never sees.

data/lib/textus/ports/fetch/detached.rb

@@ -31,7 +31,11 @@ module Textus
               # exists). Config-time detection is doctor's job (ADR 0044 Q2).
               role = acting_role(store)
               exit(0) unless role
-              store.as(role).fetch(key)
+              # FetchWorker is the internal executor since the public `fetch`
+              # verb was collapsed (ADR 0079); drive it directly.
+              Textus::Write::FetchWorker.new(
+                container: store.container, call: Textus::Call.build(role: role),
+              ).run(key)
             rescue StandardError
               # Already logged via :fetch_failed; exit cleanly.
             ensure

data/lib/textus/read/freshness.rb

@@ -2,10 +2,10 @@ require "time"
 
 module Textus
   module Read
-    # Per-entry freshness report. Walks every entry declared in the manifest,
-    # consults `rules_for(key)` for a fetch rule, and reports the
-    # current status. Status is one of :fresh, :stale, :never_fetched, or
-    # :no_policy.
+    # Per-entry lifecycle report (ADR 0079). Walks every entry declared in the
+    # manifest, consults `rules.for(key)` for a `lifecycle:` policy, and reports
+    # the unified verdict. Status is one of :fresh, :expired, or :no_policy; the
+    # row also carries the policy's :action (on_expire).
     class Freshness
       extend Textus::Contract::DSL
 
@@ -17,13 +17,11 @@ module Textus
       arg :zone,   String, required: false, description: "filter to entries in this zone"
       view(:cli) { |rows| { "verb" => "freshness", "rows" => rows } }
 
-      def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator)
+      def initialize(container:, call:)
         @container  = container
         @call       = call
         @manifest   = container.manifest
         @file_store = container.file_store
-        @evaluator  = evaluator
-        @cache      = {}
       end
 
       # Returns the soonest `next_due_at` across all entries with a fetch
@@ -52,29 +50,38 @@ module Textus
       private
 
       def row_for(mentry)
-        set = @manifest.rules.for(mentry.key)
-        fetch = set.fetch
+        policy = lifecycle_for(mentry.key)
         envelope = safe_get(mentry.key)
         last = envelope&.meta&.dig("last_fetched_at")
 
-        return base_row(mentry, last).merge(status: :no_policy) if fetch.nil?
-
-        fp = fetch.to_freshness_policy
-        cache_key = [mentry.key, last]
-        verdict = (@cache[cache_key] ||= @evaluator.call(fp, envelope, now: @call.now))
-        status = if verdict.fresh? then :fresh
-                 elsif last.nil?   then :never_fetched
-                 else                   :stale
-                 end
+        return base_row(mentry, last).merge(status: :no_policy) if policy.nil?
 
+        expired, reason = Textus::Domain::Lifecycle.verdict(
+          policy: policy,
+          last_fetched_at: last,
+          mtime: mtime_for(mentry.key),
+          now: @call.now,
+        )
         base_row(mentry, last).merge(
-          ttl_seconds: fp.ttl_seconds,
-          on_stale: fp.on_stale,
-          status: status,
-          next_due_at: next_due(last, fp.ttl_seconds),
+          ttl_seconds: policy.ttl_seconds,
+          action: policy.on_expire,
+          status: expired ? :expired : :fresh,
+          reason: reason,
+          next_due_at: next_due(last, policy.ttl_seconds),
         )
       end
 
+      def lifecycle_for(key)
+        @manifest.rules.for(key).lifecycle
+      end
+
+      def mtime_for(key)
+        path = @manifest.resolver.resolve(key).path
+        @file_store.exists?(path) ? Textus::Ports::Storage::FileStat.new.mtime(path) : nil
+      rescue Textus::Error
+        nil
+      end
+
       def base_row(mentry, last)
         {
           key: mentry.key,