textus 0.20.2 → 0.26.0

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

@@ -0,0 +1,49 @@
+module Textus
+  module Application
+    module Write
+      module Put
+        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
+          def initialize(ctx:, caps:, writer:, hook_context:)
+            @ctx          = ctx
+            @manifest     = caps.manifest
+            @events       = caps.events
+            @authorizer   = caps.authorizer
+            @writer       = writer
+            @hook_context = hook_context
+          end
+
+          def call(key, meta: nil, body: nil, content: nil, if_etag: nil)
+            Textus::Manifest::Data.validate_key!(key)
+            mentry = @manifest.resolver.resolve(key).entry
+
+            @authorizer.authorize_write!(mentry, role: @ctx.role)
+
+            envelope = @writer.put(
+              key,
+              mentry: mentry,
+              payload: Textus::Application::Envelope::Writer::Payload.new(meta: meta, body: body, content: content),
+              if_etag: if_etag,
+            )
+
+            @events.publish(:entry_put,
+                            ctx: @hook_context,
+                            key: key,
+                            envelope: envelope)
+
+            envelope
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:put, Textus::Application::Write::Put, caps: :write)

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

@@ -0,0 +1,63 @@
+module Textus
+  module Application
+    module Write
+      module RefreshAll
+        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
+            @rpc          = rpc
+            @writer       = writer
+            @hook_context = hook_context
+          end
+
+          def call(prefix: nil, zone: nil)
+            worker = Textus::Application::Write::RefreshWorker::Impl.new(
+              ctx: @ctx, caps: @caps, rpc: @rpc, writer: @writer,
+              hook_context: @hook_context
+            )
+
+            stale_rows = Textus::Application::Read::Stale::Impl.new(caps: @caps).call(prefix: prefix, zone: zone)
+            refreshed = []
+            failed = []
+            skipped = []
+
+            stale_rows.each do |row|
+              key = row["key"] || row[:key]
+              reason = row["reason"] || row[:reason]
+              if reason.to_s.match?(/ttl exceeded|never refreshed/)
+                begin
+                  worker.run(key)
+                  refreshed << key
+                rescue Textus::Error => e
+                  failed << { "key" => key, "error" => e.message }
+                end
+              else
+                skipped << { "key" => key, "reason" => reason }
+              end
+            end
+
+            {
+              "protocol" => Textus::PROTOCOL,
+              "ok" => failed.empty?,
+              "refreshed" => refreshed,
+              "failed" => failed,
+              "skipped" => skipped,
+            }
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:refresh_all, Textus::Application::Write::RefreshAll, caps: :write)

data/lib/textus/application/{refresh/orchestrator.rb → write/refresh_orchestrator.rb}

@@ -1,12 +1,11 @@
 module Textus
   module Application
-    module Refresh
-      class Orchestrator
-        def initialize(worker:, store_root:, bus: nil, store: nil, ctx: nil, hook_context: nil, detached_spawner: nil) # rubocop:disable Metrics/ParameterLists
+    module Write
+      class RefreshOrchestrator
+        def initialize(worker:, store_root:, events:, ctx: nil, hook_context: nil, detached_spawner: nil)
           @worker       = worker
           @store_root   = store_root
-          @bus          = bus
-          @store        = store
+          @events       = events
           @ctx          = ctx
           @hook_context = hook_context
           @detached_spawner = detached_spawner || default_spawner
@@ -31,12 +30,37 @@ module Textus
         end
 
         def run_timed(budget_ms, key)
-          unless Textus::Infra::Refresh::Detached.supported?
+          return run_timed_with_fork(budget_ms, key) if Textus::Infra::Refresh::Detached.supported?
+
+          run_timed_cooperative(budget_ms, key)
+        end
+
+        def run_timed_cooperative(budget_ms, key)
+          result = nil
+          thread = Thread.new do
+            result = @worker.run(key)
+          rescue Textus::Error => e
+            result = e
+          end
+
+          thread.join(budget_ms / 1000.0)
+          if thread.alive?
+            thread.kill
             return Textus::Domain::Outcome::Failed.new(
-              error: Textus::UsageError.new("timed_sync requires fork (Unix only)"),
+              error: Textus::UsageError.new(
+                "refresh exceeded budget #{budget_ms}ms (no fork available — cooperative cancel)",
+              ),
             )
           end
 
+          if result.is_a?(Textus::Error)
+            Textus::Domain::Outcome::Failed.new(error: result)
+          else
+            Textus::Domain::Outcome::Refreshed.new(envelope: result)
+          end
+        end
+
+        def run_timed_with_fork(budget_ms, key)
           result = nil
           thread = Thread.new do
             result = @worker.run(key)
@@ -59,7 +83,7 @@ module Textus
 
             payload = { key: key, started_at: Time.now.utc.iso8601, budget_ms: budget_ms }
             payload[:ctx] = @hook_context if @hook_context
-            @bus&.publish(:refresh_backgrounded, **payload)
+            @events.publish(:refresh_backgrounded, **payload)
             @detached_spawner.call(store_root: @store_root, key: key)
             Textus::Domain::Outcome::Detached.new
           elsif result.is_a?(Textus::Error)

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/{intro.rb → boot.rb}

@@ -4,8 +4,8 @@ module Textus
   # project: zones and their write authority, entries and their flags,
   # registered hooks, write flows, and the CLI verb catalog.
   #
-  # Intro is side-effect-free.
-  module Intro
+  # Boot is side-effect-free.
+  module Boot
     PROTOCOL_ID = PROTOCOL
 
     # Conventional zone purposes. Unknown zones (declared in the manifest
@@ -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
@@ -95,10 +95,10 @@ module Textus
     }.freeze
 
     # The CLI verb catalog. Truth lives here; do not derive dynamically.
-    # Agents that read intro should see a stable shape regardless of how
+    # Agents that read boot should see a stable shape regardless of how
     # verb implementations evolve.
     CLI_VERBS = [
-      { "name" => "intro",    "summary" => "this output — orientation for agents and tools" },
+      { "name" => "boot",     "summary" => "this output — orientation for agents and tools" },
       { "name" => "list",     "summary" => "enumerate keys (optional --prefix)" },
       { "name" => "get",      "summary" => "read an entry; envelope with _meta, body, uid, etag" },
       { "name" => "where",    "summary" => "resolve a key to its zone and path without reading" },
@@ -116,35 +116,58 @@ module Textus
       { "name" => "doctor", "summary" => "health-check the store (missing schemas, illegal keys, sentinel drift, etc.)" },
       { "name" => "hook",
         "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
+      { "name" => "pulse",
+        "summary" => "delta since cursor — changed entries, stale, pending review, doctor summary" },
     ].freeze
 
+    def self.agent_quickstart(manifest, session)
+      proposer_roles = manifest.policy.roles_with_kind(:proposer)
+      agent_role = proposer_roles.first
+
+      writable_zones = manifest.data.zones.each_with_object([]) do |(zname, writers), acc|
+        acc << zname if agent_role && writers.include?(agent_role)
+      end
+
+      propose_zone = writable_zones.find { |z| z.include?("review") } || writable_zones.first
+
+      {
+        "read_verbs" => %w[boot get list audit pulse freshness doctor],
+        "write_verbs" => agent_role ? ["put KEY --as=#{agent_role} --stdin"] : [],
+        "writable_zones" => writable_zones,
+        "propose_zone" => propose_zone,
+        "latest_seq" => session.write_caps.audit_log.latest_seq,
+      }
+    end
+
     def self.agent_protocol(manifest)
       AGENT_PROTOCOL_TEMPLATE.merge(
         "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_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
@@ -152,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,
@@ -165,21 +188,18 @@ module Textus
           "derived" => derived,
           "intake" => e.is_a?(Textus::Manifest::Entry::Intake),
           "publish_to" => Array(e.publish_to),
-          "publish_each" => e.respond_to?(:publish_each) ? e.publish_each : nil,
+          "publish_each" => e.publish_each,
         }
       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,8 +63,8 @@ module Textus
       end
 
       # rubocop:disable Metrics/ParameterLists
-      def self.run(mentry:, manifest:, reader:, lister:, transform_resolver:, template_loader:,
-                   transform_context: nil, inject_intro: nil)
+      def self.run(mentry:, manifest:, reader:, lister:, rpc:, template_loader:,
+                   transform_context: nil, inject_boot: nil)
         # 1. Load sources + project + reduce
         data =
           if mentry.is_a?(Textus::Manifest::Entry::Derived) && mentry.projection?
@@ -72,13 +72,13 @@ 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
             { "entries" => [], "count" => 0, "generated_at" => Time.now.utc.iso8601 }
           end
-        data = data.merge("intro" => inject_intro.call) if mentry.inject_intro && inject_intro
+        data = data.merge("boot" => inject_boot.call) if mentry.inject_boot && inject_boot
 
         # 2. Render
         klass = renderers[mentry.format] or
@@ -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

@@ -9,18 +9,20 @@ module Textus
         option :role_filter, "--role=ROLE"
         option :verb_filter, "--verb=V"
         option :since, "--since=ISO8601|RELATIVE"
+        option :seq_since, "--seq-since=N"
         option :correlation_id, "--correlation-id=ID"
         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,
             role: role_filter,
             verb: verb_filter,
             since: since_time,
+            seq_since: seq_since&.to_i,
             correlation_id: correlation_id,
             limit: limit&.to_i,
           )

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

@@ -0,0 +1,13 @@
+module Textus
+  class CLI
+    class Verb
+      class Boot < Verb
+        command_name "boot"
+
+        def call(store)
+          emit(Textus::Boot.run(Textus::Session.for(store)))
+        end
+      end
+    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