textus 0.52.0 → 0.53.0

data/lib/textus/action/rule_list.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class RuleList < Base
+      extend Textus::Contract::DSL
+
+      verb :rule_list
+      summary "List every rule block in the manifest."
+      surfaces :cli
+      cli "rule list"
+      view(:cli) { |policies| { "verb" => "rule_list", "policies" => policies } }
+
+      BURN = :sync
+
+      def call(container:, **)
+        manifest = container.manifest
+        manifest.rules.blocks.map do |block|
+          row = { "match" => block.match }
+          self.class::LIST_FIELDS.each do |field|
+            value = block.public_send(field)
+            row[field.to_s] = serialize(field, value) unless value.nil?
+          end
+          row
+        end
+      end
+
+      LIST_FIELDS = Textus::Manifest::Schema::FIELD_REGISTRY.select { |_, m| m[:in_rule_list] }.keys.freeze
+
+      private
+
+      def serialize(field, value)
+        case field
+        when :retention
+          { "ttl_seconds" => value.ttl_seconds, "action" => value.action.to_s }
+        when :react
+          value.to_h
+        when :handler_permit
+          value.handlers
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/textus/action/schema_envelope.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class SchemaEnvelope < Base
+      extend Textus::Contract::DSL
+
+      verb :schema_show
+      summary "Return the schema (field shape) for an entry's family, by key."
+      surfaces :cli, :mcp
+      cli "schema show"
+      arg :key, String, required: true, positional: true,
+                        description: "any key in the family whose schema you want; returns required/optional fields and their types"
+
+      BURN = :sync
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def call(container:, **)
+        manifest = container.manifest
+        schemas = container.schemas
+        mentry = manifest.resolver.resolve(@key).entry
+        schema = schemas.fetch_or_nil(mentry.schema)
+        { "protocol" => PROTOCOL, "key" => @key, "schema_ref" => mentry.schema, "schema" => schema&.to_h }
+      end
+    end
+  end
+end

data/lib/textus/action/uid.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Uid < Base
+      extend Textus::Contract::DSL
+
+      verb :uid
+      summary "Return the stable UID of an entry without reading its body."
+      surfaces :cli
+      cli "key uid"
+      arg :key, String, required: true, positional: true, description: "entry key"
+      view(:cli) { |uid, inputs| { "key" => inputs[:key], "uid" => uid } }
+
+      BURN = :sync
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def call(container:, call:)
+        Textus::Action::Get.new(key: @key).call(container: container, call: call).uid
+      end
+
+      def self.new(*args, **kwargs)
+        return super(**kwargs) unless args.any?
+
+        positional = instance_method(:initialize).parameters.slice(:keyreq, :key).map(&:last)
+        mapped = positional.zip(args).to_h
+        super(**mapped.merge(kwargs))
+      end
+    end
+  end
+end

data/lib/textus/action/where.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Where < Base
+      extend Textus::Contract::DSL
+
+      verb :where
+      summary "Resolve a key to its zone, owner, and path without reading the body."
+      surfaces :cli, :mcp
+      arg :key, String, required: true, positional: true,
+                        description: "dotted key to locate (returns zone, owner, path; does not read content)"
+
+      BURN = :sync
+
+      def initialize(key:)
+        super()
+        @key = key
+      end
+
+      def call(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        manifest = container.manifest
+        res = manifest.resolver.resolve(@key)
+        mentry = res.entry
+        path = res.path
+        { "protocol" => PROTOCOL, "key" => @key, "lane" => mentry.lane, "owner" => mentry.owner, "path" => path }
+      end
+
+      def self.new(*args, **kwargs)
+        return super(**kwargs) unless args.any?
+
+        positional = instance_method(:initialize).parameters.slice(:keyreq, :key).map(&:last)
+        mapped = positional.zip(args).to_h
+        super(**mapped.merge(kwargs))
+      end
+    end
+  end
+end

data/lib/textus/action/write_verb.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class WriteVerb < Base
+      private
+
+      def auth(container)
+        Textus::Gate::Auth.new(container)
+      end
+
+      def writer(container, call)
+        Textus::Envelope::IO::Writer.from(container: container, call: call)
+      end
+
+      def reader(container)
+        Textus::Envelope::IO::Reader.from(container: container)
+      end
+
+      def run_with_cascade(target_key, container:, call:)
+        result = yield
+        cascade_to_rdeps(target_key, container, call) if target_key
+        result
+      end
+
+      def cascade_to_rdeps(key, container, call)
+        return if derived_write?(key, container)
+
+        rdeps = Textus::Action::Rdeps.new(key: key).call(container: container, call: call).fetch("rdeps", [])
+        producible = rdeps.select { |dep_key| producible?(dep_key, container) }
+        return if producible.empty?
+
+        producible.each do |dep_key|
+          Textus::Background::Job::Materialize.new(key: dep_key).call(container:, call:)
+        end
+        container.steps.publish(
+          :entry_written,
+          ctx: Textus::Step::Context.for(container: container, call: call),
+          key: key,
+          envelope: nil,
+        )
+      end
+
+      def derived_write?(key, container)
+        container.manifest.resolver.resolve(key).entry.derived?
+      rescue Textus::Error
+        false
+      end
+
+      def producible?(key, container)
+        entry = container.manifest.resolver.resolve(key).entry
+        entry.derived? || !entry.publish_tree.nil?
+      rescue Textus::Error
+        false
+      end
+    end
+  end
+end

data/lib/textus/background/job/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Textus
+  module Background
+    module Job
+      class Base
+        def self.inherited(subclass)
+          super
+          return unless subclass.name
+
+          TracePoint.new(:end) do |tp|
+            if tp.self == subclass
+              Textus::Background::Job.register(subclass)
+              tp.disable
+            end
+          end.enable
+        end
+
+        def call(**)
+          raise NotImplementedError.new("#{self.class}#call")
+        end
+
+        def args = {}
+      end
+    end
+  end
+end

data/lib/textus/background/job/materialize.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Textus
+  module Background
+    module Job
+      class Materialize < Base
+        TYPE = "materialize"
+
+        def initialize(key:)
+          super()
+          @key = key
+        end
+
+        def args = { key: @key }
+
+        def call(container:, call:)
+          result = Textus::Pipeline::Engine.converge(container: container, call: call, keys: [@key])
+          return unless result.is_a?(Hash)
+
+          Array(result[:failed]).each do |failure|
+            container.steps.publish(
+              :produce_failed,
+              ctx: Textus::Step::Context.for(container: container, call: call),
+              keys: [failure["key"]], error: failure["error"]
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/background/job/refresh.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Textus
+  module Background
+    module Job
+      class Refresh < Base
+        TYPE = "refresh"
+
+        def initialize(key:)
+          super()
+          @key = key
+        end
+
+        def args = { key: @key }
+
+        def call(container:, call:)
+          Textus::Pipeline::Engine.converge(container: container, call: call, keys: [@key])
+        end
+      end
+    end
+  end
+end

data/lib/textus/background/job/sweep.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Textus
+  module Background
+    module Job
+      class Sweep < Base
+        REQUIRED_ROLE = Textus::Role::AUTOMATION
+        TYPE = "sweep"
+
+        def initialize(scope: nil, key: nil)
+          super()
+          @scope = scope || {}
+          @key   = key
+        end
+
+        def args = { scope: @scope, key: @key }.compact
+
+        def call(container:, call:)
+          prefix = @key || (@scope.is_a?(Hash) ? @scope["prefix"] : nil)
+          lane   = @scope.is_a?(Hash) ? @scope["lane"] : nil
+          rows = Textus::Core::Retention::Sweep.new(
+            manifest: container.manifest,
+            file_stat: Textus::Ports::Storage::FileStat.new,
+            clock: Textus::Ports::Clock.new,
+          ).call(prefix: prefix, lane: lane)
+          Textus::Background::Retention::Apply.new(container: container, call: call).call(rows)
+        end
+      end
+    end
+  end
+end

data/lib/textus/background/job.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Textus
+  module Background
+    module Job
+      @registry = {}
+
+      def self.registry = @registry
+
+      def self.register(klass)
+        @registry[klass::TYPE] = klass if klass.const_defined?(:TYPE, false)
+      end
+
+      def self.fetch(type)
+        @registry.fetch(type) { raise Textus::UsageError.new("unknown job type: #{type}") }
+      end
+    end
+  end
+end

data/lib/textus/background/plan.rb

@@ -0,0 +1,9 @@
+module Textus
+  module Background
+    Plan = Data.define(:steps, :warnings) do
+      def to_h
+        { "steps" => steps, "warnings" => warnings }
+      end
+    end
+  end
+end

data/lib/textus/background/planner/plan.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Textus
+  module Background
+    module Planner
+      class Plan
+        ACTIONS_BY_TRIGGER = {
+          "convergence" => %w[materialize refresh sweep],
+          "entry.written" => %w[materialize],
+          "entry.deleted" => %w[materialize],
+          "entry.moved" => %w[materialize],
+          "proposal.accepted" => %w[materialize],
+          "proposal.rejected" => %w[materialize],
+        }.freeze
+
+        SCOPE_RESOLVERS = {
+          "materialize" => :producible_keys,
+          "refresh" => :stale_intake_keys,
+          "sweep" => :lane_keys,
+        }.freeze
+
+        def self.seed(container:, queue:, role:)
+          jobs = new(container: container).plan(
+            trigger: { "type" => "convergence" },
+            role: role,
+          )
+          jobs.each { |j| queue.enqueue(j) }
+        end
+
+        def initialize(container:)
+          @container = container
+          @manifest  = container.manifest
+        end
+
+        def plan(trigger:, role:)
+          type = trigger["type"] || trigger[:type]
+          trigger["target"] || trigger[:target]
+          return [] if type.nil?
+
+          blocks_with_react = @manifest.rules.blocks.select(&:react)
+          if blocks_with_react.any?
+            plan_from_rules(blocks_with_react, type, role)
+          else
+            plan_from_defaults(type, role)
+          end
+        end
+
+        private
+
+        def plan_from_rules(blocks, type, role)
+          jobs = []
+          blocks
+            .select { |b| matches_trigger?(b.react, type) }
+            .each do |block|
+              do_action = block.react.raw["do"]
+              Array(do_action).each do |action|
+                if action == "sweep"
+                  jobs << Textus::Ports::Queue::Job.new(
+                    type: "sweep", args: { "scope" => {} }, enqueued_by: role,
+                  )
+                else
+                  resolver = SCOPE_RESOLVERS.fetch(action, :producible_keys)
+                  keys = send(resolver, nil)
+                  keys.each { |key| jobs << job(action, key, role) }
+                end
+              end
+            end
+          jobs
+        end
+
+        def plan_from_defaults(type, role)
+          actions = ACTIONS_BY_TRIGGER.fetch(type, [])
+          jobs = []
+          producible_keys(nil).each { |k| jobs << job("materialize", k, role) } if actions.include?("materialize")
+          stale_intake_keys(nil).each { |k| jobs << job("refresh", k, role) } if actions.include?("refresh")
+          if actions.include?("sweep")
+            jobs << Textus::Ports::Queue::Job.new(
+              type: "sweep", args: { "scope" => {} }, enqueued_by: role,
+            )
+          end
+          jobs
+        end
+
+        def matches_trigger?(react, type)
+          on = react.raw["on"]
+          Array(on).include?(type)
+        end
+
+        def job(type, key, enqueued_by)
+          Textus::Ports::Queue::Job.new(type: type, args: { "key" => key }, enqueued_by: enqueued_by)
+        end
+
+        def producible_keys(_target)
+          @manifest.data.entries
+                   .select { |e| e.derived? || !e.publish_tree.nil? || !e.publish_to.empty? }
+                   .map(&:key)
+        end
+
+        def stale_intake_keys(_target)
+          Textus::Core::Freshness::Evaluator.new(
+            manifest: @manifest,
+            file_stat: Textus::Ports::Storage::FileStat.new,
+            clock: Textus::Ports::Clock.new,
+          ).stale_intake_keys(prefix: nil, lane: nil)
+        end
+
+        def lane_keys(_target)
+          @manifest.data.entries.map(&:key)
+        end
+      end
+    end
+  end
+end

data/lib/textus/{maintenance → background}/retention/apply.rb

@@ -1,12 +1,8 @@
 require "fileutils"
 
 module Textus
-  module Maintenance
+  module Background
     module Retention
-      # The destructive half of convergence: apply retention rows (drop/archive).
-      # Lifted verbatim from the legacy reconcile apply/archive_leaf so drain/serve and
-      # the `sweep` job handler share one path. Runs as the caller's role — never
-      # self-elevates (ADR 0079/0093: destructiveness decides authority).
       class Apply
         def initialize(container:, call:)
           @container = container
@@ -15,17 +11,16 @@ module Textus
 
         def call(rows)
           out = { dropped: [], archived: [], failed: [] }
-          delete = Write::KeyDelete.new(container: @container, call: @call)
           rows.each do |row|
             key = row["key"]
             begin
               case row["action"]
               when "drop"
-                delete.call(key)
+                delete(key)
                 out[:dropped] << key
               when "archive"
                 archive_leaf(row)
-                delete.call(key)
+                delete(key)
                 out[:archived] << key
               end
             rescue Textus::Error => e
@@ -37,7 +32,6 @@ module Textus
 
         private
 
-        # Copy the leaf into <store>/archive/<relative-path> before deletion.
         def archive_leaf(row)
           src  = row["path"]
           root = @container.root.to_s
@@ -46,6 +40,10 @@ module Textus
           FileUtils.mkdir_p(File.dirname(dest))
           FileUtils.cp(src, dest)
         end
+
+        def delete(key)
+          Textus::Action::KeyDelete.new(key: key).call(container: @container, call: @call)
+        end
       end
     end
   end

data/lib/textus/background/worker.rb

@@ -0,0 +1,67 @@
+module Textus
+  module Background
+    class Worker
+      Summary = Struct.new(:completed, :failed, keyword_init: true)
+
+      def self.for(container:, queue:)
+        new(queue: queue, container: container,
+            lease_ttl: container.manifest.data.worker_config[:lease_ttl])
+      end
+
+      def initialize(queue:, container:, lease_ttl: 60)
+        @queue     = queue
+        @container = container
+        @lease_ttl = lease_ttl
+      end
+
+      def drain(worker_id: "drain-#{Process.pid}")
+        completed = 0
+        failed    = 0
+        loop do
+          leased = @queue.lease(worker_id: worker_id, lease_ttl: @lease_ttl)
+          break unless leased
+
+          case run_one(leased)
+          when :completed     then completed += 1
+          when :dead_lettered then failed += 1
+          end
+        end
+        Summary.new(completed: completed, failed: failed)
+      end
+
+      def drain_pool(pool: 4)
+        summaries = []
+        mutex     = Mutex.new
+        threads   = Array.new(pool) do |i|
+          Thread.new do
+            s = drain(worker_id: "pool-#{Process.pid}-#{i}")
+            mutex.synchronize { summaries << s }
+          end
+        end
+        threads.each(&:join)
+        Summary.new(completed: summaries.sum(&:completed), failed: summaries.sum(&:failed))
+      end
+
+      private
+
+      def run_one(leased)
+        job    = leased.job
+        klass  = Textus::Background::Job.fetch(job.type)
+        action = if klass.instance_method(:initialize).parameters.any?
+                   klass.new(**job.args.transform_keys(&:to_sym))
+                 else
+                   klass.new
+                 end
+        call   = Textus::Call.build(
+          role: job.enqueued_by || Textus::Role::AUTOMATION,
+          correlation_id: SecureRandom.uuid,
+        )
+        action.call(container: @container, call: call)
+        @queue.ack(leased)
+        :completed
+      rescue StandardError => e
+        @queue.fail(leased, error: e.message)
+      end
+    end
+  end
+end