textus 0.22.0 → 0.26.0

data/lib/textus/application/write/refresh_worker.rb

@@ -0,0 +1,134 @@
+require "timeout"
+
+module Textus
+  module Application
+    module Write
+      module RefreshWorker
+        FETCH_TIMEOUT_SECONDS = 30
+
+        def self.call(*, session:, ctx:, caps:, **)
+          Impl.new(
+            ctx: ctx, caps: caps,
+            rpc: session.rpc,
+            writer: session.envelope_writer,
+            hook_context: session.hook_context
+          ).call(*, **)
+        end
+
+        class Impl
+          def initialize(ctx:, caps:, rpc:, writer:, hook_context:)
+            @ctx          = ctx
+            @caps         = caps
+            @manifest     = caps.manifest
+            @writer       = writer
+            @events       = caps.events
+            @rpc          = rpc
+            @authorizer   = caps.authorizer
+            @hook_context = hook_context
+          end
+
+          # call(key) is the primary entry; run is kept as an alias for
+          # Orchestrator and RefreshAll which call worker.run(key).
+          def call(key)
+            run(key)
+          end
+
+          def run(key)
+            res = @manifest.resolver.resolve(key)
+            mentry = res.entry
+            path = res.path
+            remaining = res.remaining
+            raise UsageError.new("no intake declared for '#{key}'") unless mentry.is_a?(Textus::Manifest::Entry::Intake)
+
+            before_etag = File.exist?(path) ? Etag.for_file(path) : nil
+            result = fetch_with_events(key, mentry, remaining)
+            persist_and_notify(key, mentry, result, before_etag)
+          end
+
+          private
+
+          def fetch_timeout_for(key)
+            rule = @manifest.rules.for(key)
+            rule&.refresh&.fetch_timeout_seconds || FETCH_TIMEOUT_SECONDS
+          end
+
+          def fetch_with_events(key, mentry, remaining)
+            @events.publish(:refresh_started, ctx: @hook_context, key: key, mode: :sync)
+            call_intake(key, mentry, remaining)
+          end
+
+          def call_intake(key, mentry, remaining)
+            timeout = fetch_timeout_for(key)
+            Timeout.timeout(timeout) do
+              @rpc.invoke(:resolve_intake, mentry.handler,
+                          caps: @caps,
+                          config: mentry.config,
+                          args: { trigger_key: key, leaf_segments: remaining || [] })
+            end
+          rescue Timeout::Error
+            @events.publish(:refresh_failed, ctx: @hook_context, key: key,
+                                             error_class: "Timeout::Error",
+                                             error_message: "intake '#{mentry.handler}' exceeded #{timeout}s")
+            raise UsageError.new("intake '#{mentry.handler}' exceeded #{timeout}s timeout")
+          rescue Textus::Error => e
+            @events.publish(:refresh_failed, ctx: @hook_context, key: key, error_class: e.class.name,
+                                             error_message: e.message)
+            raise
+          rescue StandardError => e
+            @events.publish(:refresh_failed, ctx: @hook_context, key: key, error_class: e.class.name,
+                                             error_message: e.message)
+            raise UsageError.new("intake '#{mentry.handler}' raised: #{e.class}: #{e.message}")
+          end
+
+          def persist_and_notify(key, mentry, result, before_etag)
+            normalized = RefreshWorker.send(:normalize_action_result, result, format: mentry.format)
+            @authorizer.authorize_write!(mentry, role: @ctx.role)
+            envelope = @writer.put(
+              key,
+              mentry: mentry,
+              payload: Textus::Application::Envelope::Writer::Payload.new(
+                meta: normalized[:meta], body: normalized[:body], content: normalized[:content],
+              ),
+            )
+            change = detect_change(before_etag, envelope)
+            @events.publish(:entry_refreshed, ctx: @hook_context, key: key, envelope: envelope, change: change) unless change == :unchanged
+            envelope
+          end
+
+          def detect_change(before_etag, envelope)
+            if before_etag.nil? then :created
+            elsif envelope.etag == before_etag then :unchanged
+            else :updated
+            end
+          end
+        end
+
+        def self.normalize_action_result(res, format:)
+          res = res.transform_keys(&:to_s) if res.is_a?(Hash)
+          res ||= {}
+          meta_val = res["_meta"]
+          body     = res["body"]
+          content  = res["content"]
+
+          case format
+          when "markdown" then { meta: meta_val || {}, body: body.to_s, content: nil }
+          when "text"     then { meta: {}, body: body.to_s, content: nil }
+          when "json", "yaml"
+            if !content.nil?
+              { meta: meta_val || {}, body: nil, content: content }
+            elsif !body.nil?
+              { meta: {}, body: body.to_s, content: nil }
+            else
+              raise Textus::UsageError.new("intake for #{format} returned neither content nor body")
+            end
+          else
+            raise Textus::UsageError.new("unknown format #{format.inspect}")
+          end
+        end
+        private_class_method :normalize_action_result
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:refresh, Textus::Application::Write::RefreshWorker, caps: :write)

data/lib/textus/application/write/reject.rb

@@ -0,0 +1,62 @@
+require_relative "authority_gate"
+
+module Textus
+  module Application
+    module Write
+      module Reject
+        def self.call(*, session:, ctx:, caps:, **)
+          Impl.new(
+            ctx: ctx, caps: caps,
+            writer: session.envelope_writer,
+            hook_context: session.hook_context
+          ).call(*, **)
+        end
+
+        class Impl
+          include AuthorityGate
+
+          def initialize(ctx:, caps:, writer:, hook_context:)
+            @ctx          = ctx
+            @caps         = caps
+            @manifest     = caps.manifest
+            @writer       = writer
+            @events       = caps.events
+            @authorizer   = caps.authorizer
+            @hook_context = hook_context
+          end
+
+          def call(pending_key)
+            assert_accept_authority!("reject")
+
+            mentry = @manifest.resolver.resolve(pending_key).entry
+            unless mentry.in_proposal_zone?
+              raise ProposalError.new("reject: '#{pending_key}' is not in a proposal zone (zone=#{mentry.zone})")
+            end
+
+            env = Textus::Application::Read::Get::Impl.new(
+              ctx: @ctx, caps: @caps,
+            ).call(pending_key)
+            proposal = env.meta&.dig("proposal") or
+              raise ProposalError.new("entry has no proposal block: #{pending_key}")
+            target_key = proposal["target_key"] or
+              raise ProposalError.new("proposal missing target_key")
+
+            Textus::Application::Write::Delete::Impl.new(
+              ctx: @ctx, caps: @caps, writer: @writer,
+              hook_context: @hook_context
+            ).call(pending_key, suppress_events: true)
+
+            @events.publish(:proposal_rejected,
+                            ctx: @hook_context,
+                            key: pending_key,
+                            target_key: target_key)
+
+            { "protocol" => PROTOCOL, "rejected" => pending_key, "target_key" => target_key }
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:reject, Textus::Application::Write::Reject, caps: :write)

data/lib/textus/boot.rb

@@ -26,7 +26,7 @@ module Textus
         "edit files in identity/working zones, then 'textus put KEY --as=#{name}'"
       end,
       proposer: lambda do |name, manifest|
-        authority = manifest.roles_with_kind(:accept_authority).first || "accept_authority"
+        authority = manifest.policy.roles_with_kind(:accept_authority).first || "accept_authority"
         "propose changes by writing review.* entries with --as=#{name} and a 'proposal:' frontmatter block; " \
           "the #{authority} role runs 'textus accept' to apply"
       end,
@@ -39,7 +39,7 @@ module Textus
     }.freeze
 
     def self.write_flows_for(manifest)
-      manifest.role_mapping.each_with_object({}) do |(name, kind), acc|
+      manifest.policy.role_mapping.each_with_object({}) do |(name, kind), acc|
         tmpl = WRITE_FLOW_TEMPLATES[kind]
         acc[name] = tmpl.call(name, manifest) if tmpl
       end
@@ -120,11 +120,11 @@ module Textus
         "summary" => "delta since cursor — changed entries, stale, pending review, doctor summary" },
     ].freeze
 
-    def self.agent_quickstart(manifest, store)
-      proposer_roles = manifest.roles_with_kind(:proposer)
+    def self.agent_quickstart(manifest, session)
+      proposer_roles = manifest.policy.roles_with_kind(:proposer)
       agent_role = proposer_roles.first
 
-      writable_zones = manifest.zones.each_with_object([]) do |(zname, writers), acc|
+      writable_zones = manifest.data.zones.each_with_object([]) do |(zname, writers), acc|
         acc << zname if agent_role && writers.include?(agent_role)
       end
 
@@ -135,7 +135,7 @@ module Textus
         "write_verbs" => agent_role ? ["put KEY --as=#{agent_role} --stdin"] : [],
         "writable_zones" => writable_zones,
         "propose_zone" => propose_zone,
-        "latest_seq" => store.audit_log.latest_seq,
+        "latest_seq" => session.write_caps.audit_log.latest_seq,
       }
     end
 
@@ -144,29 +144,30 @@ module Textus
         "role_resolution" => {
           "summary" => "write role is resolved in order: --as flag, TEXTUS_ROLE env var, .textus/role file, " \
                        "default 'human'",
-          "roles" => manifest.role_mapping.keys,
+          "roles" => manifest.policy.role_mapping.keys,
           "ref" => "SPEC.md §5",
         },
       )
     end
 
-    def self.run(store)
+    def self.run(session)
+      manifest = session.read_caps.manifest
       {
         "protocol" => PROTOCOL_ID,
-        "store_root" => store.root,
-        "zones" => zones_for(store),
-        "entries" => entries_for(store),
-        "hooks" => hooks_for(store),
-        "write_flows" => write_flows_for(store.manifest),
+        "store_root" => session.read_caps.root,
+        "zones" => zones_for(manifest),
+        "entries" => entries_for(manifest),
+        "hooks" => hooks_for(session),
+        "write_flows" => write_flows_for(manifest),
         "cli_verbs" => CLI_VERBS.map(&:dup),
-        "agent_protocol" => agent_protocol(store.manifest),
-        "agent_quickstart" => agent_quickstart(store.manifest, store),
+        "agent_protocol" => agent_protocol(manifest),
+        "agent_quickstart" => agent_quickstart(manifest, session),
         "docs" => { "spec" => "SPEC.md", "example" => "examples/claude-plugin/" },
       }
     end
 
-    def self.zones_for(store)
-      store.manifest.zones.map do |name, writers|
+    def self.zones_for(manifest)
+      manifest.data.zones.map do |name, writers|
         row = { "name" => name, "writers" => Array(writers) }
         purpose = ZONE_PURPOSES[name]
         row["purpose"] = purpose if purpose
@@ -174,9 +175,9 @@ module Textus
       end
     end
 
-    def self.entries_for(store)
-      store.manifest.entries.map do |e|
-        derived = store.manifest.zone_kinds(e.zone).include?(:generator)
+    def self.entries_for(manifest)
+      manifest.data.entries.map do |e|
+        derived = manifest.policy.zone_kinds(e.zone).include?(:generator)
         {
           "key" => e.key,
           "zone" => e.zone,
@@ -192,16 +193,13 @@ module Textus
       end
     end
 
-    def self.hooks_for(store)
-      bus = store.bus
+    def self.hooks_for(session)
       sections = {}
-      Hooks::Bus::EVENTS.each do |event, spec|
-        case spec[:mode]
-        when :rpc
-          sections[event.to_s] = bus.rpc_names(event).map(&:to_s).sort
-        when :pubsub
-          sections[event.to_s] = bus.pubsub_handlers(event).map { |h| h[:name].to_s }.sort
-        end
+      Hooks::RpcRegistry::EVENTS.each_key do |event|
+        sections[event.to_s] = session.rpc.names(event).map(&:to_s).sort
+      end
+      Hooks::EventBus::EVENTS.each_key do |event|
+        sections[event.to_s] = session.events.pubsub_handlers(event).map { |h| h[:name].to_s }.sort
       end
       sections
     end

data/lib/textus/builder/pipeline.rb

@@ -63,7 +63,7 @@ module Textus
       end
 
       # rubocop:disable Metrics/ParameterLists
-      def self.run(mentry:, manifest:, reader:, lister:, transform_resolver:, template_loader:,
+      def self.run(mentry:, manifest:, reader:, lister:, rpc:, template_loader:,
                    transform_context: nil, inject_boot: nil)
         # 1. Load sources + project + reduce
         data =
@@ -72,7 +72,7 @@ module Textus
               reader: reader,
               spec: mentry.source.to_h.transform_keys(&:to_s),
               lister: lister,
-              transform_resolver: transform_resolver,
+              rpc: rpc,
               transform_context: transform_context,
             ).run
           else
@@ -86,7 +86,7 @@ module Textus
         bytes = klass.new(template_loader: template_loader).call(mentry: mentry, data: data)
 
         # 3. Write (idempotent: skip if only generated_at would differ)
-        target_path = Key::Path.resolve(manifest, mentry)
+        target_path = Key::Path.resolve(manifest.data, mentry)
         FileUtils.mkdir_p(File.dirname(target_path))
         write_if_changed(target_path, bytes, mentry.format)
 

data/lib/textus/cli/group/mcp.rb

@@ -0,0 +1,9 @@
+module Textus
+  class CLI
+    class Group
+      class MCP < Group
+        command_name "mcp"
+      end
+    end
+  end
+end

data/lib/textus/cli/group/zone.rb

@@ -0,0 +1,9 @@
+module Textus
+  class CLI
+    class Group
+      class Zone < Group
+        command_name "zone"
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/accept.rb

@@ -8,7 +8,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("accept requires a key")
-          emit(operations_for(store).accept(key))
+          emit(session_for(store).accept(key))
         end
       end
     end

data/lib/textus/cli/verb/audit.rb

@@ -14,8 +14,8 @@ module Textus
         option :limit, "--limit=N"
 
         def call(store)
-          ops = operations_for(store)
-          since_time = since && Textus::Application::Reads::Audit.parse_since(since, now: ops.ctx.now)
+          ops = session_for(store)
+          since_time = since && Textus::Application::Read::Audit.parse_since(since, now: ops.ctx.now)
           rows = ops.audit(
             key: key_filter,
             zone: zone,

data/lib/textus/cli/verb/blame.rb

@@ -8,7 +8,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("blame requires a key")
-          rows = operations_for(store).blame(key: key, limit: limit&.to_i)
+          rows = session_for(store).blame(key: key, limit: limit&.to_i)
           emit({ "verb" => "blame", "key" => key, "rows" => rows })
         end
       end

data/lib/textus/cli/verb/boot.rb

@@ -5,7 +5,7 @@ module Textus
         command_name "boot"
 
         def call(store)
-          emit(Textus::Boot.run(store))
+          emit(Textus::Boot.run(Textus::Session.for(store)))
         end
       end
     end

data/lib/textus/cli/verb/build.rb

@@ -8,8 +8,8 @@ module Textus
 
         def call(store)
           Textus::Infra::BuildLock.with(root: store.root) do
-            role = store.manifest.roles_with_kind(:generator).first || "builder"
-            ops = Textus::Operations.for(store, role: role)
+            role = store.manifest.policy.roles_with_kind(:generator).first || "builder"
+            ops = store.session(role: role)
             result = ops.publish(prefix: prefix)
             emit(result)
           end

data/lib/textus/cli/verb/delete.rb

@@ -9,7 +9,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("delete requires a key")
-          emit(operations_for(store).delete(key, if_etag: if_etag))
+          emit(session_for(store).delete(key, if_etag: if_etag))
         end
       end
     end

data/lib/textus/cli/verb/deps.rb

@@ -6,7 +6,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("deps requires a key")
-          emit({ "key" => key, "deps" => operations_for(store).deps(key) })
+          emit({ "key" => key, "deps" => session_for(store).deps(key) })
         end
       end
     end

data/lib/textus/cli/verb/doctor.rb

@@ -8,7 +8,7 @@ module Textus
 
         def call(store)
           check_list = checks&.split(",")&.map(&:strip)
-          res = Textus::Doctor.run(store, checks: check_list)
+          res = Textus::Doctor.run(Textus::Session.for(store), checks: check_list)
           emit(res, exit_code: res["ok"] ? 0 : 1)
         end
       end

data/lib/textus/cli/verb/freshness.rb

@@ -8,7 +8,7 @@ module Textus
         option :zone, "--zone=Z"
 
         def call(store)
-          rows = operations_for(store).freshness(prefix: prefix, zone: zone)
+          rows = session_for(store).freshness(prefix: prefix, zone: zone)
           emit({ "verb" => "freshness", "rows" => rows })
         end
       end

data/lib/textus/cli/verb/get.rb

@@ -8,7 +8,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("get requires a key")
-          result = operations_for(store).get_or_refresh(key)
+          result = session_for(store).get_or_refresh(key)
           raise Textus::UnknownKey.new(key, suggestions: store.manifest.resolver.suggestions_for(key)) if result.nil?
 
           emit(result.to_h_for_wire)

data/lib/textus/cli/verb/hook_run.rb

@@ -27,15 +27,14 @@ module Textus
           end
 
           Role.resolve(flag: as_flag, env: ENV, root: store.root)
-          callable = store.bus.rpc_callable(:resolve_intake, name)
 
           begin
-            Timeout.timeout(Textus::Application::Refresh::Worker::FETCH_TIMEOUT_SECONDS) do
-              callable.call(config: {}, store: store, args: args)
+            Timeout.timeout(Textus::Application::Write::RefreshWorker::FETCH_TIMEOUT_SECONDS) do
+              store.rpc.invoke(:resolve_intake, name, caps: nil, config: {}, args: args)
             end
           rescue Timeout::Error
             raise UsageError.new(
-              "hook run '#{name}' exceeded #{Textus::Application::Refresh::Worker::FETCH_TIMEOUT_SECONDS}s timeout",
+              "hook run '#{name}' exceeded #{Textus::Application::Write::RefreshWorker::FETCH_TIMEOUT_SECONDS}s timeout",
             )
           rescue Textus::Error
             raise

data/lib/textus/cli/verb/hooks.rb

@@ -16,22 +16,19 @@ module Textus
           end
 
           rows = []
-          Textus::Hooks::Bus::EVENTS.each do |event, spec|
-            mode = spec[:mode].to_s
-            case spec[:mode]
-            when :rpc
-              store.bus.rpc_names(event).each do |name|
-                rows << { "event" => event.to_s, "mode" => mode, "name" => name.to_s }
-              end
-            when :pubsub
-              store.bus.pubsub_handlers(event).each do |h|
-                row = { "event" => event.to_s, "mode" => mode, "name" => h[:name].to_s }
-                row["keys"] = Array(h[:keys]) if h[:keys]
-                rows << row
-              end
+          Textus::Hooks::RpcRegistry::EVENTS.each_key do |event|
+            store.rpc.names(event).each do |name|
+              rows << { "event" => event.to_s, "mode" => "rpc", "name" => name.to_s }
+            end
+          end
+          Textus::Hooks::EventBus::EVENTS.each_key do |event|
+            store.events.pubsub_handlers(event).each do |h|
+              row = { "event" => event.to_s, "mode" => "pubsub", "name" => h[:name].to_s }
+              row["keys"] = Array(h[:keys]) if h[:keys]
+              rows << row
             end
           end
-          store.manifest.entries.each do |e|
+          store.manifest.data.entries.each do |e|
             (e.respond_to?(:events) ? e.events : {}).each do |evt, defs|
               Array(defs).each do |defn|
                 next unless defn["exec"]

data/lib/textus/cli/verb/key_delete.rb

@@ -0,0 +1,24 @@
+module Textus
+  class CLI
+    class Verb
+      class KeyDelete < Verb
+        command_name "delete"
+        parent_group Group::Key
+
+        option :as_flag, "--as=ROLE"
+        option :dry_run, "--dry-run"
+        option :prefix, "--prefix"
+
+        def call(store)
+          if prefix
+            p = positional.shift or raise UsageError.new("key delete --prefix requires <prefix>")
+            emit(session_for(store).key_delete_prefix(prefix: p, dry_run: dry_run || false).to_h)
+          else
+            key = positional.shift or raise UsageError.new("key delete requires <key>")
+            emit(session_for(store).delete(key))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/list.rb

@@ -8,7 +8,7 @@ module Textus
         option :zone, "--zone=Z"
 
         def call(store)
-          emit({ "entries" => operations_for(store).list(prefix: prefix, zone: zone) })
+          emit({ "entries" => session_for(store).list(prefix: prefix, zone: zone) })
         end
       end
     end

data/lib/textus/cli/verb/mcp_serve.rb

@@ -0,0 +1,17 @@
+module Textus
+  class CLI
+    class Verb
+      # Launches the MCP stdio server in the current process. Blocks on
+      # stdin; never returns until stdin closes.
+      class MCPServe < Verb
+        command_name "serve"
+        parent_group Group::MCP
+
+        def call(store)
+          Textus::MCP::Server.new(store: store, stdin: @stdin, stdout: @stdout).run
+          0
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/migrate.rb

@@ -0,0 +1,18 @@
+module Textus
+  class CLI
+    class Verb
+      class Migrate < Verb
+        command_name "migrate"
+
+        option :as_flag, "--as=ROLE"
+        option :dry_run, "--dry-run"
+
+        def call(store)
+          path = positional.shift or raise UsageError.new("migrate requires <plan.yaml>")
+          plan_yaml = File.read(path)
+          emit(session_for(store).migrate(plan_yaml: plan_yaml, dry_run: dry_run || false).to_h)
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/mv.rb

@@ -7,11 +7,19 @@ module Textus
 
         option :as_flag, "--as=ROLE"
         option :dry_run, "--dry-run"
+        option :prefix, "--prefix"
 
         def call(store)
-          old_key = positional.shift or raise UsageError.new("mv requires <old-key> <new-key>")
-          new_key = positional.shift or raise UsageError.new("mv requires <old-key> <new-key>")
-          emit(operations_for(store).mv(old_key, new_key, dry_run: dry_run || false))
+          if prefix
+            from_p = positional.shift or raise UsageError.new("mv --prefix requires <from-prefix> <to-prefix>")
+            to_p   = positional.shift or raise UsageError.new("mv --prefix requires <from-prefix> <to-prefix>")
+            emit(session_for(store).key_mv_prefix(from_prefix: from_p, to_prefix: to_p,
+                                                  dry_run: dry_run || false).to_h)
+          else
+            old_key = positional.shift or raise UsageError.new("mv requires <old-key> <new-key>")
+            new_key = positional.shift or raise UsageError.new("mv requires <old-key> <new-key>")
+            emit(session_for(store).mv(old_key, new_key, dry_run: dry_run || false))
+          end
         end
       end
     end

data/lib/textus/cli/verb/published.rb

@@ -5,7 +5,7 @@ module Textus
         command_name "published"
 
         def call(store)
-          emit({ "published" => operations_for(store).published })
+          emit({ "published" => session_for(store).published })
         end
       end
     end

data/lib/textus/cli/verb/pulse.rb

@@ -7,7 +7,7 @@ module Textus
         option :since, "--since=N"
 
         def call(store)
-          ops = operations_for(store)
+          ops = session_for(store)
           since_n = (since || "0").to_i
           emit(ops.pulse(since: since_n))
         end