textus 0.52.0 → 0.53.0

data/lib/textus/domain/policy/predicates/zone_writable_by.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Domain
-    module Policy
-      module Predicates
-        # Predicate #0 of every write guard. Wraps the post-0.31.0 capability
-        # topology gate (role.can ⊇ verb_for(zone.kind)). On failure, #error
-        # raises the capability-shaped WriteForbidden so the topology refusal
-        # — textus's signature product feature — is unchanged.
-        class ZoneWritableBy
-          attr_reader :reason
-
-          def name = "zone_writable_by"
-
-          def call(eval)
-            manifest = eval.manifest
-            @mentry = manifest.resolver.resolve(eval.target).entry
-            return true if manifest.policy.permission_for(@mentry.zone.to_s).allows_write?(eval.actor)
-
-            @verb    = manifest.policy.verb_for_zone(@mentry.zone) # capability the kind requires
-            @holders = manifest.policy.roles_with_capability(@verb)
-            @reason  = "zone '#{@mentry.zone}' needs capability '#{@verb}'; '#{eval.actor}' lacks it"
-            false
-          end
-
-          # Matches the capability-shaped WriteForbidden landed by ADR 0030
-          # Task 3:
-          #   WriteForbidden.new(key, zone, verb:, holders:)
-          #   → "writing '<k>' (zone '<z>') needs capability '<verb>'",
-          #     hint: "held by: <holders>; pass --as=<role>".
-          def error(_eval)
-            Textus::WriteForbidden.new(@mentry.key, @mentry.zone, verb: @verb, holders: @holders)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/hooks/builtin.rb

@@ -1,70 +0,0 @@
-require "json"
-require "csv"
-require "yaml"
-require "rexml/document"
-
-module Textus
-  module Hooks
-    module Builtin
-      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-      def self.register_all(events:, rpc:) # rubocop:disable Lint/UnusedMethodArgument
-        rpc.register(:resolve_handler, :json) do |caps:, config:, args:|
-          _ = caps
-          _ = args
-          data = JSON.parse(config["bytes"].to_s)
-          { _meta: {}, body: YAML.dump(data) }
-        end
-
-        rpc.register(:resolve_handler, :csv) do |caps:, config:, args:|
-          _ = caps
-          _ = args
-          rows = CSV.parse(config["bytes"].to_s, headers: true).map(&:to_h)
-          { _meta: {}, body: YAML.dump(rows) }
-        end
-
-        rpc.register(:resolve_handler, :"markdown-links") do |caps:, config:, args:|
-          _ = caps
-          _ = args
-          links = config["bytes"].to_s.scan(%r{\[([^\]]+)\]\((https?://[^)\s]+)\)}).map do |text, href|
-            { "text" => text, "href" => href }
-          end
-          { _meta: {}, body: YAML.dump(links) }
-        end
-
-        rpc.register(:resolve_handler, :"ical-events") do |caps:, config:, args:|
-          _ = caps
-          _ = args
-          events_list = []
-          current = nil
-          config["bytes"].to_s.each_line do |line|
-            line = line.strip
-            case line
-            when "BEGIN:VEVENT" then current = {}
-            when "END:VEVENT"
-              events_list << current if current
-              current = nil
-            when /\A(SUMMARY|DTSTART|DTEND|UID|LOCATION|DESCRIPTION):(.*)\z/
-              current[Regexp.last_match(1).downcase] = Regexp.last_match(2) if current
-            end
-          end
-          { _meta: {}, body: YAML.dump(events_list) }
-        end
-
-        rpc.register(:resolve_handler, :rss) do |caps:, config:, args:|
-          _ = caps
-          _ = args
-          doc = REXML::Document.new(config["bytes"].to_s)
-          items = doc.elements.to_a("//item").map do |item|
-            {
-              "title" => item.elements["title"]&.text,
-              "link" => item.elements["link"]&.text,
-              "pubDate" => item.elements["pubDate"]&.text,
-            }
-          end
-          { _meta: {}, body: YAML.dump(items) }
-        end
-      end
-      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
-    end
-  end
-end

data/lib/textus/hooks/loader.rb

@@ -1,54 +0,0 @@
-module Textus
-  module Hooks
-    class Loader
-      # A small DSL object passed to user hook blocks. Routes `.on(...)` to the
-      # EventBus and `.rpc(...)` / `.register(...)` to the RpcRegistry.
-      class Dsl
-        def initialize(events:, rpc:)
-          @events = events
-          @rpc    = rpc
-        end
-
-        # Pubsub registration — delegates to EventBus.
-        # Also handles RPC event names by delegating to RpcRegistry.
-        def on(event, name, keys: nil, &)
-          if Hooks::Catalog::RPC.key?(event.to_sym)
-            @rpc.register(event, name, &)
-          else
-            @events.register(event, name, keys: keys, &)
-          end
-        end
-
-        # Explicit RPC registration.
-        def register(event, name, &)
-          @rpc.register(event, name, &)
-        end
-      end
-
-      def initialize(events:, rpc:)
-        @events = events
-        @rpc    = rpc
-        @dsl    = Dsl.new(events: @events, rpc: @rpc)
-      end
-
-      def load_dir(dir)
-        return unless File.directory?(dir)
-
-        # Discard any leftover blocks from a prior partial load.
-        Textus.drain_hook_blocks
-
-        Dir.glob(File.join(dir, "**/*.rb")).sort.each do |f| # rubocop:disable Lint/RedundantDirGlobSort
-          load(f)
-        rescue StandardError, ScriptError => e
-          raise UsageError.new("failed loading hook #{File.basename(f)}: #{e.class}: #{e.message}")
-        end
-
-        Textus.drain_hook_blocks.each do |blk|
-          blk.call(@dsl)
-        rescue StandardError, ScriptError => e
-          raise UsageError.new("failed registering hook: #{e.class}: #{e.message}")
-        end
-      end
-    end
-  end
-end

data/lib/textus/hooks/rpc_registry.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Hooks
-    class RpcRegistry
-      def initialize
-        @table = Hash.new { |h, k| h[k] = {} }
-      end
-
-      def register(event, name, &blk)
-        event_sym = event.to_sym
-        raise UsageError.new("#{event_sym} is a pubsub event; register on EventBus") if Catalog::PUBSUB.key?(event_sym)
-
-        required = Catalog::RPC[event_sym] or raise UsageError.new("unknown RPC event: #{event}")
-        sig = Signature.new(blk)
-        missing = sig.missing(required)
-        raise UsageError.new("#{event_sym} RPC must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})") if missing.any?
-
-        name = name.to_sym
-        raise UsageError.new("#{event_sym} '#{name}' already registered") if @table[event_sym].key?(name)
-
-        @table[event_sym][name] = blk
-      end
-
-      def names(event) = @table[event.to_sym].keys
-
-      def callable(event, name)
-        @table[event.to_sym][name.to_sym] or raise UsageError.new("unknown #{event}: #{name}")
-      end
-
-      # Invoke a registered callable, injecting `caps:` only if the callable
-      # declares it (or accepts keyrest). Mis-named kwargs (e.g. the legacy
-      # `store:`) are rejected at registration time, not here.
-      def invoke(event, name, caps:, **other)
-        blk = callable(event, name)
-        sig = Signature.new(blk)
-        kwargs = other.dup
-        kwargs[:caps] = caps if sig.accepts_keyrest? || sig.declared_keys.include?(:caps)
-        blk.call(**kwargs)
-      end
-    end
-  end
-end

data/lib/textus/jobs/handlers.rb

@@ -1,62 +0,0 @@
-module Textus
-  module Jobs
-    # Wires the closed allow-list of convergence job types to the existing
-    # convergence code. Authority is read from the job's frozen `enqueued_by`
-    # and turned into the Call the handler runs under: produce self-elevates
-    # inside Produce::Engine regardless; destructive sweep runs AS the caller.
-    module Handlers
-      module_function
-
-      def registry
-        reg = Textus::Domain::Jobs::Registry.new
-        # produce is pure (self-elevates) — any caller may request a rematerialize.
-        reg.register("materialize", handler: method(:produce))
-        reg.register("re-pull",     handler: method(:produce))
-        # sweep is destructive — gate ad-hoc enqueue to the automation authority.
-        reg.register("sweep",       handler: method(:sweep), required_role: Textus::Role::AUTOMATION)
-        reg
-      end
-
-      # produce: render derived / re-pull intake for a single key. Engine
-      # self-elevates to the build actor internally; the passed call carries
-      # only correlation/dry_run plus the stamped role for audit. Engine#call
-      # isolates per-key produce errors into its result hash rather than raising,
-      # so surface them as :produce_failed events (the converge result hash used
-      # to carry them; the worker drops the return, so re-publish here).
-      def produce(job:, container:)
-        call = call_for(job)
-        result = Textus::Produce::Engine.converge(container: container, call: call, keys: [job.args["key"]])
-        return unless result.is_a?(Hash)
-
-        Array(result[:failed]).each do |failure|
-          container.events.publish(
-            :produce_failed,
-            ctx: Textus::Hooks::Context.for(container: container, call: call),
-            keys: [failure["key"]], error: failure["error"]
-          )
-        end
-      end
-
-      # sweep: compute retention rows for the scope, then apply destructively AS
-      # the job's role (no self-elevation).
-      def sweep(job:, container:)
-        call = call_for(job)
-        scope = job.args["scope"]
-        rows = Textus::Domain::Retention::Sweep.new(
-          manifest: container.manifest,
-          file_stat: Textus::Ports::Storage::FileStat.new,
-          clock: Textus::Ports::Clock.new,
-        ).call(prefix: scope_prefix(scope), zone: scope_zone(scope))
-        Textus::Maintenance::Retention::Apply.new(container: container, call: call).call(rows)
-      end
-
-      def call_for(job)
-        Textus::Call.build(role: job.enqueued_by || Textus::Role::AUTOMATION)
-      end
-
-      # A scope is `{ "prefix" => ..., "zone" => ... }` or nil (whole store).
-      def scope_prefix(scope) = scope.is_a?(Hash) ? scope["prefix"] : nil
-      def scope_zone(scope)   = scope.is_a?(Hash) ? scope["zone"]   : nil
-    end
-  end
-end

data/lib/textus/jobs/scheduler.rb

@@ -1,36 +0,0 @@
-module Textus
-  module Jobs
-    # Time-based seeding for the daemon: at each tick, enqueue a re-pull job for
-    # every intake key past its source.ttl and a sweep job to GC entries past
-    # retention.ttl. Dedup means a job already queued from a prior tick is a
-    # no-op. Both are stamped automation (the daemon's own authority); the sweep
-    # handler runs retention as that role.
-    class Scheduler
-      def initialize(container:, queue:)
-        @container = container
-        @queue = queue
-      end
-
-      def run_once
-        stale_intake.each do |key|
-          @queue.enqueue(job("re-pull", { "key" => key }))
-        end
-        @queue.enqueue(job("sweep", { "scope" => { "prefix" => nil, "zone" => nil } }))
-      end
-
-      private
-
-      def stale_intake
-        Textus::Domain::Freshness::Evaluator.new(
-          manifest: @container.manifest,
-          file_stat: Textus::Ports::Storage::FileStat.new,
-          clock: Textus::Ports::Clock.new,
-        ).stale_intake_keys(prefix: nil, zone: nil)
-      end
-
-      def job(type, args)
-        Textus::Domain::Jobs::Job.new(type: type, args: args, enqueued_by: Textus::Role::AUTOMATION)
-      end
-    end
-  end
-end

data/lib/textus/jobs/seeder.rb

@@ -1,57 +0,0 @@
-module Textus
-  module Jobs
-    # Enqueues the full convergence set for a scope: a produce job per derived /
-    # publish_tree / publish.to entry, a re-pull job per stale intake key, and a
-    # single sweep job for the scope. The scope logic mirrors
-    # the converge scope (Produce::Engine) so `drain` and `serve` converge identically.
-    # Produce jobs self-elevate (stamped automation); the sweep job carries the
-    # caller's role (destructive runs as caller).
-    class Seeder
-      def initialize(container:, queue:, call:)
-        @container = container
-        @queue = queue
-        @call = call
-        @manifest = container.manifest
-      end
-
-      def seed(prefix:, zone:)
-        file_stat = Textus::Ports::Storage::FileStat.new
-
-        producible_keys(prefix, zone).each do |key|
-          @queue.enqueue(job("materialize", { "key" => key }, Textus::Role::AUTOMATION))
-        end
-        stale_intake_keys(prefix, zone, file_stat).each do |key|
-          @queue.enqueue(job("re-pull", { "key" => key }, Textus::Role::AUTOMATION))
-        end
-        @queue.enqueue(job("sweep", { "scope" => { "prefix" => prefix, "zone" => zone } }, @call.role))
-      end
-
-      private
-
-      def job(type, args, role)
-        Textus::Domain::Jobs::Job.new(type: type, args: args, enqueued_by: role)
-      end
-
-      # Mirrors the converge scope (the publishable arm).
-      def producible_keys(prefix, zone)
-        @manifest.data.entries
-                 .select { |e| e.derived? || !e.publish_tree.nil? || !e.publish_to.empty? }
-                 .select { |e| in_scope?(e, prefix, zone) }
-                 .map(&:key)
-      end
-
-      def stale_intake_keys(prefix, zone, file_stat)
-        Textus::Domain::Freshness::Evaluator.new(
-          manifest: @manifest, file_stat: file_stat, clock: Textus::Ports::Clock.new,
-        ).stale_intake_keys(prefix: prefix, zone: zone)
-      end
-
-      def in_scope?(entry, prefix, zone)
-        return false if zone && entry.zone != zone
-        return false if prefix && !entry.key.start_with?(prefix)
-
-        true
-      end
-    end
-  end
-end

data/lib/textus/maintenance/drain.rb

@@ -1,42 +0,0 @@
-module Textus
-  module Maintenance
-    # Converge-and-exit: seed the full convergence set for the scope, run the
-    # worker until the queue is empty, return a health summary. Exits not-ok if
-    # any job dead-lettered. This is the converge entry point and what CI
-    # runs. Single-pass (serial) on purpose: each produce job self-locks via
-    # Produce::Engine.converge, so running them in turn keeps the build lock
-    # uncontended; a concurrent pool would make all-but-one produce job hit
-    # BuildInProgress and skip.
-    class Drain
-      extend Textus::Contract::DSL
-
-      verb     :drain
-      summary  "Converge everything now: seed produce + retention jobs and drain the queue to empty."
-      surfaces :cli, :mcp
-      cli      "drain"
-      arg :prefix, String, description: "restrict convergence to keys under this dotted prefix"
-      arg :zone,   String, description: "restrict convergence to entries in this zone"
-
-      def initialize(container:, call:)
-        @container = container
-        @call = call
-      end
-
-      def call(prefix: nil, zone: nil)
-        queue = Textus::Ports::Queue.new(root: @container.root)
-        Textus::Jobs::Seeder.new(container: @container, queue: queue, call: @call).seed(prefix: prefix, zone: zone)
-
-        summary = Worker.for(container: @container, queue: queue).drain
-        health = Read::Doctor.new(container: @container, call: @call).call
-
-        {
-          "protocol" => Textus::PROTOCOL,
-          "ok" => summary.failed.zero?,
-          "completed" => summary.completed,
-          "failed" => summary.failed,
-          "health" => health,
-        }
-      end
-    end
-  end
-end

data/lib/textus/maintenance/key_delete_prefix.rb

@@ -1,48 +0,0 @@
-module Textus
-  module Maintenance
-    # Bulk-delete every leaf key under `prefix`.
-    class KeyDeletePrefix
-      extend Textus::Contract::DSL
-
-      verb     :key_delete_prefix
-      summary  "Bulk-delete every leaf key under prefix."
-      surfaces :cli, :mcp
-      cli      "key delete-prefix"
-      arg :prefix,  String, required: true, positional: true, description: "every leaf key under this dotted prefix is deleted"
-      arg :dry_run, :boolean, default: false,
-                              description: "when true, returns the keys that would be deleted without deleting them; " \
-                                           "defaults to false, so omitting it deletes immediately"
-      view { |v, _i| v.to_h }
-
-      def initialize(container:, call:)
-        @container    = container
-        @call         = call
-      end
-
-      def call(prefix, dry_run: false)
-        raise UsageError.new("prefix required") if prefix.nil? || prefix.empty?
-
-        leaves = Read::List.new(container: @container)
-                           .call(prefix: prefix)
-                           .map { |r| r.is_a?(Hash) ? (r["key"] || r[:key]) : r }
-
-        warnings = leaves.empty? ? ["no keys under #{prefix}"] : []
-        steps = leaves.map { |k| { "op" => "delete", "key" => k } }
-
-        plan = Plan.new(steps: steps, warnings: warnings)
-        return plan if dry_run
-
-        steps.each do |s|
-          delete.call(s["key"])
-        end
-        plan
-      end
-
-      private
-
-      def delete
-        Write::KeyDelete.new(container: @container, call: @call)
-      end
-    end
-  end
-end

data/lib/textus/maintenance/key_mv_prefix.rb

@@ -1,68 +0,0 @@
-module Textus
-  module Maintenance
-    # Bulk-rename every leaf key under `from_prefix` to `to_prefix`.
-    # Calls Write::KeyMv directly for each entry — emits one audit row per file moved.
-    class KeyMvPrefix
-      extend Textus::Contract::DSL
-
-      verb     :key_mv_prefix
-      summary  "Bulk-rename every leaf key under from_prefix to to_prefix. Dry-run returns a Plan; apply with dry_run: false."
-      surfaces :cli, :mcp
-      cli      "key mv-prefix"
-      arg :from_prefix, String, required: true, positional: true, description: "dotted prefix whose leaf keys are renamed"
-      arg :to_prefix,   String, required: true, positional: true, description: "dotted prefix the keys are renamed to"
-      arg :dry_run,     :boolean, default: false,
-                                  description: "when true, returns the planned moves without applying them; " \
-                                               "defaults to false, so omitting it applies the rename immediately"
-      view { |v, _i| v.to_h }
-
-      def initialize(container:, call:)
-        @container    = container
-        @call         = call
-      end
-
-      def call(from_prefix, to_prefix, dry_run: false)
-        raise UsageError.new("from_prefix and to_prefix required") if from_prefix.nil? || to_prefix.nil?
-
-        leaves = list_leaves_under(from_prefix)
-
-        # When from_prefix is itself a leaf, `delete_prefix("#{from_prefix}.")`
-        # finds no trailing dot to strip, so the tail keeps the whole key and the
-        # move silently targets "to_prefix.<full-from_prefix>". Refuse it — a
-        # single-key rename is `mv`'s job, not the bulk prefix verb's.
-        if leaves.include?(from_prefix)
-          raise UsageError.new("from_prefix '#{from_prefix}' is itself a leaf — use `mv` to rename a single key")
-        end
-
-        warnings = []
-        warnings << "no keys under #{from_prefix}" if leaves.empty?
-
-        steps = leaves.map do |old_key|
-          tail = old_key.delete_prefix("#{from_prefix}.")
-          new_key = "#{to_prefix}.#{tail}"
-          { "op" => "mv", "from" => old_key, "to" => new_key }
-        end
-
-        plan = Plan.new(steps: steps, warnings: warnings)
-        return plan if dry_run
-
-        steps.each do |s|
-          mv.call(s["from"], s["to"], dry_run: false)
-        end
-        plan
-      end
-
-      private
-
-      def list_leaves_under(prefix)
-        Read::List.new(container: @container)
-                  .call(prefix: prefix)
-                  .map { |row| row.is_a?(Hash) ? (row["key"] || row[:key]) : row }
-      end
-
-      def mv
-        Write::KeyMv.new(container: @container, call: @call)
-      end
-    end
-  end
-end

data/lib/textus/maintenance/rule_lint.rb

@@ -1,66 +0,0 @@
-require "yaml"
-
-module Textus
-  module Maintenance
-    # Compare the live manifest's `rules:` block against a candidate
-    # YAML string. Returns a Plan describing rule additions/removals/
-    # changes. Does NOT write anything.
-    class RuleLint
-      extend Textus::Contract::DSL
-
-      verb     :rule_lint
-      summary  "Diff candidate manifest YAML's rules against the live manifest. No writes."
-      surfaces :cli, :mcp
-      cli      "rule lint"
-      arg :candidate_yaml, String, required: true, wire_name: :against, source: :file,
-                                   description: "path to candidate manifest YAML; its `rules:` block is diffed against the live manifest"
-      view { |v, _i| v.to_h }
-
-      def initialize(container:, call:)
-        @container = container
-        @call      = call
-        @root      = container.root
-      end
-
-      def call(candidate_yaml:)
-        live_rules      = current_rules
-        candidate_rules = parse_candidate(candidate_yaml)
-
-        live_by_match      = live_rules.to_h { |r| [r["match"], r] }
-        candidate_by_match = candidate_rules.to_h { |r| [r["match"], r] }
-
-        steps = (candidate_by_match.keys - live_by_match.keys).map do |m|
-          { "op" => "add_rule", "match" => m, "rule" => candidate_by_match[m] }
-        end
-        (live_by_match.keys - candidate_by_match.keys).each do |m|
-          steps << { "op" => "remove_rule", "match" => m }
-        end
-        (live_by_match.keys & candidate_by_match.keys).each do |m|
-          next if live_by_match[m] == candidate_by_match[m]
-
-          steps << { "op" => "change_rule", "match" => m,
-                     "from" => live_by_match[m], "to" => candidate_by_match[m] }
-        end
-
-        Plan.new(steps: steps, warnings: [])
-      end
-
-      private
-
-      def current_rules
-        raw = YAML.safe_load_file(File.join(@root, "manifest.yaml"),
-                                  permitted_classes: [Symbol], aliases: false)
-        Array(raw["rules"])
-      end
-
-      def parse_candidate(yaml_text)
-        raw = YAML.safe_load(yaml_text, permitted_classes: [Symbol], aliases: false)
-        raise UsageError.new("candidate is not a YAML mapping") unless raw.is_a?(Hash)
-
-        Array(raw["rules"])
-      rescue Psych::Exception => e
-        raise UsageError.new("candidate YAML parse error: #{e.message}")
-      end
-    end
-  end
-end

data/lib/textus/maintenance/serve.rb

@@ -1,30 +0,0 @@
-module Textus
-  module Maintenance
-    # The convergence daemon loop: seed scheduled work (TTL re-pull + sweep),
-    # reclaim crashed leases, drain the queue, sleep, repeat. `tick` is one
-    # iteration (unit-testable); `run` loops forever. Drains serially for the
-    # same reason as Drain — each produce job self-locks, so running them in turn
-    # keeps the build lock uncontended.
-    class Serve
-      def initialize(container:, call:)
-        @container = container
-        @call = call
-        @queue = Textus::Ports::Queue.new(root: container.root)
-      end
-
-      def tick
-        Textus::Jobs::Scheduler.new(container: @container, queue: @queue).run_once
-        @queue.reclaim(now: Textus::Ports::Clock.new.now)
-        Worker.for(container: @container, queue: @queue).drain
-      end
-
-      def run(poll: nil)
-        interval = poll || @container.manifest.data.worker_config[:poll]
-        loop do
-          tick
-          sleep(interval)
-        end
-      end
-    end
-  end
-end