textus 0.26.0 → 0.29.0

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

@@ -3,22 +3,24 @@ module Textus
     class Check
       class Sentinels < Check
         def call
-          dir = File.join(root, "sentinels")
-          return [] unless File.directory?(dir)
+          store      = Textus::Ports::SentinelStore.new
+          file_stat  = Textus::Ports::Storage::FileStat.new
+          dir        = File.join(root, "sentinels")
+          return [] unless file_stat.directory?(dir)
 
           repo_root = File.dirname(root)
-          Dir.glob(File.join(dir, "**", "*#{Textus::Domain::Sentinel::SUFFIX}")).flat_map do |sentinel_path|
-            inspect_sentinel(sentinel_path, repo_root)
+          file_stat.glob(File.join(dir, "**", "*#{Textus::Ports::SentinelStore::SUFFIX}")).flat_map do |sentinel_path|
+            inspect_sentinel(sentinel_path, repo_root, store, file_stat)
           end
         end
 
         private
 
-        def inspect_sentinel(sentinel_path, repo_root)
-          sentinel = Textus::Domain::Sentinel.load(sentinel_path, repo_root)
+        def inspect_sentinel(sentinel_path, repo_root, store, file_stat)
+          sentinel = store.load(sentinel_path, repo_root)
           return [parse_error_issue(sentinel_path)] if sentinel.nil?
-          return [orphan_issue(sentinel_path, sentinel)] if sentinel.orphan?
-          return [drift_issue(sentinel)] if sentinel.drift?
+          return [orphan_issue(sentinel_path, sentinel)] if sentinel.orphan?(file_stat)
+          return [drift_issue(sentinel)] if sentinel.drift?(file_stat)
 
           []
         end

data/lib/textus/doctor/check.rb

@@ -14,8 +14,8 @@ module Textus
                           .downcase
       end
 
-      def initialize(session)
-        @session = session
+      def initialize(container)
+        @container = container
       end
 
       def call
@@ -24,9 +24,16 @@ module Textus
 
       protected
 
-      def root     = @session.read_caps.root
-      def manifest = @session.read_caps.manifest
-      def rpc      = @session.rpc
+      def root     = @container.root
+      def manifest = @container.manifest
+      def rpc      = @container.rpc
+
+      # Dispatch a verb through the static Dispatcher table.
+      def dispatch(verb, *, **)
+        klass = Textus::Dispatcher.fetch(verb)
+        call_value = Textus::Call.build(role: Textus::Role::DEFAULT)
+        klass.new(container: @container, call: call_value).call(*, **)
+      end
     end
   end
 end

data/lib/textus/doctor.rb

@@ -30,7 +30,7 @@ module Textus
 
     module_function
 
-    def run(session, checks: nil)
+    def build(container:, checks: nil)
       selected_keys = checks ? Array(checks).map(&:to_s) : ALL_CHECKS
       unknown = selected_keys - ALL_CHECKS
       unless unknown.empty?
@@ -40,8 +40,8 @@ module Textus
       end
 
       selected = CHECKS.select { |c| selected_keys.include?(c.name_key) }
-      issues = selected.flat_map { |c| c.new(session).call }
-      issues.concat(run_registered_checks(session))
+      issues = selected.flat_map { |c| c.new(container).call }
+      issues.concat(run_registered_checks(container))
 
       summary = LEVELS.to_h { |l| [l, issues.count { |i| i["level"] == l }] }
       {
@@ -52,13 +52,13 @@ module Textus
       }
     end
 
-    def run_registered_checks(session)
-      session.rpc.names(:validate).flat_map { |name| invoke_registered_check(session, name) }
+    def run_registered_checks(container)
+      container.rpc.names(:validate).flat_map { |name| invoke_registered_check(container, name) }
     end
 
-    def invoke_registered_check(session, name)
+    def invoke_registered_check(container, name)
       result = Timeout.timeout(DOCTOR_CHECK_TIMEOUT_SECONDS) do
-        session.rpc.invoke(:validate, name, caps: session.write_caps)
+        container.rpc.invoke(:validate, name, caps: container)
       end
       return result.map { |h| h.transform_keys(&:to_s) } if result.is_a?(Array)
 

data/lib/textus/domain/authorizer.rb

@@ -3,8 +3,8 @@
 module Textus
   module Domain
     # Authorization service. Single source of truth for "given a manifest
-    # entry and a role, may this caller read/write?". Extracted from
-    # Application::Context so the rule lives in Domain alongside Permission.
+    # entry and a role, may this caller read/write?". Lives in Domain
+    # alongside Permission.
     class Authorizer
       def initialize(manifest:)
         @manifest = manifest

data/lib/textus/domain/sentinel.rb

@@ -1,69 +1,15 @@
-require "json"
 require "digest"
-require "fileutils"
 
 module Textus
   module Domain
-    # Value object for sentinel files written by Infra::Publisher and inspected
-    # by Doctor::Check::Sentinels. Owns the JSON shape ({source, target,
-    # sha256, mode}) and the on-disk path layout (<store_root>/sentinels/
-    # <target-rel-to-repo>.textus-managed.json). Target/source are repo-relative
-    # when the published file is under the repo root, absolute otherwise.
+    # Pure value object representing a published-file sentinel. Holds the
+    # recorded target path, source path, sha256 checksum, and publish mode.
+    # Has no filesystem I/O — path layout and persistence live in
+    # Ports::SentinelStore; predicate methods accept a FileStat port for
+    # existence and content checks.
     class Sentinel
-      SUFFIX = ".textus-managed.json".freeze
-      DIR    = "sentinels".freeze
-
       attr_reader :target, :source, :sha256, :mode
 
-      def self.write!(target:, source:, store_root:)
-        path = sentinel_path(target, store_root)
-        FileUtils.mkdir_p(File.dirname(path))
-        repo_root = File.dirname(store_root)
-        File.write(path, JSON.generate(
-                           "source" => rel_or_abs(source, repo_root),
-                           "target" => rel_or_abs(target, repo_root),
-                           "sha256" => Digest::SHA256.hexdigest(File.binread(target)),
-                           "mode" => "copy",
-                         ))
-      end
-
-      def self.load(path, repo_root)
-        raw = JSON.parse(File.read(path))
-        new(
-          target: absolutize(raw["target"], repo_root),
-          source: absolutize(raw["source"], repo_root),
-          sha256: raw["sha256"],
-          mode: raw["mode"],
-        )
-      rescue JSON::ParserError, Errno::ENOENT
-        nil
-      end
-
-      def self.sentinel_path(target, store_root)
-        repo_root = File.dirname(store_root)
-        rel = relative_to(target, repo_root) || File.basename(target)
-        File.join(store_root, DIR, rel + SUFFIX)
-      end
-
-      def self.rel_or_abs(path, repo_root)
-        relative_to(path, repo_root) || File.expand_path(path)
-      end
-
-      def self.relative_to(path, repo_root)
-        path = File.expand_path(path)
-        base = File.expand_path(repo_root)
-        return nil unless path.start_with?(base + File::SEPARATOR)
-
-        path[(base.length + 1)..]
-      end
-
-      def self.absolutize(path, repo_root)
-        return path if path.nil?
-        return path if File.absolute_path?(path)
-
-        File.expand_path(path, repo_root)
-      end
-
       def initialize(target:, source:, sha256:, mode:)
         @target = target
         @source = source
@@ -71,15 +17,13 @@ module Textus
         @mode = mode
       end
 
-      def orphan?
-        @target.nil? || !File.exist?(@target)
-      end
+      def orphan?(file_stat) = @target.nil? || !file_stat.exists?(@target)
 
-      def drift?
-        return false if orphan?
+      def drift?(file_stat)
+        return false if orphan?(file_stat)
         return false if @sha256.nil?
 
-        Digest::SHA256.hexdigest(File.binread(@target)) != @sha256
+        Digest::SHA256.hexdigest(file_stat.read(@target)) != @sha256
       end
     end
   end

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

@@ -8,34 +8,43 @@ module Textus
       # entry's `_meta.generated.at` timestamp. Returns an Array of row hashes
       # (possibly empty) per entry.
       class GeneratorCheck
-        def initialize(manifest:)
-          @manifest = manifest
+        def initialize(manifest:, file_stat:)
+          @manifest  = manifest
+          @file_stat = file_stat
         end
 
         def rows_for(mentry)
-          return [] unless mentry.in_generator_zone?
-          return [] unless mentry.is_a?(Textus::Manifest::Entry::Derived)
-
-          src = mentry.source
-          return [] unless src.is_a?(Textus::Manifest::Entry::Derived::External)
+          return [] unless applicable?(mentry)
 
           path = Textus::Key::Path.resolve(@manifest.data, mentry)
-          return [stale_row(mentry, path, "derived entry has never been generated")] unless File.exist?(path)
+          reason = stale_reason(mentry, path)
+          reason ? [stale_row(mentry, path, reason)] : []
+        end
 
-          parsed = Entry.for_format(mentry.format).parse(File.binread(path), path: path)
-          generated_at = parsed["_meta"].dig("generated", "at")
-          return [stale_row(mentry, path, "missing generated.at frontmatter")] unless generated_at
+        private
 
-          gen_time = parse_time(generated_at)
-          return [stale_row(mentry, path, "unparseable generated.at: #{generated_at.inspect}")] unless gen_time
+        def applicable?(mentry)
+          mentry.in_generator_zone?(@manifest.policy) &&
+            mentry.is_a?(Textus::Manifest::Entry::Derived) &&
+            mentry.source.is_a?(Textus::Manifest::Entry::Derived::External)
+        end
 
-          offender = newest_source_after(src, gen_time)
-          return [stale_row(mentry, path, "source '#{offender}' modified after generated.at")] if offender
+        def stale_reason(mentry, path)
+          return "derived entry has never been generated" unless @file_stat.exists?(path)
 
-          []
+          generated_at = generated_at_of(mentry, path)
+          return "missing generated.at frontmatter" unless generated_at
+
+          gen_time = parse_time(generated_at)
+          return "unparseable generated.at: #{generated_at.inspect}" unless gen_time
+
+          offender = newest_source_after(mentry.source, gen_time)
+          "source '#{offender}' modified after generated.at" if offender
         end
 
-        private
+        def generated_at_of(mentry, path)
+          Entry.for_format(mentry.format).parse(@file_stat.read(path), path: path)["_meta"].dig("generated", "at")
+        end
 
         def parse_time(str)
           Time.parse(str.to_s)
@@ -54,7 +63,7 @@ module Textus
         def check_source(src, gen_time)
           if src.match?(/\A[a-z0-9.][a-z0-9._-]*\z/) && !src.include?("/")
             @manifest.resolver.enumerate(prefix: src).each do |row|
-              return src if File.mtime(row[:path]) > gen_time
+              return src if @file_stat.mtime(row[:path]) > gen_time
             end
             nil
           else
@@ -63,18 +72,29 @@ module Textus
         end
 
         def check_filesystem_source(src, gen_time)
-          abs = File.absolute_path?(src) ? src : File.join(File.dirname(@manifest.data.root), src)
-          if File.directory?(abs)
-            Dir.glob(File.join(abs, "**", "*")).each do |fp|
-              next unless File.file?(fp)
-              return src if File.mtime(fp) > gen_time
-            end
-            nil
-          elsif File.exist?(abs) && File.mtime(abs) > gen_time
+          abs = absolutize_source(src)
+          if @file_stat.directory?(abs)
+            dir_has_newer_file?(abs, gen_time) ? src : nil
+          elsif @file_stat.exists?(abs) && @file_stat.mtime(abs) > gen_time
             src
           end
         end
 
+        def absolutize_source(src)
+          File.absolute_path?(src) ? src : File.join(File.dirname(@manifest.data.root), src)
+        end
+
+        def dir_has_newer_file?(abs, gen_time)
+          @file_stat.glob(File.join(abs, "**", "*")).any? do |fpath|
+            file?(fpath) && @file_stat.mtime(fpath) > gen_time
+          end
+        end
+
+        # FileStat substitute for File.file?: excludes directories but treats
+        # special files (FIFOs/sockets/devices) as regular files — acceptable
+        # because a generator source tree won't contain them.
+        def file?(fpath) = !@file_stat.directory?(fpath) && @file_stat.exists?(fpath)
+
         def stale_row(mentry, path, reason)
           {
             "key" => mentry.key,

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

@@ -6,8 +6,10 @@ module Textus
       # Reports TTL-exceeded staleness for intake-handler entries. Returns an
       # Array of row hashes (possibly empty) per entry.
       class IntakeCheck
-        def initialize(manifest:)
-          @manifest = manifest
+        def initialize(manifest:, file_stat:, clock:)
+          @manifest  = manifest
+          @file_stat = file_stat
+          @clock     = clock
         end
 
         def rows_for(mentry)
@@ -17,19 +19,25 @@ module Textus
           return [] unless ttl
 
           path = Textus::Key::Path.resolve(@manifest.data, mentry)
-          return [row(mentry, path, "never refreshed")] unless File.exist?(path)
+          reason = ttl_reason(mentry, path, ttl)
+          reason ? [row(mentry, path, reason)] : []
+        end
+
+        private
 
-          meta = Entry.for_format(mentry.format).parse(File.binread(path), path: path)["_meta"]
-          last_str = meta["last_refreshed_at"]
-          return [row(mentry, path, "never refreshed (no last_refreshed_at)")] if last_str.nil?
+        def ttl_reason(mentry, path, ttl)
+          return "never refreshed" unless @file_stat.exists?(path)
 
-          last = parse_time(last_str)
-          return [row(mentry, path, "ttl exceeded (#{ttl}s)")] if last.nil? || (Time.now - last) > ttl
+          last_str = last_refreshed_of(mentry, path)
+          return "never refreshed (no last_refreshed_at)" if last_str.nil?
 
-          []
+          last = parse_time(last_str)
+          "ttl exceeded (#{ttl}s)" if last.nil? || (@clock.now - last) > ttl
         end
 
-        private
+        def last_refreshed_of(mentry, path)
+          Entry.for_format(mentry.format).parse(@file_stat.read(path), path: path)["_meta"]["last_refreshed_at"]
+        end
 
         def parse_time(str)
           Time.parse(str.to_s)

data/lib/textus/domain/staleness.rb

@@ -1,10 +1,10 @@
 module Textus
   module Domain
     class Staleness
-      def initialize(manifest:)
+      def initialize(manifest:, file_stat:, clock:)
         @manifest = manifest
-        @generator_check = GeneratorCheck.new(manifest: manifest)
-        @intake_check = IntakeCheck.new(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)

data/lib/textus/{application/envelope → envelope/io}/reader.rb

@@ -1,6 +1,6 @@
 module Textus
-  module Application
-    module Envelope
+  class Envelope
+    module IO
       # Read-only counterpart to EnvelopeWriter. Resolves a key, reads the
       # bytes, parses them via the format strategy, and hands back an
       # Envelope. Used by Mv (pre-move inspection) and by EnvelopeWriter

data/lib/textus/{application/envelope → envelope/io}/writer.rb

@@ -1,8 +1,8 @@
 require "fileutils"
 
 module Textus
-  module Application
-    module Envelope
+  class Envelope
+    module IO
       # Owns the write pipeline (validate, serialize, etag-check, write, audit).
       # Talks to ports (FileStore, Schemas, AuditLog, Manifest) and an
       # Reader for the existing-uid lookup.
@@ -10,16 +10,16 @@ module Textus
       # Invariant: every public method's final action is @audit_log.append(...).
       #
       # No permission check, no event firing — those belong to the caller
-      # (Application::Write::Put / ::Delete / ::Mv).
+      # (Write::Put / ::Delete / ::Mv).
       class Writer
         Payload = Data.define(:meta, :body, :content)
 
-        def initialize(file_store:, manifest:, schemas:, audit_log:, ctx:, reader:)
+        def initialize(file_store:, manifest:, schemas:, audit_log:, call:, reader:)
           @file_store = file_store
           @manifest   = manifest
           @schemas    = schemas
           @audit_log  = audit_log
-          @ctx        = ctx
+          @call       = call
           @reader     = reader
         end
 
@@ -56,9 +56,9 @@ module Textus
             meta: eff_meta, body: eff_body, etag: etag_after, content: eff_content
           )
           @audit_log.append(
-            role: @ctx.role, verb: "put", key: key,
+            role: @call.role, verb: "put", key: key,
             etag_before: etag_before, etag_after: etag_after,
-            extras: @ctx.correlation_id ? { "correlation_id" => @ctx.correlation_id } : nil
+            extras: @call.correlation_id ? { "correlation_id" => @call.correlation_id } : nil
           )
           envelope
         end
@@ -75,9 +75,9 @@ module Textus
 
           @file_store.delete(path)
           @audit_log.append(
-            role: @ctx.role, verb: "delete", key: key,
+            role: @call.role, verb: "delete", key: key,
             etag_before: etag_before, etag_after: nil,
-            extras: @ctx.correlation_id ? { "correlation_id" => @ctx.correlation_id } : nil
+            extras: @call.correlation_id ? { "correlation_id" => @call.correlation_id } : nil
           )
         end
 
@@ -108,10 +108,10 @@ module Textus
             "from_path" => from_path, "to_path" => to_path,
             "uid" => envelope.uid
           }
-          extras["correlation_id"] = @ctx.correlation_id if @ctx.correlation_id
+          extras["correlation_id"] = @call.correlation_id if @call.correlation_id
 
           @audit_log.append(
-            role: @ctx.role, verb: "mv", key: to_key,
+            role: @call.role, verb: "mv", key: to_key,
             etag_before: etag_before, etag_after: etag_after,
             extras: extras
           )

data/lib/textus/hooks/context.rb

@@ -3,31 +3,48 @@
 module Textus
   module Hooks
     # A narrow handle passed to user hooks in place of the raw Store.
-    # All writes route back through the Session so authorization, audit
+    # All writes route back through the RoleScope so authorization, audit
     # logging, and schema validation always fire.
     class Context
       attr_reader :role, :correlation_id
 
-      def initialize(session:)
-        @session = session
-        @role = session.ctx.role
-        @correlation_id = session.ctx.correlation_id
+      def self.for(container:, call:)
+        scope = Textus::RoleScope.new(
+          container: container,
+          role: call.role,
+          correlation_id: call.correlation_id,
+          dry_run: call.dry_run,
+        )
+        new(scope: scope)
+      end
+
+      def initialize(scope:)
+        @scope          = scope
+        @role           = scope.role
+        @correlation_id = scope.correlation_id
+      end
+
+      def backend
+        @scope
       end
 
       # read
-      def get(key)                = @session.get(key)
-      def list(**)                = @session.list(**)
-      def deps(key)               = @session.deps(key)
-      def freshness(key)          = @session.freshness(key)
+      def get(key)                = @scope.get(key)
+      def list(**)                = @scope.list(**)
+      def deps(key)               = @scope.deps(key)
+      def freshness(key)          = @scope.freshness(key)
 
       # write (authorized + audited)
-      def put(key, **)          = @session.put(key, **)
-      def delete(key, **)       = @session.delete(key, **)
-      def audit(verb, key:, **) = @session.write_caps.audit_log.append(role: @role, verb: verb, key: key, **)
+      def put(key, **)          = @scope.put(key, **)
+      def delete(key, **)       = @scope.delete(key, **)
+
+      def audit(verb, key:, **)
+        @scope.container.audit_log.append(role: @role, verb: verb, key: key, **)
+      end
 
       # fan-out
       def publish_followup(event, **)
-        @session.write_caps.events.publish(event, ctx: self, **)
+        @scope.container.events.publish(event, ctx: self, **)
       end
 
       def inspect

data/lib/textus/hooks/rpc_registry.rb

@@ -44,7 +44,7 @@ module Textus
         if declared.include?(:store)
           raise UsageError.new(
             "RPC callable for #{event} '#{name}' declares legacy `store:`; rename to `caps:` " \
-            "(Textus::Application::ReadCaps / WriteCaps)",
+            "(Textus::Container)",
           )
         end
 

data/lib/textus/maintenance/key_delete_prefix.rb

@@ -0,0 +1,36 @@
+module Textus
+  module Maintenance
+    # Bulk-delete every leaf key under `prefix`.
+    class KeyDeletePrefix
+      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::Delete.new(container: @container, call: @call)
+      end
+    end
+  end
+end

data/lib/textus/maintenance/key_mv_prefix.rb

@@ -0,0 +1,46 @@
+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.
+    class KeyMvPrefix
+      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)
+        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::Mv.new(container: @container, call: @call)
+      end
+    end
+  end
+end

data/lib/textus/maintenance/migrate.rb

@@ -0,0 +1,51 @@
+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
+      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:)
+        kwargs = op_hash.except("op").transform_keys(&:to_sym).merge(dry_run: dry_run)
+        klass = op_class(op_name)
+        klass.new(
+          container: @container, call: @call,
+        ).call(**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