textus 0.55.1 → 0.56.0

data/lib/textus/surface/cli/verb/put.rb

@@ -3,20 +3,22 @@ module Textus
     class CLI
       class Verb
         class Put < Runner::Base
-          self.spec = Textus::Action::Put.contract
+          self.spec = Textus::Protocol::VerbRegistry.for(:put)
           option :as_flag, "--as=ROLE"
           option :use_stdin, "--stdin"
+          option :as_format, "--as-format=FORMAT"
 
           def invoke(store)
             key = positional.shift or raise UsageError.new("put requires a key")
             raise UsageError.new("put requires --stdin in v1") unless use_stdin
 
             payload = JSON.parse(@stdin.read)
-            spec = Textus::Action::Put.contract
-            inputs = { key: key, meta: payload["_meta"] || {}, body: payload["body"] || "",
-                       content: nil, if_etag: payload["if_etag"] }
-            result = store.gate.dispatch(spec: spec, inputs: inputs, role: resolved_role(store), surface: :cli)
-            emit(result)
+            Textus::Protocol::VerbRegistry.for(:put)
+            inputs = { key: key, meta: payload["_meta"] || {}, data: payload["data"],
+                       if_etag: payload["if_etag"] }
+            inputs[:format] = as_format if as_format
+            s = store.with_role(resolved_role(store))
+            emit(s.put(**inputs))
           end
         end
       end

data/lib/textus/surface/cli/verb/web_serve.rb

@@ -0,0 +1,22 @@
+module Textus
+  module Surface
+    class CLI
+      class Verb
+        class WebServe < Verb
+          command_name "serve"
+          parent_group Group::Web
+          option :as_flag, "--as=ROLE"
+          option :port, "--port=N"
+
+          def call(store)
+            role = resolved_role(store, default: Textus::Value::Role::AGENT)
+            Textus::Surface::Web.set :textus_session, store.with_role(role)
+            Textus::Surface::Web.set :port, (port || 9292).to_i
+            Textus::Surface::Web.run!
+            0
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/surface/cli.rb

@@ -40,7 +40,7 @@ module Textus
         # `textus hook list --root=X`). Without this, `order!` below only sees
         # options before the first verb token, so a trailing `--root` reached the
         # verb's own parser and raised InvalidOption (#161 F5). TEXTUS_ROOT already
-        # works everywhere via Store.discover, so this brings the flag to parity.
+        # works everywhere via Session, so this brings the flag to parity.
         @root_arg = extract_root!(argv)
 
         # Define --version/--help ourselves so OptionParser doesn't intercept them
@@ -99,7 +99,29 @@ module Textus
       end
 
       def store
-        @store ||= Store.discover(@cwd, root: @root_arg)
+        @store ||= Textus::Protocol::Session.open(store_root)
+      end
+
+      def store_root
+        @store_root ||= explicit_root || discovered_root
+      end
+
+      def explicit_root
+        @root_arg || ENV.fetch("TEXTUS_ROOT", nil)
+      end
+
+      def discovered_root
+        dir = File.expand_path(@cwd)
+        loop do
+          if File.directory?(File.join(dir, ".textus")) && File.exist?(File.join(dir, ".textus", "manifest.yaml"))
+            return File.join(dir, ".textus")
+          end
+
+          parent = File.dirname(dir)
+          raise Textus::IoError.new("no .textus directory found from #{@cwd}") if parent == dir
+
+          dir = parent
+        end
       end
 
       def dispatch(klass, argv)
@@ -131,14 +153,11 @@ module Textus
             textus blame KEY [--limit=N]
             textus pulse [--since=N]
             textus boot
-            textus doctor
             textus drain [PREFIX] --as=ROLE
             textus watch
-            textus jobs
-
             textus key {delete,mv,mv-prefix,delete-prefix,uid}
             textus rule {explain,lint,list}
-            textus schema {diff,init,migrate,show}
+            textus schema {show}
             textus data {mv}
             textus mcp {serve}
         HELP

data/lib/textus/surface/dispatch.rb

@@ -0,0 +1,17 @@
+module Textus
+  module Surface
+    module Dispatch
+      module_function
+
+      def call(session, verb_name, raw_args = nil, **bound)
+        if raw_args
+          spec = Textus::Protocol::VerbRegistry.for(verb_name.to_sym)
+          raise Textus::UsageError.new("unknown verb: #{verb_name}") unless spec
+
+          bound = Textus::Protocol::Binder.inputs_from_wire(spec, raw_args)
+        end
+        session.public_send(verb_name.to_sym, **bound)
+      end
+    end
+  end
+end

data/lib/textus/surface/mcp/adapters/mcp_adapter.rb

@@ -0,0 +1,28 @@
+module Textus
+  module Surface
+    module MCP
+      module Adapters
+        class McpAdapter
+          def server(name:, version:, tools:, resources:, server_context:)
+            ::MCP::Server.new(
+              name: name,
+              version: version,
+              tools: tools,
+              resources: resources,
+              server_context: server_context,
+            )
+          end
+
+          def tool(name:, description:, input_schema:, &)
+            ::MCP::Tool.define(
+              name: name,
+              description: description,
+              input_schema: input_schema,
+              &
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/surface/mcp/catalog.rb

@@ -1,89 +1,53 @@
 module Textus
   module Surface
     module MCP
-      # Derives the entire MCP tool surface from the per-verb contracts (ADR 0039).
-      # `build_tools` builds MCP::Tool instances for the SDK; `call` is the generic
-      # dispatch: map JSON args -> (positional, keyword) per the contract, invoke
-      # the verb through the role scope, then shape the return value. No per-tool code.
       module Catalog
-        PROJECTOR = Projector.new(view_key: :default, binder_method: :inputs_from_wire).freeze
+        MCP_ADAPTER = Textus::Surface::MCP::Adapters::McpAdapter.new
 
         module_function
 
-        WRITE_VERBS = %i[
-          put propose key_delete key_mv accept reject enqueue
-        ].freeze
-
-        MAINTENANCE_VERBS = %i[
-          data_mv key_mv_prefix key_delete_prefix drain rule_lint
-        ].freeze
-
-        # Contracts of every MCP-surfaced verb, in Dispatcher order.
         def specs
-          Textus::Action::VERBS.values
-                               .select { |k| mcp_surfaced?(k) }
-                               .map(&:contract)
+          Textus::Protocol::VerbRegistry.registered.select(&:mcp?)
         end
 
-        # Builds MCP::Tool instances for the SDK, bound to mcp_server.dispatch.
         def build_tools(mcp_server)
-          Textus::Action::VERBS
-            .select { |_, klass| mcp_surfaced?(klass) }
-            .map do |name, action|
-              schema = action.contract.input_schema
-              schema = schema.reject { |k, v| k == :required && Array(v).empty? }
-              ::MCP::Tool.define(
-                name: name.to_s,
-                description: action.contract.summary,
-                input_schema: schema,
-              ) do |server_context:, **args|
-                mcp_server.dispatch(name, args, server_context)
-              end
+          specs.map do |spec|
+            schema = spec.input_schema
+            schema = schema.reject { |k, v| k == :required && Array(v).empty? }
+            MCP_ADAPTER.tool(
+              name: spec.verb.to_s,
+              description: spec.summary,
+              input_schema: schema,
+            ) do |server_context:, **args|
+              mcp_server.dispatch(spec.verb, args, server_context)
             end
+          end
         end
 
         def names
-          PROJECTOR.names(
-            Textus::Action::VERBS.select { |_, klass| mcp_surfaced?(klass) },
-          )
+          specs.map(&:verb).map(&:to_s)
         end
 
-        # MCP-surfaced read verbs, by Dispatcher class namespace — the agent's
-        # real read/discovery surface. `boot.agent_quickstart.read_verbs` derives
-        # from this so it can never advertise a verb the agent cannot call, nor
-        # omit one it can (ADR 0056). Excludes write/maintenance verbs by verb
-        # identity (routing may be legacy UseCases or Dispatch::Actions).
         def read_verbs
-          Textus::Action::VERBS
-            .reject { |verb, _klass| WRITE_VERBS.include?(verb) || MAINTENANCE_VERBS.include?(verb) }
-            .select { |_verb, klass| mcp_surfaced?(klass) }
-            .keys.map(&:to_s)
+          Textus::Protocol::VerbRegistry.registered
+                                        .select { |s| s.read? && s.mcp? }
+                                        .map { |s| s.verb.to_s }
         end
 
-        # MCP-surfaced write verbs, by Dispatcher class namespace — the mirror of
-        # read_verbs for the write side. `boot.agent_quickstart.write_verbs` derives
-        # from this so it advertises bare verb names the agent can call (no `--as`/
-        # `--stdin` CLI framing), finishing the de-CLI-ing of the agent surface
-        # (ADR 0056, ADR 0057).
         def write_verbs
-          Textus::Action::VERBS
-            .select { |verb, klass| WRITE_VERBS.include?(verb) && mcp_surfaced?(klass) }
-            .keys.map(&:to_s)
-        end
-
-        def mcp_surfaced?(klass)
-          klass.respond_to?(:contract?) && klass.contract? && klass.contract.mcp?
+          Textus::Protocol::VerbRegistry.registered
+                                        .select { |s| s.write? && s.mcp? }
+                                        .map { |s| s.verb.to_s }
         end
 
-        def call(name, session:, store:, args:)
-          klass = Textus::Action::VERBS[name.to_sym]
-          raise ToolError.new("unknown tool: #{name}") unless klass && mcp_surfaced?(klass)
+        def call(name, store:, args:)
+          spec = Textus::Protocol::VerbRegistry.for(name.to_sym)
+          raise ToolError.new("unknown tool: #{name}") unless spec&.mcp?
 
-          PROJECTOR.dispatch(name, inputs: args, store:, role: session.role, session:)
-        rescue Textus::Gate::MissingArgs => e
-          spec = klass.contract
-          raise ToolError.new("#{spec.verb}: missing #{e.missing.map { |a| a.wire.to_s }.join(", ")}")
-        rescue Textus::ContractDrift, CursorExpired
+          Textus::Surface::Dispatch.call(store, name.to_sym, args)
+        rescue Textus::Protocol::MissingArgs => e
+          raise ToolError.new("#{name}: missing #{e.missing.map { |a| a.wire.to_s }.join(", ")}")
+        rescue Textus::ContractDrift, Textus::CursorExpired
           raise
         rescue Textus::Error => e
           raise ToolError.new("#{name}: #{e.message}")

data/lib/textus/surface/mcp/cursor_manager.rb

@@ -0,0 +1,22 @@
+module Textus
+  module Surface
+    module MCP
+      class CursorManager
+        def initialize(store:, role:)
+          @store = store
+          @role = role
+        end
+
+        def resume!
+          saved = @store.container.store.cursor_store.get(@role)[:seq]
+          latest = @store.container.store.audit_log.latest[:seq]
+          @store.advance_cursor(saved) if saved.positive? && saved <= latest
+        end
+
+        def advance!(seq:)
+          @store.advance_cursor(seq)
+        end
+      end
+    end
+  end
+end

data/lib/textus/surface/mcp/drift_annotation.rb

@@ -0,0 +1,19 @@
+module Textus
+  module Surface
+    module MCP
+      module DriftAnnotation
+        module_function
+
+        def apply(result, verb_name:, drifted:, is_read:, current_etag:, previous_etag:)
+          result["contract_drifted"] = drifted if verb_name == :pulse
+
+          if drifted && !is_read && verb_name != :boot
+            result["_warning"] = "contract drifted (was #{previous_etag}, now #{current_etag}); call boot() to re-arm"
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/textus/surface/mcp/errors.rb

@@ -1,16 +1,6 @@
 module Textus
   module Surface
     module MCP
-      # Audit cursor fell off the keep window. Client should re-boot and
-      # resume from the new latest_seq.
-      class CursorExpired < Textus::Error
-        JSONRPC_CODE = -32_002
-
-        def initialize(message, details: {})
-          super("cursor_expired", message, details: details)
-        end
-      end
-
       # Tool execution failed (validation, authorization, IO). Wraps an
       # underlying Textus::Error or generic StandardError.
       class ToolError < Textus::Error

data/lib/textus/surface/mcp/server.rb

@@ -1,30 +1,22 @@
-# frozen_string_literal: true
-
 require "mcp"
 
 module Textus
   module Surface
     module MCP
-      # MCP stdio server backed by the official mcp gem. The SDK owns protocol
-      # negotiation, tool dispatch, and JSON-RPC framing. This class owns the
-      # textus Session lifecycle (built lazily on first tool call) and delegates
-      # execution to Catalog.
       class Server
+        CHECKPOINT_INTERVAL = 30
+        MCP_ADAPTER = Textus::Surface::MCP::Adapters::McpAdapter.new
+
         def initialize(store:, role: Textus::Value::Role::DEFAULT, stdin: $stdin, stdout: $stdout)
-          @store  = store
-          @role   = role
+          @store  = store.with_role(role)
           @stdin  = stdin
           @stdout = stdout
-          # Session built eagerly so the contract_etag is captured at server start.
-          # Changes to manifest/hooks/schemas after this point are detected as drift.
-          @session = Textus::Store::Session.new(
-            role: @role,
-            cursor: @store.audit_log.latest_seq,
-            propose_lane: @store.manifest.policy.propose_lane_for(@role),
-            contract_etag: contract_etag_now,
-          )
+          @shutdown = false
+          @cursor_manager = CursorManager.new(store: @store, role:)
 
-          @sdk = ::MCP::Server.new(
+          @store = @cursor_manager.resume! || @store
+
+          @sdk = MCP_ADAPTER.server(
             name: "textus",
             version: Textus::VERSION,
             tools: Catalog.build_tools(self),
@@ -34,7 +26,6 @@ module Textus
           @sdk.resources_read_handler { |params, server_context:| handle_resource_read(params[:uri].to_s, server_context) }
         end
 
-        # Runs the stdio line loop; delegates each JSON line to the SDK.
         def run
           @stdin.each_line do |line|
             line = line.strip
@@ -48,55 +39,63 @@ module Textus
           end
         end
 
-        # Called from every MCP::Tool handler block in Catalog.
-        # The SDK parses JSON with symbolize_names: true — all nested keys are symbols.
-        # Deep-stringify so Catalog.call receives the string-key format it expects.
         def dispatch(verb_name, args, _server_context)
           str_args = deep_stringify_keys(args)
-          @session.check_etag!(contract_etag_now) unless Catalog.read_verbs.include?(verb_name.to_s)
-          result = Catalog.call(verb_name.to_s, session: @session, store: @store, args: str_args)
-          update_session_for(verb_name.to_s)
+          drifted = drift_detected?
+
+          result = Catalog.call(verb_name.to_s, store: @store, args: str_args)
+          result = DriftAnnotation.apply(
+            result, verb_name:, drifted:, is_read: Catalog.read_verbs.include?(verb_name.to_s),
+                    current_etag: short_etag(contract_etag_now),
+                    previous_etag: short_etag(@store.contract_etag)
+          )
+
+          post_dispatch!(verb_name)
           ::MCP::Tool::Response.new([{ type: "text", text: JSON.dump(result) }])
-        rescue Textus::ContractDrift => e
-          raise_handler_error(e.message, Textus::ContractDrift::JSONRPC_CODE)
-        rescue CursorExpired => e
-          raise_handler_error(e.message, CursorExpired::JSONRPC_CODE)
+        rescue Textus::CursorExpired => e
+          raise_handler_error(e.message, Textus::CursorExpired::JSONRPC_CODE)
         rescue Textus::Surface::MCP::ToolError => e
           raise_handler_error(e.message, ToolError::JSONRPC_CODE)
         rescue StandardError => e
-          raise_handler_error("internal: #{e.class}: #{e.message}", -32_603)
+          raise_handler_error("internal: #{e.message}", -32_603)
         end
 
         private
 
-        def update_session_for(verb_name)
-          @session = @session.advance_cursor(@store.audit_log.latest_seq) if verb_name == "pulse"
-          @session = @session.with(contract_etag: contract_etag_now)      if verb_name == "boot"
+        def drift_detected?
+          @store.contract_etag != contract_etag_now
+        end
+
+        def post_dispatch!(verb_name)
+          @store = @cursor_manager.advance!(seq: @store.container.store.audit_log.latest[:seq]) if verb_name == :pulse
+          @store = @store.with_role(@store.role) if verb_name == :boot
         end
 
         def build_resources
-          machine_lane = @store.manifest.policy.machine_lane
+          machine_lane = @store.respond_to?(:container) ? @store.container.manifest.policy.machine_lane : nil
           return [] unless machine_lane
 
-          @store.manifest.data.entries
-                .select { |e| e.lane == machine_lane && e.is_a?(Textus::Manifest::Entry::Produced) }
-                .map { |e| ::MCP::Resource.new(uri: "textus://#{e.key.tr(".", "/")}", name: e.key, mime_type: mime_for_format(e.format)) }
+          entries = @store.respond_to?(:container) ? @store.container.manifest.data.entries : []
+          entries.select { |e| e.lane == machine_lane }
+                 .map { |e| ::MCP::Resource.new(uri: "textus://#{e.key.tr(".", "/")}", name: e.key, mime_type: mime_for_format(e.format)) }
         end
 
         def handle_resource_read(uri, _server_context)
-          key = uri.delete_prefix("textus://").tr("/", ".")
-          env  = @store.as(@role).get(key)
-          text = env.content.is_a?(Hash) ? JSON.dump(env.content) : (env.body || "").to_s
-          mime = mime_for_format(@store.manifest.resolver.resolve(key).entry.format)
+          key  = uri.delete_prefix("textus://").tr("/", ".")
+          env  = @store.get(key:)
+          text = env["content"].is_a?(Hash) ? JSON.dump(env["content"]) : (env["body"] || "").to_s
+          mime = mime_for_format(env["format"])
           [{ uri: uri, mimeType: mime, text: text }]
         rescue Textus::Error => e
           raise_handler_error("resource read failed: #{e.message}", -32_603)
+        rescue StandardError => e
+          raise_handler_error("internal: #{e.message}", -32_603)
         end
 
-        def contract_etag_now = Textus::Value::Etag.for_contract(@store.root)
+        def contract_etag_now = Textus::Value::Etag.for_contract(@store.layout)
+
+        def short_etag(etag) = etag.to_s.delete_prefix("sha256:")[0, 8]
 
-        # The SDK parses JSON with symbolize_names:true, making all nested hash keys symbols.
-        # Recursively stringify so Catalog.call receives string-keyed hashes throughout.
         def deep_stringify_keys(obj)
           case obj
           when Hash  then obj.transform_keys(&:to_s).transform_values { |v| deep_stringify_keys(v) }
@@ -107,9 +106,10 @@ module Textus
 
         def mime_for_format(format)
           case format.to_s
-          when "json" then "application/json"
-          when "yaml" then "application/yaml"
-          else             "text/plain"
+          when "json"     then "application/json"
+          when "yaml"     then "application/yaml"
+          when "markdown" then "text/markdown"
+          else                 "text/plain"
           end
         end
 

data/lib/textus/surface/watcher.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require "securerandom"
 
 module Textus
@@ -7,22 +5,30 @@ module Textus
     class Watcher
       def initialize(container:)
         @container = container
+        @registry = Textus::Workflow::Registry.new(container.workflows)
       end
 
       def tick
-        queue = Textus::Store::Jobs::Queue.new(store: @container.job_store)
-        Textus::Store::Jobs::Planner.seed(
-          container: @container,
-          queue: queue,
-          role: Textus::Value::Role::AUTOMATION,
-        )
-        queue.reclaim(now: Textus::Port::Clock.new.now)
-        Textus::Store::Jobs::Worker.for(container: @container, queue: queue).drain
+        call = Textus::Value::Call.build(role: Textus::Value::Role::AUTOMATION, correlation_id: SecureRandom.uuid)
+
+        Textus::Workflow::Scheduler.new(
+          registry: @registry,
+          workflow_queue: @container.store.workflow_queue,
+          reader: ->(key:) { @container.store_engine.read(key:) },
+        ).seed_expired
+
+        consumer = Textus::Workflow::Consumer.new(registry: @registry, container: @container, call:)
+        loop do
+          row = @container.store.workflow_queue.pop
+          break unless row
+
+          consumer.consume(row, @container.store.workflow_queue)
+        end
       end
 
       def run(poll: nil)
-        interval = poll || @container.manifest.data.worker_config[:poll]
-        lock = Textus::Port::WatcherLock.new(@container.root)
+        interval = poll || @container.manifest.data.worker_config[:poll] || 2
+        lock = Infra::Locks::WatcherLock.new(@container.root)
         lock.acquire
         begin
           loop do

data/lib/textus/surface/web.rb

@@ -0,0 +1,50 @@
+require "sinatra/base"
+require "json"
+
+module Textus
+  module Surface
+    class Web < Sinatra::Base
+      set :textus_session, nil
+      set :port, 9292
+      set :bind, "0.0.0.0"
+      set :server, "puma"
+      set :show_exceptions, false
+
+      get "/api/status" do
+        content_type :json
+        s = settings.textus_session
+        boot = s.boot
+        JSON.generate(protocol: boot["protocol"], lanes: boot["lanes"]&.map { |l| l["name"] }, store_root: boot["store_root"])
+      end
+
+      post "/api/:verb" do
+        content_type :json
+        session = settings.textus_session.with_role(request.env["HTTP_X_TEXTUS_ROLE"] || "agent")
+        body = begin
+          JSON.parse(request.body.read)
+        rescue StandardError
+          {}
+        end
+        result = Textus::Surface::Dispatch.call(session, params[:verb], body)
+        JSON.generate(result)
+      rescue Textus::Error => e
+        halt status_for(e), JSON.generate(error: e.message, code: e.code.to_s)
+      end
+
+      not_found do
+        content_type :json
+        JSON.generate(error: "not found")
+      end
+
+      private
+
+      def status_for(err)
+        case err
+        when Textus::UnknownKey, Textus::UsageError then 404
+        when Textus::EtagMismatch then 409
+        else 422
+        end
+      end
+    end
+  end
+end

data/lib/textus/value/call.rb

@@ -10,7 +10,7 @@ module Textus
         new(
           role: role.to_s,
           correlation_id: correlation_id || SecureRandom.uuid,
-          now: now || Textus::Port::Clock.new.now,
+          now: now || Time.now.utc,
           dry_run: dry_run,
         )
       end

data/lib/textus/{core → value}/duration.rb

@@ -1,8 +1,5 @@
 module Textus
-  module Core
-    # Parses a duration value into whole seconds. Accepts a bare integer (or
-    # integer-string) of seconds, or `<n><unit>` with unit s/m/h/d. Returns
-    # nil for nil or any unparseable value.
+  module Value
     module Duration
       UNIT_SECONDS = { "s" => 1, "m" => 60, "h" => 3600, "d" => 86_400 }.freeze
 

data/lib/textus/value/etag.rb

@@ -16,8 +16,9 @@ module Textus
       # mid-session edit to any of these makes the cached orientation stale, so
       # the session must re-boot (ADR 0074). The composite is one digest over the
       # sorted per-file listing, so it is order-stable.
-      def self.for_contract(root)
-        listing = contract_files(root).map do |path|
+      def self.for_contract(layout)
+        root = layout.root
+        listing = contract_files(layout).map do |path|
           rel = path.delete_prefix(root).delete_prefix("/")
           "#{rel}:#{for_file(path)}"
         end.join("\n")
@@ -26,12 +27,11 @@ module Textus
 
       # manifest.yaml, then every hook and schema file. Dir.glob already returns
       # sorted paths (Ruby 3.0+), keeping the digest independent of FS order.
-      def self.contract_files(root)
-        geom = Textus::Store::Geometry.new(root)
+      def self.contract_files(layout)
         [
-          geom.manifest_path,
-          *Dir.glob(File.join(geom.hooks_dir, "**", "*.rb")),
-          *Dir.glob(geom.schemas_glob).select { |f| File.file?(f) },
+          layout.manifest_path,
+          *Dir.glob(File.join(layout.hooks_dir, "**", "*.rb")),
+          *Dir.glob(layout.schemas_glob).select { |f| File.file?(f) },
         ]
       end
     end

data/lib/textus/value/payload.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Textus
+  module Value
+    Payload = Data.define(:meta, :body, :content)
+  end
+end

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.55.1"
+  VERSION = "0.56.0"
   PROTOCOL = "textus/4"
 end