textus 0.26.0 → 0.29.0

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

@@ -41,7 +41,8 @@ module Textus
         @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 +61,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

data/lib/textus/manifest/entry/base.rb

@@ -2,11 +2,10 @@ module Textus
   class Manifest
     class Entry
       class Base < Entry
-        attr_reader :raw, :key, :path, :zone, :schema, :owner, :format, :manifest, :publish_to
+        attr_reader :raw, :key, :path, :zone, :schema, :owner, :format, :publish_to
 
         # rubocop:disable Metrics/ParameterLists, Lint/MissingSuper
-        def initialize(manifest:, raw:, key:, path:, zone:, schema:, owner:, format:, publish_to: [])
-          @manifest = manifest
+        def initialize(raw:, key:, path:, zone:, schema:, owner:, format:, publish_to: [])
           @raw = raw
           @key = key
           @path = path
@@ -18,14 +17,14 @@ module Textus
         end
         # rubocop:enable Metrics/ParameterLists, Lint/MissingSuper
 
-        def zone_writers
-          @manifest.policy.zone_writers(@zone)
+        def zone_writers(policy)
+          policy.zone_writers(@zone)
         rescue UsageError => e
           raise UsageError.new("entry '#{@key}': #{e.message}")
         end
 
-        def in_generator_zone? = @manifest.policy.zone_kinds(@zone).include?(:generator)
-        def in_proposal_zone?  = @manifest.policy.zone_kinds(@zone).include?(:proposer)
+        def in_generator_zone?(policy) = policy.zone_kinds(@zone).include?(:generator)
+        def in_proposal_zone?(policy)  = policy.zone_kinds(@zone).include?(:proposer)
 
         def nested?  = false
         def derived? = false
@@ -41,11 +40,32 @@ module Textus
         def publish_each   = nil
         def index_filename = nil
 
-        PublishContext = Struct.new(
-          :repo_root, :manifest, :file_store, :root, :caps, :rpc, :session, :ctx, :bus, :hook_context,
-          :reader, :emit, # callables: reader.call(key) → envelope; emit.call(event, **payload)
-          keyword_init: true
-        )
+        # Minimal context object passed into entry `publish_via` hooks.
+        # Everything beyond the three primitives is derived. Data.define
+        # instances are frozen, so we recompute per-call rather than
+        # memoizing — RoleScope/Hooks::Context construction is cheap.
+        PublishContext = ::Data.define(:container, :call, :reader) do
+          def manifest   = container.manifest
+          def root       = container.root
+          def repo_root  = File.dirname(container.root)
+          def events     = container.events
+
+          def hook_context
+            Textus::Hooks::Context.new(scope: scope_for_hooks)
+          end
+
+          def emit(event, **payload)
+            events.publish(event, ctx: hook_context, **payload)
+          end
+
+          private
+
+          def scope_for_hooks
+            Textus::RoleScope.new(
+              container: container, role: call.role, dry_run: call.dry_run,
+            )
+          end
+        end
 
         # Subclasses override to customize publish behavior.
         # Default: copy the stored file to each publish_to target.
@@ -59,12 +79,12 @@ module Textus
 
           publish_to.each do |rel|
             target_abs = File.join(pctx.repo_root, rel)
-            Textus::Infra::Publisher.publish(source: source_path, target: target_abs, store_root: pctx.root)
-            pctx.emit.call(:file_published,
-                           key: @key,
-                           envelope: envelope,
-                           source: source_path,
-                           target: target_abs)
+            Textus::Ports::Publisher.publish(source: source_path, target: target_abs, store_root: pctx.root)
+            pctx.emit(:file_published,
+                      key: @key,
+                      envelope: envelope,
+                      source: source_path,
+                      target: target_abs)
           end
 
           { kind: :built, value: { "key" => @key, "path" => source_path, "published_to" => publish_to } }

data/lib/textus/manifest/entry/derived.rb

@@ -20,22 +20,22 @@ module Textus
         def external?   = @source.is_a?(External)
 
         def publish_via(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
-          return nil unless in_generator_zone?
+          return nil unless in_generator_zone?(pctx.manifest.policy)
 
-          target_path = Textus::Application::Write::Materializer.new(
-            ctx: pctx.ctx, caps: pctx.caps, rpc: pctx.rpc, session: pctx.session,
+          target_path = Textus::Write::Materializer.new(
+            container: pctx.container, call: pctx.call,
           ).run(self)
 
           envelope = pctx.reader.call(@key)
           Array(publish_to).each do |rel|
             target_abs = File.join(pctx.repo_root, rel)
-            Textus::Infra::Publisher.publish(source: target_path, target: target_abs, store_root: pctx.root)
-            pctx.emit.call(:file_published, key: @key, envelope: envelope, source: target_path, target: target_abs)
+            Textus::Ports::Publisher.publish(source: target_path, target: target_abs, store_root: pctx.root)
+            pctx.emit(:file_published, key: @key, envelope: envelope, source: target_path, target: target_abs)
           end
 
           src = @source
           selects = src.is_a?(Projection) ? Array(src.select).compact : []
-          pctx.emit.call(:build_completed, key: @key, envelope: envelope, sources: selects)
+          pctx.emit(:build_completed, key: @key, envelope: envelope, sources: selects)
 
           { kind: :built, value: { "key" => @key, "path" => target_path, "published_to" => publish_to } }
         end

data/lib/textus/manifest/entry/nested.rb

@@ -1,5 +1,3 @@
-require_relative "validators/publish_each"
-
 module Textus
   class Manifest
     class Entry
@@ -37,7 +35,7 @@ module Textus
           return nil if @publish_each.nil?
 
           leaves = []
-          @manifest.resolver.enumerate(prefix: @key).each do |row|
+          pctx.manifest.resolver.enumerate(prefix: @key).each do |row|
             next unless row[:manifest_entry].equal?(self)
             next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
 
@@ -49,12 +47,12 @@ module Textus
               )
             end
 
-            Textus::Infra::Publisher.publish(source: row[:path], target: target_abs, store_root: pctx.root)
-            pctx.emit.call(:file_published,
-                           key: row[:key],
-                           envelope: pctx.reader.call(row[:key]),
-                           source: row[:path],
-                           target: target_abs)
+            Textus::Ports::Publisher.publish(source: row[:path], target: target_abs, store_root: pctx.root)
+            pctx.emit(:file_published,
+                      key: row[:key],
+                      envelope: pctx.reader.call(row[:key]),
+                      source: row[:path],
+                      target: target_abs)
             leaves << { "key" => row[:key], "source" => row[:path], "target" => target_abs }
           end
 

data/lib/textus/manifest/entry/parser.rb

@@ -4,7 +4,7 @@ module Textus
       module Parser
         COMPUTE_KINDS = %w[projection external].freeze
 
-        def self.call(manifest, raw)
+        def self.call(raw)
           key = raw["key"] or raise UsageError.new("manifest entry missing key")
           path = raw["path"] or raise UsageError.new("manifest entry '#{key}' missing path")
           zone = raw["zone"] or raise UsageError.new("manifest entry '#{key}' missing zone")
@@ -14,7 +14,7 @@ module Textus
           format = resolve_format(raw, path)
 
           common = {
-            manifest: manifest, raw: raw,
+            raw: raw,
             key: key, path: path, zone: zone,
             schema: raw["schema"], owner: raw["owner"],
             format: format,

data/lib/textus/manifest/entry/validators/events.rb

@@ -3,7 +3,7 @@ module Textus
     class Entry
       module Validators
         module Events
-          def self.call(entry)
+          def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
             pubsub_events = Textus::Hooks::EventBus::EVENTS.keys
             events = entry.events
             events.each_key do |evt|

data/lib/textus/manifest/entry/validators/format_matrix.rb

@@ -3,7 +3,7 @@ module Textus
     class Entry
       module Validators
         module FormatMatrix
-          def self.call(entry)
+          def self.call(entry, policy:)
             begin
               Textus::Entry.for_format(entry.format).validate_path_extension(entry.path, entry.nested?)
             rescue UsageError => e
@@ -17,7 +17,7 @@ module Textus
             has_template = !entry.template.nil?
             is_external  = entry.derived? && entry.external?
             is_intake    = entry.intake?
-            return unless entry.in_generator_zone? && !has_template && !is_external && !is_intake &&
+            return unless entry.in_generator_zone?(policy) && !has_template && !is_external && !is_intake &&
                           %w[markdown text].include?(entry.format) && !entry.nested?
 
             raise UsageError.new("entry '#{entry.key}': #{entry.format} entries in a generator zone require a template")

data/lib/textus/manifest/entry/validators/index_filename.rb

@@ -3,7 +3,7 @@ module Textus
     class Entry
       module Validators
         module IndexFilename
-          def self.call(entry)
+          def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
             # Use raw to detect misuse on non-nested entries (typed attr stubs nil on Base).
             index_filename = entry.nested? ? entry.index_filename : entry.raw["index_filename"]
             return if index_filename.nil?

data/lib/textus/manifest/entry/validators/inject_boot.rb

@@ -3,10 +3,12 @@ module Textus
     class Entry
       module Validators
         module InjectBoot
-          def self.call(entry)
+          def self.call(entry, policy:)
             return unless entry.inject_boot
 
-            raise UsageError.new("entry '#{entry.key}': inject_boot: is only valid on derived entries") unless entry.in_generator_zone?
+            unless entry.in_generator_zone?(policy)
+              raise UsageError.new("entry '#{entry.key}': inject_boot: is only valid on derived entries")
+            end
 
             return unless entry.template.nil?
 

data/lib/textus/manifest/entry/validators/publish_each.rb

@@ -7,7 +7,7 @@ module Textus
           VAR_RE = /\{([a-z]+)\}/
           REQUIRED_DISCRIMINATOR_VARS = %w[leaf basename key].freeze
 
-          def self.call(entry)
+          def self.call(entry, policy: nil) # rubocop:disable Lint/UnusedMethodArgument
             # Use raw to detect misuse on non-nested entries (typed attr stubs nil on Base).
             publish_each = entry.nested? ? entry.publish_each : entry.raw["publish_each"]
             return if publish_each.nil?

data/lib/textus/manifest/entry/validators.rb

@@ -10,8 +10,8 @@ module Textus
           FormatMatrix,
         ].freeze
 
-        def self.run_all(entry)
-          REGISTERED.each { |v| v.call(entry) }
+        def self.run_all(entry, policy:)
+          REGISTERED.each { |v| v.call(entry, policy: policy) }
           nil
         end
       end

data/lib/textus/manifest/entry.rb

@@ -1,11 +1,6 @@
 module Textus
   class Manifest
     class Entry
-      # Re-exported for backward compatibility with callers that referenced these
-      # constants on Entry. Canonical source is the PublishEach validator.
-      PUBLISH_EACH_VARS = Validators::PublishEach::KNOWN_VARS
-      PUBLISH_EACH_VAR_RE = Validators::PublishEach::VAR_RE
-
       # Populated by each Entry::* subclass at load time.
       REGISTRY = {}
     end

data/lib/textus/manifest.rb

@@ -43,17 +43,12 @@ module Textus # rubocop:disable Style/OneClassPerFile
 
       def build(raw, root)
         data = Manifest::Data.parse(raw, root: root)
-        composition = new(
+        new(
           data: data,
           resolver: Manifest::Resolver.new(data),
           policy: data.policy,
           rules: Manifest::Rules.parse(raw["rules"] || []),
         )
-        # Re-point entries' back-reference from Data to the composition
-        # record. Entries call `@manifest.policy.*` / `@manifest.resolver.*`
-        # at use time (see Entry::Base, Entry::Nested).
-        data.entries.each { |e| e.instance_variable_set(:@manifest, composition) }
-        composition
       end
 
       def check_version!(raw, source)

data/lib/textus/mcp/server.rb

@@ -1,5 +1,4 @@
 require "json"
-require "digest"
 
 module Textus
   module MCP
@@ -107,7 +106,7 @@ module Textus
       end
 
       def manifest_etag
-        Digest::SHA256.hexdigest(File.read(File.join(@store.root, "manifest.yaml")))
+        @store.file_store.etag(File.join(@store.root, "manifest.yaml"))
       end
 
       def emit_result(rid, result)

data/lib/textus/mcp/session.rb

@@ -23,9 +23,18 @@ module Textus
         return if observed_etag == @manifest_etag
 
         raise ContractDrift.new(
-          "manifest changed (was #{@manifest_etag[0, 8]}, now #{observed_etag[0, 8]}); re-run boot",
+          "manifest changed (was #{short_etag(@manifest_etag)}, now #{short_etag(observed_etag)}); re-run boot",
         )
       end
+
+      private
+
+      # First 8 hex chars after the "sha256:" prefix — a stable short id for
+      # the drift diagnostic. Tolerates non-prefixed values (delete_prefix is
+      # a no-op when the prefix is absent).
+      def short_etag(etag)
+        etag.to_s.delete_prefix("sha256:")[0, 8]
+      end
     end
   end
 end

data/lib/textus/mcp/tools.rb

@@ -17,11 +17,11 @@ module Textus
       end
 
       def ops_for(session, store)
-        store.session(role: session.role)
+        store.as(session.role)
       end
 
       REGISTRY = {
-        "boot" => ->(_s, store, _a) { Textus::Boot.run(Textus::Session.for(store)) },
+        "boot" => ->(_s, store, _a) { store.boot },
 
         "find" => lambda do |s, store, args|
           ops_for(s, store).list(zone: args["zone"], prefix: args["prefix"])

data/lib/textus/mcp.rb

@@ -1,6 +1,6 @@
 module Textus
   # The agent gate. Stdio JSON-RPC 2.0 server speaking MCP draft 2024-11-05.
-  # Wraps Textus::Session as auto-derived tools. See ADR 0015.
+  # Wraps Textus::RoleScope as auto-derived tools. See ADR 0015.
   module MCP
   end
 end

data/lib/textus/{infra → ports}/audit_log.rb

@@ -3,7 +3,7 @@ require "json"
 require "time"
 
 module Textus
-  module Infra
+  module Ports
     class AuditLog
       DEFAULT_MAX_SIZE = 10_485_760
       DEFAULT_KEEP = 5

data/lib/textus/{infra → ports}/audit_subscriber.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Textus
-  module Infra
+  module Ports
     # Writes an "event_error" audit row when a user hook raises during
     # Hooks::EventBus publish. Attached at Store boot.
     #
@@ -11,7 +11,7 @@ module Textus
     # event subscribers should be able to filter by key glob).
     #
     # Lifecycle audit rows for verb: "put" / "delete" / "rename" are written
-    # by Application::Envelope::Writer directly (it owns the
+    # by Envelope::IO::Writer directly (it owns the
     # audit-append-as-final-step invariant); this subscriber covers the
     # hook-failure case the writer never sees.
     class AuditSubscriber

data/lib/textus/{infra → ports}/build_lock.rb

@@ -3,7 +3,7 @@ require "socket"
 require "time"
 
 module Textus
-  module Infra
+  module Ports
     class BuildLock
       LOCK_FILENAME = ".build.lock"
       MAX_HOLDER_BYTES = 512

data/lib/textus/{infra → ports}/clock.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Infra
+  module Ports
     module Clock
       module_function
 

data/lib/textus/{infra → ports}/publisher.rb

@@ -1,21 +1,21 @@
 require "fileutils"
 
 module Textus
-  module Infra
+  module Ports
     # Publishes built artifacts from the store to repo-relative consumer paths.
     # Publish = copy + sentinel. The in-store file is already the consumer-shaped
     # artifact; no parsing or stripping.
     #
-    # Sentinel I/O is delegated to Textus::Domain::Sentinel. Sentinels live under
-    # `<store_root>/sentinels/` and mirror the target's repo-relative layout so
-    # consumer directories aren't polluted with `.textus-managed.json` siblings.
+    # Sentinel I/O is delegated to Textus::Ports::SentinelStore. Sentinels live
+    # under `<store_root>/sentinels/` and mirror the target's repo-relative layout
+    # so consumer directories aren't polluted with `.textus-managed.json` siblings.
     module Publisher
       def self.publish(source:, target:, store_root:)
         FileUtils.mkdir_p(File.dirname(target))
         refuse_if_unmanaged(target, store_root)
         File.delete(target) if File.symlink?(target)
         FileUtils.cp(source, target)
-        Textus::Domain::Sentinel.write!(target: target, source: source, store_root: store_root)
+        Textus::Ports::SentinelStore.new.write!(target: target, source: source, store_root: store_root)
       end
 
       def self.refuse_if_unmanaged(target, store_root)
@@ -26,7 +26,7 @@ module Textus
       end
 
       def self.managed?(target, store_root)
-        File.exist?(Textus::Domain::Sentinel.sentinel_path(target, store_root))
+        File.exist?(Textus::Ports::SentinelStore.new.sentinel_path(target, store_root))
       end
     end
   end

data/lib/textus/{infra → ports}/refresh/detached.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Infra
+  module Ports
     module Refresh
       module Detached
         module_function
@@ -16,12 +16,12 @@ module Textus
             $stdout.reopen(File::NULL, "w")
             $stderr.reopen(File::NULL, "w")
 
-            lock = Textus::Infra::Refresh::Lock.new(root: store_root, key: key)
+            lock = Textus::Ports::Refresh::Lock.new(root: store_root, key: key)
             exit(0) unless lock.try_acquire
 
             begin
               store = Textus::Store.new(store_root)
-              store.session(role: "runner").refresh(key)
+              store.as("runner").refresh(key)
             rescue StandardError
               # Already logged via :refresh_failed; exit cleanly.
             ensure

data/lib/textus/{infra → ports}/refresh/lock.rb

@@ -1,7 +1,7 @@
 require "fileutils"
 
 module Textus
-  module Infra
+  module Ports
     module Refresh
       class Lock
         def initialize(root:, key:)