textus 0.47.1 → 0.50.0

data/lib/textus/write/{mv.rb → key_mv.rb}

@@ -1,9 +1,9 @@
 module Textus
   module Write
-    class Mv
+    class KeyMv
       extend Textus::Contract::DSL
 
-      verb     :mv
+      verb     :key_mv
       summary  "Rename one entry (same zone + format). Refuses if the target exists. Single-key, lower blast radius than key_mv_prefix."
       surfaces :cli, :mcp
       cli      "key mv"
@@ -53,8 +53,8 @@ module Textus
         raise UnknownKey.new(old_key) unless reader.exists?(old_key)
 
         validate_zone_and_format!(old_res.entry, new_res.entry)
-        guard_for(:mv, old_key).check!(eval_for(:mv, target_key: old_key))
-        guard_for(:mv, new_key).check!(eval_for(:mv, target_key: new_key))
+        guard_for(:key_mv, old_key).check!(eval_for(:key_mv, target_key: old_key))
+        guard_for(:key_mv, new_key).check!(eval_for(:key_mv, target_key: new_key))
         raise UsageError.new("mv: target '#{new_key}' already exists at #{new_res.path}") if reader.exists?(new_key)
 
         [old_res, new_res]

data/lib/textus/write/reject.rb

@@ -59,7 +59,7 @@ module Textus
       end
 
       def delete_op
-        @delete_op ||= Textus::Write::Delete.new(
+        @delete_op ||= Textus::Write::KeyDelete.new(
           container: @container, call: @call,
         )
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.47.1
+  version: 0.50.0
 platform: ruby
 authors:
 - Patrick
@@ -120,7 +120,6 @@ files:
 - lib/textus/call.rb
 - lib/textus/cli.rb
 - lib/textus/cli/group.rb
-- lib/textus/cli/group/fetch.rb
 - lib/textus/cli/group/hook.rb
 - lib/textus/cli/group/key.rb
 - lib/textus/cli/group/mcp.rb
@@ -132,8 +131,6 @@ files:
 - lib/textus/cli/verb/boot.rb
 - lib/textus/cli/verb/build.rb
 - lib/textus/cli/verb/doctor.rb
-- lib/textus/cli/verb/fetch.rb
-- lib/textus/cli/verb/fetch_all.rb
 - lib/textus/cli/verb/get.rb
 - lib/textus/cli/verb/hook_run.rb
 - lib/textus/cli/verb/hooks.rb
@@ -157,10 +154,12 @@ files:
 - lib/textus/doctor/check.rb
 - lib/textus/doctor/check/audit_log.rb
 - lib/textus/doctor/check/fetch_locks.rb
+- lib/textus/doctor/check/generator_drift.rb
 - lib/textus/doctor/check/handler_allowlist.rb
 - lib/textus/doctor/check/hooks.rb
 - lib/textus/doctor/check/illegal_keys.rb
 - lib/textus/doctor/check/intake_registration.rb
+- lib/textus/doctor/check/lifecycle_action_invalid.rb
 - lib/textus/doctor/check/manifest_files.rb
 - lib/textus/doctor/check/orphaned_publish_targets.rb
 - lib/textus/doctor/check/proposal_targets.rb
@@ -179,14 +178,15 @@ files:
 - lib/textus/domain/freshness/evaluator.rb
 - lib/textus/domain/freshness/policy.rb
 - lib/textus/domain/freshness/verdict.rb
+- lib/textus/domain/lifecycle.rb
 - lib/textus/domain/outcome.rb
 - lib/textus/domain/permission.rb
 - lib/textus/domain/policy/base_guards.rb
 - lib/textus/domain/policy/evaluation.rb
-- lib/textus/domain/policy/fetch.rb
 - lib/textus/domain/policy/guard.rb
 - lib/textus/domain/policy/guard_factory.rb
 - lib/textus/domain/policy/handler_allowlist.rb
+- lib/textus/domain/policy/lifecycle.rb
 - lib/textus/domain/policy/matcher.rb
 - lib/textus/domain/policy/predicates/author_held.rb
 - lib/textus/domain/policy/predicates/etag_match.rb
@@ -195,12 +195,9 @@ files:
 - lib/textus/domain/policy/predicates/schema_valid.rb
 - lib/textus/domain/policy/predicates/target_is_canon.rb
 - lib/textus/domain/policy/predicates/zone_writable_by.rb
-- lib/textus/domain/policy/retention.rb
-- lib/textus/domain/retention.rb
 - lib/textus/domain/sentinel.rb
 - lib/textus/domain/staleness.rb
 - lib/textus/domain/staleness/generator_check.rb
-- lib/textus/domain/staleness/intake_check.rb
 - lib/textus/entry.rb
 - lib/textus/entry/base.rb
 - lib/textus/entry/json.rb
@@ -231,8 +228,8 @@ files:
 - lib/textus/maintenance.rb
 - lib/textus/maintenance/key_delete_prefix.rb
 - lib/textus/maintenance/key_mv_prefix.rb
-- lib/textus/maintenance/migrate.rb
 - lib/textus/maintenance/rule_lint.rb
+- lib/textus/maintenance/tend.rb
 - lib/textus/maintenance/zone_mv.rb
 - lib/textus/manifest.rb
 - lib/textus/manifest/capabilities.rb
@@ -293,11 +290,9 @@ files:
 - lib/textus/read/published.rb
 - lib/textus/read/pulse.rb
 - lib/textus/read/rdeps.rb
-- lib/textus/read/retainable.rb
 - lib/textus/read/rule_explain.rb
 - lib/textus/read/rule_list.rb
 - lib/textus/read/schema_envelope.rb
-- lib/textus/read/stale.rb
 - lib/textus/read/uid.rb
 - lib/textus/read/validate_all.rb
 - lib/textus/read/validator.rb
@@ -313,18 +308,16 @@ files:
 - lib/textus/version.rb
 - lib/textus/write/accept.rb
 - lib/textus/write/build.rb
-- lib/textus/write/delete.rb
-- lib/textus/write/fetch_all.rb
 - lib/textus/write/fetch_events.rb
 - lib/textus/write/fetch_orchestrator.rb
 - lib/textus/write/fetch_worker.rb
 - lib/textus/write/intake_fetch.rb
+- lib/textus/write/key_delete.rb
+- lib/textus/write/key_mv.rb
 - lib/textus/write/materializer.rb
-- lib/textus/write/mv.rb
 - lib/textus/write/propose.rb
 - lib/textus/write/put.rb
 - lib/textus/write/reject.rb
-- lib/textus/write/retention_sweep.rb
 homepage: https://github.com/patrick204nqh/textus
 licenses:
 - MIT

data/lib/textus/cli/group/fetch.rb

@@ -1,20 +0,0 @@
-module Textus
-  class CLI
-    class Group
-      class Fetch < Group
-        command_name "fetch"
-
-        def parse(argv)
-          if argv.first == "all"
-            argv.shift
-            @sub_klass = Verb::FetchAll
-          else
-            @sub_klass = Verb::Fetch
-          end
-          @sub = @sub_klass.new(stdin: @stdin, stdout: @stdout, stderr: @stderr, cwd: @cwd)
-          @sub.parse(argv)
-        end
-      end
-    end
-  end
-end

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

@@ -1,14 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class Fetch < Verb
-        option :as_flag, "--as=ROLE"
-
-        def call(store)
-          key = positional.shift or raise UsageError.new("fetch requires a key")
-          emit(session_for(store).fetch(key).to_h_for_wire)
-        end
-      end
-    end
-  end
-end

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

@@ -1,20 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class FetchAll < Verb
-        command_name "all"
-        parent_group Group::Fetch
-
-        option :prefix, "--prefix=KEY"
-        option :zone, "--zone=Z"
-        option :as_flag, "--as=ROLE"
-
-        def call(store)
-          result = session_for(store).fetch_all(prefix: prefix, zone: zone)
-          emit(result)
-          result["ok"] ? 0 : 1
-        end
-      end
-    end
-  end
-end

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

@@ -1,37 +0,0 @@
-module Textus
-  module Domain
-    module Policy
-      class Fetch
-        ALLOWED_ON_STALE = %i[warn sync timed_sync].freeze
-
-        attr_reader :ttl, :on_stale, :sync_budget_ms, :fetch_timeout_seconds
-
-        def initialize(ttl:, on_stale:, sync_budget_ms:, fetch_timeout_seconds: nil)
-          on_stale_sym = on_stale.is_a?(Symbol) ? on_stale : on_stale.to_s.to_sym
-          unless ALLOWED_ON_STALE.include?(on_stale_sym)
-            raise Textus::UsageError.new(
-              "on_stale must be one of #{ALLOWED_ON_STALE.join(", ")} (got #{on_stale.inspect})",
-            )
-          end
-
-          @ttl                   = ttl
-          @on_stale              = on_stale_sym
-          @sync_budget_ms        = sync_budget_ms
-          @fetch_timeout_seconds = fetch_timeout_seconds
-        end
-
-        def ttl_seconds
-          Textus::Domain::Duration.seconds(@ttl)
-        end
-
-        def to_freshness_policy
-          Textus::Domain::Freshness::Policy.new(
-            ttl_seconds: ttl_seconds,
-            on_stale: @on_stale,
-            sync_budget_ms: @sync_budget_ms,
-          )
-        end
-      end
-    end
-  end
-end

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

@@ -1,26 +0,0 @@
-module Textus
-  module Domain
-    module Policy
-      # Lifetime policy for queue/quarantine leaves. Both windows are optional
-      # durations (see Domain::Duration). `expire_after` deletes; `archive_after`
-      # moves the leaf aside. When both are set, expire wins once its (longer)
-      # window is exceeded.
-      class Retention
-        attr_reader :expire_after, :archive_after
-
-        def initialize(expire_after: nil, archive_after: nil)
-          @expire_after  = Textus::Domain::Duration.seconds(expire_after)
-          @archive_after = Textus::Domain::Duration.seconds(archive_after)
-        end
-
-        # :expire | :archive | nil for a leaf of the given age (seconds).
-        def action_for(age_seconds)
-          return :expire  if @expire_after  && age_seconds > @expire_after
-          return :archive if @archive_after && age_seconds > @archive_after
-
-          nil
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/retention.rb

@@ -1,44 +0,0 @@
-module Textus
-  module Domain
-    # Reports leaves whose age (now - file mtime) exceeds a retention window.
-    # Each row is { "key", "path", "action" => "expire"|"archive", "age_seconds" }.
-    class Retention
-      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 rows_for(mentry)
-        policy = @manifest.rules.for(mentry.key).retention
-        return [] if policy.nil?
-
-        @manifest.resolver.enumerate(prefix: mentry.key).filter_map do |row|
-          path = row[:path]
-          next unless @file_stat.exists?(path)
-
-          age = (@clock.now - @file_stat.mtime(path)).to_i
-          action = policy.action_for(age)
-          next if action.nil?
-
-          { "key" => row[:key], "path" => path, "action" => action.to_s, "age_seconds" => age }
-        end
-      end
-
-      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
-    end
-  end
-end

data/lib/textus/domain/staleness/intake_check.rb

@@ -1,54 +0,0 @@
-require "time"
-
-module Textus
-  module Domain
-    class Staleness
-      # Reports TTL-exceeded staleness for intake-handler entries. Returns an
-      # Array of row hashes (possibly empty) per entry.
-      class IntakeCheck
-        def initialize(manifest:, file_stat:, clock:)
-          @manifest  = manifest
-          @file_stat = file_stat
-          @clock     = clock
-        end
-
-        def rows_for(mentry)
-          return [] unless mentry.is_a?(Textus::Manifest::Entry::Intake)
-
-          ttl = @manifest.rules.for(mentry.key).fetch&.ttl_seconds
-          return [] unless ttl
-
-          path = Textus::Key::Path.resolve(@manifest.data, mentry)
-          reason = ttl_reason(mentry, path, ttl)
-          reason ? [row(mentry, path, reason)] : []
-        end
-
-        private
-
-        def ttl_reason(mentry, path, ttl)
-          return "never fetched" unless @file_stat.exists?(path)
-
-          last_str = last_fetched_of(mentry, path)
-          return "never fetched (no last_fetched_at)" if last_str.nil?
-
-          last = parse_time(last_str)
-          "ttl exceeded (#{ttl}s)" if last.nil? || (@clock.now - last) > ttl
-        end
-
-        def last_fetched_of(mentry, path)
-          Entry.for_format(mentry.format).parse(@file_stat.read(path), path: path)["_meta"]["last_fetched_at"]
-        end
-
-        def parse_time(str)
-          Time.parse(str.to_s)
-        rescue StandardError
-          nil
-        end
-
-        def row(mentry, path, reason)
-          { "key" => mentry.key, "path" => path, "handler" => mentry.handler, "reason" => reason }
-        end
-      end
-    end
-  end
-end

data/lib/textus/maintenance/migrate.rb

@@ -1,65 +0,0 @@
-require "yaml"
-
-module Textus
-  module Maintenance
-    # Loads a YAML migration plan and dispatches each op to the
-    # appropriate Maintenance use case. Concatenates resulting Plans.
-    class Migrate
-      extend Textus::Contract::DSL
-
-      verb     :migrate
-      summary  "Run a YAML migration plan (multi-op)."
-      surfaces :cli, :mcp
-      arg :plan_yaml, String, required: true, positional: true, source: :file,
-                              description: "path to the YAML migration plan (zone_mv, key_mv_prefix, key_delete_prefix ops run in order)"
-      arg :dry_run, :boolean, default: false,
-                              description: "when true, returns the planned ops without applying them; " \
-                                           "defaults to false, so omitting it runs the migration immediately"
-      view { |v, _i| v.to_h }
-
-      def initialize(container:, call:)
-        @container    = container
-        @call         = call
-      end
-
-      def call(plan_yaml, dry_run: false)
-        raw = YAML.safe_load(plan_yaml, permitted_classes: [Symbol], aliases: false)
-        raise UsageError.new("migration plan must be a YAML mapping") unless raw.is_a?(Hash)
-
-        ops = Array(raw["operations"])
-        all_steps = []
-        warnings = []
-
-        ops.each do |op_hash|
-          op_name = op_hash["op"]
-          sub_plan = invoke_op(op_name, op_hash, dry_run: dry_run)
-          all_steps.concat(sub_plan.steps)
-          warnings.concat(sub_plan.warnings)
-        end
-
-        Plan.new(steps: all_steps, warnings: warnings)
-      end
-
-      private
-
-      def invoke_op(op_name, op_hash, dry_run:)
-        klass = op_class(op_name)
-        inputs = op_hash.except("op").transform_keys(&:to_sym).merge(dry_run: dry_run)
-        # Each op now carries positional args (from/to, from_prefix/to_prefix,
-        # prefix); split the YAML fields into (positional, keyword) via the op's
-        # own contract so we call its #call signature correctly (ADR 0066/0068).
-        args, kwargs = Textus::Contract::Binder.bind(klass.contract, inputs)
-        klass.new(container: @container, call: @call).call(*args, **kwargs)
-      end
-
-      def op_class(op_name)
-        case op_name
-        when "key_mv_prefix"     then KeyMvPrefix
-        when "key_delete_prefix" then KeyDeletePrefix
-        when "zone_mv"           then ZoneMv
-        else raise UsageError.new("unknown op: #{op_name}")
-        end
-      end
-    end
-  end
-end

data/lib/textus/read/retainable.rb

@@ -1,17 +0,0 @@
-module Textus
-  module Read
-    class Retainable
-      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
-        @manifest = container.manifest
-      end
-
-      def call(prefix: nil, zone: nil)
-        Textus::Domain::Retention.new(
-          manifest: @manifest,
-          file_stat: Textus::Ports::Storage::FileStat.new,
-          clock: Textus::Ports::Clock,
-        ).call(prefix: prefix, zone: zone)
-      end
-    end
-  end
-end

data/lib/textus/read/stale.rb

@@ -1,17 +0,0 @@
-module Textus
-  module Read
-    class Stale
-      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
-        @manifest = container.manifest
-      end
-
-      def call(prefix: nil, zone: nil)
-        Textus::Domain::Staleness.new(
-          manifest: @manifest,
-          file_stat: Textus::Ports::Storage::FileStat.new,
-          clock: Textus::Ports::Clock,
-        ).call(prefix: prefix, zone: zone)
-      end
-    end
-  end
-end

data/lib/textus/write/fetch_all.rb

@@ -1,53 +0,0 @@
-module Textus
-  module Write
-    class FetchAll
-      extend Textus::Contract::DSL
-
-      verb     :fetch_all
-      summary  "Fetch all stale quarantine entries, optionally scoped by zone/prefix."
-      surfaces :cli, :mcp
-      cli      "fetch all"
-      arg :prefix, String, description: "only refresh stale entries whose key starts with this dotted prefix"
-      arg :zone,   String, description: "only refresh stale entries in this quarantine zone (see `pulse` stale list)"
-
-      def initialize(container:, call:)
-        @container    = container
-        @call         = call
-      end
-
-      def call(prefix: nil, zone: nil)
-        worker = Textus::Write::FetchWorker.new(
-          container: @container, call: @call,
-        )
-
-        stale_rows = Textus::Read::Stale.new(container: @container, call: @call).call(prefix: prefix, zone: zone)
-        fetched = []
-        failed = []
-        skipped = []
-
-        stale_rows.each do |row|
-          key = row["key"] || row[:key]
-          reason = row["reason"] || row[:reason]
-          if reason.to_s.match?(/ttl exceeded|never fetched/)
-            begin
-              worker.run(key)
-              fetched << key
-            rescue Textus::Error => e
-              failed << { "key" => key, "error" => e.message }
-            end
-          else
-            skipped << { "key" => key, "reason" => reason }
-          end
-        end
-
-        {
-          "protocol" => Textus::PROTOCOL,
-          "ok" => failed.empty?,
-          "fetched" => fetched,
-          "failed" => failed,
-          "skipped" => skipped,
-        }
-      end
-    end
-  end
-end

data/lib/textus/write/retention_sweep.rb

@@ -1,64 +0,0 @@
-require "fileutils"
-
-module Textus
-  module Write
-    # Applies retention actions reported by Read::Retainable. `expire` deletes
-    # the leaf through the role gate; `archive` copies it to
-    # <root>/archive/<relative-path> first, then deletes. Rows whose zone the
-    # caller's role cannot write surface in `failed` rather than aborting.
-    class RetentionSweep
-      extend Textus::Contract::DSL
-
-      verb     :retain
-      summary  "Apply each entry's retention policy; prune expired versions."
-      surfaces :cli
-      cli      "retain"
-      arg :prefix, String, description: "restrict to keys starting with this dotted prefix"
-      arg :zone,   String, description: "restrict to entries in this zone"
-
-      def initialize(container:, call:)
-        @container = container
-        @call      = call
-      end
-
-      def call(prefix: nil, zone: nil)
-        rows = Textus::Read::Retainable.new(container: @container, call: @call)
-                                       .call(prefix: prefix, zone: zone)
-        delete_op = Textus::Write::Delete.new(container: @container, call: @call)
-        expired   = []
-        archived  = []
-        failed    = []
-
-        rows.each do |row|
-          key = row["key"]
-          begin
-            archive_leaf(row) if row["action"] == "archive"
-            delete_op.call(key)
-            (row["action"] == "archive" ? archived : expired) << key
-          rescue Textus::Error => e
-            failed << { "key" => key, "error" => e.message }
-          end
-        end
-
-        {
-          "protocol" => Textus::PROTOCOL,
-          "ok" => failed.empty?,
-          "expired" => expired,
-          "archived" => archived,
-          "failed" => failed,
-        }
-      end
-
-      private
-
-      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