textus 0.26.0 → 0.30.0

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
@@ -8,6 +8,10 @@ module Textus
       #
       # No audit, no events, no permission checks — those live one layer up.
       class Reader
+        def self.from(container:)
+          new(file_store: container.file_store, manifest: container.manifest)
+        end
+
         def initialize(file_store:, manifest:)
           @file_store = file_store
           @manifest   = manifest

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,24 @@ 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 self.from(container:, call:)
+          new(
+            file_store: container.file_store, manifest: container.manifest,
+            schemas: container.schemas, audit_log: container.audit_log,
+            call: call, reader: Reader.from(container: container)
+          )
+        end
+
+        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 +64,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 +83,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 +116,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/event_bus.rb

@@ -39,7 +39,12 @@ module Textus
         raise UsageError.new("#{event_sym} is an RPC event; register on RpcRegistry") if RPC_EVENTS.include?(event_sym)
 
         required = EVENTS[event_sym] or raise UsageError.new("unknown event: #{event}")
-        shape_check!(event_sym, required, blk)
+        sig = Signature.new(blk)
+        missing = sig.missing(required)
+        if missing.any?
+          raise UsageError.new("#{event_sym} hooks must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})")
+        end
+
         name = name.to_sym
         raise UsageError.new("#{event_sym} hook '#{name}' already registered") if @pubsub[event_sym].any? { |h| h[:name] == name }
 
@@ -79,8 +84,9 @@ module Textus
       private
 
       def invoke(event, sub, key, kwargs)
-        accepted = filter_kwargs(sub[:callable], kwargs)
+        accepted = Signature.new(sub[:callable]).filter(kwargs)
         error = nil
+        # Thread#kill is unsafe in general but bounded here: post-commit, isolated, only a runaway user hook is affected.
         thread = Thread.new do
           sub[:callable].call(**accepted)
         rescue StandardError => e
@@ -115,24 +121,6 @@ module Textus
         end
       end
 
-      def filter_kwargs(callable, kwargs)
-        params = callable.parameters
-        return kwargs if params.any? { |type, _| type == :keyrest }
-
-        accepted = params.each_with_object([]) { |(t, n), acc| acc << n if %i[key keyreq].include?(t) }
-        kwargs.slice(*accepted)
-      end
-
-      def shape_check!(event, required, blk)
-        provided = blk.parameters.select { |t, _| %i[keyreq key keyrest].include?(t) } # rubocop:disable Style/HashSlice
-        return if provided.any? { |t, _| t == :keyrest }
-
-        missing = required - provided.map { |_, n| n }
-        return if missing.empty?
-
-        raise UsageError.new("#{event} hooks must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})")
-      end
-
       def match?(globs, key)
         return true if globs.nil?
 

data/lib/textus/hooks/rpc_registry.rb

@@ -20,7 +20,10 @@ module Textus
         raise UsageError.new("#{event_sym} is a pubsub event; register on EventBus") if PUBSUB_EVENTS.include?(event_sym)
 
         required = EVENTS[event_sym] or raise UsageError.new("unknown RPC event: #{event}")
-        shape_check!(event_sym, required, blk)
+        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)
 
@@ -33,45 +36,16 @@ module Textus
         @table[event.to_sym][name.to_sym] or raise UsageError.new("unknown #{event}: #{name}")
       end
 
-      # Invoke a registered callable, injecting `caps:` under the kwarg name
-      # the callable declares. Legacy `store:` is rejected (no shim).
+      # Invoke a registered callable, injecting `caps:` only if the callable
+      # declares it (or accepts keyrest). Mis-named kwargs (e.g. the legacy
+      # `caps:`-alternative) are rejected at registration time, not here.
       def invoke(event, name, caps:, **other)
         blk = callable(event, name)
-        params = blk.parameters
-        accepts_keyrest = params.any? { |t, _| t == :keyrest }
-        declared = params.each_with_object([]) { |(t, n), acc| acc << n if %i[key keyreq].include?(t) }
-
-        if declared.include?(:store)
-          raise UsageError.new(
-            "RPC callable for #{event} '#{name}' declares legacy `store:`; rename to `caps:` " \
-            "(Textus::Application::ReadCaps / WriteCaps)",
-          )
-        end
-
+        sig = Signature.new(blk)
         kwargs = other.dup
-        kwargs[:caps] = caps if accepts_keyrest || declared.include?(:caps)
+        kwargs[:caps] = caps if sig.accepts_keyrest? || sig.declared_keys.include?(:caps)
         blk.call(**kwargs)
       end
-
-      private
-
-      def shape_check!(event, required, blk)
-        provided = blk.parameters.select { |t, _| %i[keyreq key keyrest].include?(t) } # rubocop:disable Style/HashSlice
-        return if provided.any? { |t, _| t == :keyrest }
-
-        param_names = provided.map { |_, n| n }
-        # Allow `store:` as a stand-in for `caps:` so registration succeeds;
-        # invoke will raise UsageError when the callable is actually called.
-        effective_required = if param_names.include?(:store)
-                               required.map { |r| r == :caps ? :store : r }
-                             else
-                               required
-                             end
-        missing = effective_required - param_names
-        return if missing.empty?
-
-        raise UsageError.new("#{event} RPC must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})")
-      end
     end
   end
 end

data/lib/textus/hooks/signature.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Textus
+  module Hooks
+    class Signature
+      def initialize(callable)
+        @params = callable.parameters
+      end
+
+      def accepts_keyrest?
+        @params.any? { |type, _| type == :keyrest }
+      end
+
+      def declared_keys
+        @params.each_with_object([]) { |(t, n), acc| acc << n if %i[keyreq key].include?(t) }
+      end
+
+      def missing(required)
+        return [] if accepts_keyrest?
+
+        required - declared_keys
+      end
+
+      def filter(kwargs)
+        return kwargs if accepts_keyrest?
+
+        kwargs.slice(*declared_keys)
+      end
+    end
+  end
+end

data/lib/textus/init.rb

@@ -7,14 +7,15 @@ module Textus
     DEFAULT_MANIFEST = <<~YAML
       version: textus/3
       zones:
-        - { name: identity, write_policy: [human],               read_policy: [all] }
-        - { name: working,  write_policy: [human, agent, runner], read_policy: [all] }
-        - { name: intake,   write_policy: [runner],              read_policy: [all] }
-        - { name: review,   write_policy: [agent, human],        read_policy: [all] }
-        - { name: output,   write_policy: [builder],             read_policy: [all] }
+        - { name: identity, kind: origin,     write_policy: [human],          read_policy: [all] }
+        - { name: working,  kind: origin,     write_policy: [human],          read_policy: [all] }
+        - { name: intake,   kind: quarantine, write_policy: [runner],         read_policy: [all] }
+        - { name: review,   kind: queue,      write_policy: [agent, human],   read_policy: [all] }
+        - { name: output,   kind: derived,    write_policy: [builder],        read_policy: [all] }
       entries:
         - { key: identity.self, path: identity/self.md, zone: identity, schema: null, owner: human:self, kind: leaf }
         - { key: working.notes, path: working/notes,    zone: working,  schema: null, owner: human:self, nested: true, kind: nested }
+        - { key: review.notes,  path: review/notes,     zone: review,   schema: null, owner: agent:self, nested: true, kind: nested }
     YAML
 
     HOOKS_README = <<~MD
@@ -34,7 +35,7 @@ module Textus
         end
 
         reg.on(:transform_rows, :my_source) { |rows:, **| rows.map { |r| r.merge(processed: true) } }
-        reg.on(:validate,       :my_check)  { |store:, **| [] }
+        reg.on(:validate,       :my_check)  { |caps:, **| [] }
         reg.on(:entry_put,      :my_listener, keys: ["working.*"]) { |key:, envelope:, **| }
 
         # Run a side-effect every time textus writes a file to your repo:

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

data/lib/textus/maintenance/rule_lint.rb

@@ -0,0 +1,56 @@
+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
+      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/zone_mv.rb

@@ -0,0 +1,51 @@
+require "yaml"
+
+module Textus
+  module Maintenance
+    # Rename a zone — rewrites the manifest's zones[] entry, rewrites
+    # the `zone:` field on every entry under the old zone, and moves
+    # every file from zones/<old>/ to zones/<new>/.
+    class ZoneMv
+      def initialize(container:, call:)
+        @container = container
+        @call      = call
+        @manifest  = container.manifest
+        @root      = container.root
+      end
+
+      def call(from:, to:, dry_run: false)
+        raise UsageError.new("from and to required") if from.nil? || to.nil? || from.empty? || to.empty?
+        raise UsageError.new("zone '#{from}' not declared") unless @manifest.data.zones.key?(from)
+
+        dest_dir = File.join(@root, "zones", to)
+        raise UsageError.new("destination 'zones/#{to}' already exists") if File.exist?(dest_dir)
+
+        affected_keys = @manifest.data.entries.select { |e| e.zone == from }.map(&:key)
+
+        steps  = [{ "op" => "rename_zone", "from" => from, "to" => to }]
+        steps += affected_keys.map { |k| { "op" => "mv", "from" => k, "to" => "#{to}#{k[from.length..]}" } }
+
+        plan = Plan.new(steps: steps, warnings: [])
+        return plan if dry_run
+
+        rewrite_manifest!(from, to)
+        FileUtils.mv(File.join(@root, "zones", from), dest_dir)
+        plan
+      end
+
+      private
+
+      def rewrite_manifest!(from, to)
+        path = File.join(@root, "manifest.yaml")
+        raw = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: false)
+        raw["zones"].each { |z| z["name"] = to if z["name"] == from }
+        raw["entries"].each do |e|
+          e["zone"] = to if e["zone"] == from
+          e["key"]  = e["key"].sub(/\A#{Regexp.escape(from)}(\.|\z)/, "#{to}\\1")
+          e["path"] = e["path"].sub(%r{\A#{Regexp.escape(from)}(/|\z)}, "#{to}\\1")
+        end
+        File.write(path, YAML.dump(raw))
+      end
+    end
+  end
+end

data/lib/textus/maintenance.rb

@@ -0,0 +1,15 @@
+module Textus
+  # Bulk and structural changes to a textus store. Each use case returns
+  # a Plan when called with dry_run: true, and applies the plan when
+  # called with dry_run: false.
+  module Maintenance
+    # A Plan is a JSON-shaped preview. Steps are op-tagged hashes the
+    # use case knows how to apply. Warnings are strings surfaced to
+    # the operator (skipped keys, ambiguities).
+    Plan = Data.define(:steps, :warnings) do
+      def to_h
+        { "steps" => steps, "warnings" => warnings }
+      end
+    end
+  end
+end

data/lib/textus/manifest/data.rb

@@ -11,7 +11,8 @@ module Textus
     class Data
       AUDIT_DEFAULTS = { max_size: 10_485_760, keep: 5 }.freeze
 
-      attr_reader :raw, :root, :entries, :zones, :zone_readers, :audit_config, :role_mapping, :policy
+      attr_reader :raw, :root, :entries, :zones, :zone_readers, :declared_zone_kinds,
+                  :audit_config, :role_mapping, :policy
 
       def self.validate_key!(key)
         raise UsageError.new("empty key") if key.nil? || key.empty?
@@ -38,10 +39,14 @@ module Textus
           rp = z["read_policy"]
           [z["name"], rp.nil? ? :all : Array(rp)]
         end
+        @declared_zone_kinds = Array(raw["zones"]).to_h do |z|
+          [z["name"], z["kind"]&.to_sym]
+        end
         @audit_config = build_audit_config(raw)
         @role_mapping = RoleKinds.resolve(raw["roles"])
         # Policy is constructed before entries because Entry validators
-        # call `entry.in_generator_zone?` which routes through Policy.
+        # call `entry.in_generator_zone?(policy)` and similar helpers
+        # that take Policy as an argument.
         @policy = Policy.new(self)
         @entries = build_entries(raw)
         validate_declared_keys!
@@ -60,8 +65,8 @@ module Textus
 
       def build_entries(raw)
         Array(raw["entries"]).map do |e|
-          entry = Manifest::Entry::Parser.call(self, e)
-          Manifest::Entry::Validators.run_all(entry)
+          entry = Manifest::Entry::Parser.call(e)
+          Manifest::Entry::Validators.run_all(entry, policy: @policy)
           entry
         end.freeze
       end