textus 0.55.2 → 0.56.0

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

@@ -1,21 +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.with_role(role)
           @stdin  = stdin
           @stdout = stdout
+          @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),
@@ -40,13 +41,17 @@ module Textus
 
         def dispatch(verb_name, args, _server_context)
           str_args = deep_stringify_keys(args)
-          @store.check_etag!(contract_etag_now) unless Catalog.read_verbs.include?(verb_name.to_s)
+          drifted = drift_detected?
+
           result = Catalog.call(verb_name.to_s, store: @store, args: str_args)
-          @store = @store.advance_cursor(@store.audit_log.latest_seq) if verb_name == :pulse
-          @store = @store.with_role(@store.role) if verb_name == :boot
+          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 Textus::CursorExpired => e
           raise_handler_error(e.message, Textus::CursorExpired::JSONRPC_CODE)
         rescue Textus::Surface::MCP::ToolError => e
@@ -57,23 +62,29 @@ module Textus
 
         private
 
-        # Snapshot at server init against the boot-time manifest. New produced entries
-        # added by a later reconcile are invisible until the server restarts — this is
-        # intentional: a ContractDrift will gate writes on any mid-session manifest change.
+        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.get(key:)
-          text = env.content.is_a?(Hash) ? JSON.dump(env.content) : (env.body || "").to_s
-          mime = mime_for_format(env.format)
+          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)
@@ -81,10 +92,10 @@ module Textus
           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) }

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/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::Layout.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/version.rb

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

data/lib/textus/workflow/consumer.rb

@@ -0,0 +1,39 @@
+module Textus
+  module Workflow
+    class Consumer
+      BACKOFF_DELAYS = [10, 30, 60].freeze
+
+      def initialize(registry:, container:, call:)
+        @registry = registry
+        @container = container
+        @call = call
+      end
+
+      def consume(row, workflow_queue)
+        workflow_queue.mark_processing(row[:id])
+        workflow = @registry.for(row[:workflow_type])
+        Runner.new(workflow, container: @container, call: @call).run(row[:key])
+        workflow_queue.complete(row[:id])
+        row.merge(state: "done")
+      rescue StandardError => e
+        handle_failure(row, workflow_queue, e)
+      end
+
+      private
+
+      def handle_failure(row, workflow_queue, error)
+        retry_count = (row[:retry_count] || 0) + 1
+        max_attempts = row[:max_attempts] || 3
+
+        if retry_count >= max_attempts
+          workflow_queue.fail(row[:id], retry_count:, error: error.message)
+          row.merge(state: "failed", error: error.message)
+        else
+          index = [retry_count - 1, BACKOFF_DELAYS.length - 1].min
+          workflow_queue.reschedule(row[:id], retry_count:, delay: BACKOFF_DELAYS[index], error: error.message)
+          row.merge(state: "retrying")
+        end
+      end
+    end
+  end
+end

data/lib/textus/workflow/dsl/lifecycle.rb

@@ -0,0 +1,32 @@
+module Textus
+  module Workflow
+    module DSL
+      module Lifecycle
+        VALID_EXPIRE_ACTIONS = %i[drop archive].freeze
+
+        def ttl_value(cadence)
+          return nil if cadence == :__no_arg__
+
+          Textus::Value::Duration.seconds(cadence)
+        end
+
+        def expire_action(action = :__no_arg__)
+          return nil if action == :__no_arg__
+
+          sym = action.to_s.to_sym
+          raise ArgumentError.new("on_expire must be one of drop|archive, got #{action.inspect}") unless VALID_EXPIRE_ACTIONS.include?(sym)
+
+          sym
+        end
+
+        def max_attempts_value(n)
+          n.to_i
+        end
+
+        def priority_value(n)
+          n.to_i
+        end
+      end
+    end
+  end
+end

data/lib/textus/workflow/dsl/pattern_matcher.rb

@@ -0,0 +1,20 @@
+module Textus
+  module Workflow
+    module DSL
+      module PatternMatcher
+        def match_pattern?(pattern, key)
+          if pattern.end_with?(".**")
+            prefix = pattern.delete_suffix(".**")
+            key.start_with?("#{prefix}.")
+          elsif pattern.end_with?(".*")
+            prefix = pattern.delete_suffix(".*")
+            suffix = key.delete_prefix("#{prefix}.")
+            key != suffix && !suffix.include?(".")
+          else
+            key == pattern
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/workflow/dsl/step_builder.rb

@@ -0,0 +1,56 @@
+module Textus
+  module Workflow
+    module DSL
+      module StepBuilder
+        def build_step(name, callable = nil, timeout: nil, &block)
+          if callable.is_a?(Hash)
+            raise ArgumentError.new(
+              "step :#{name} no longer accepts options hash; pass timeout: keyword instead",
+            )
+          end
+
+          resolved = if callable.respond_to?(:call)
+                       callable
+                     elsif block
+                       block
+                     else
+                       raise ArgumentError.new("step :#{name} requires a block or a callable (got neither)")
+                     end
+
+          Step.new(name: name, callable: resolved, timeout: timeout)
+        end
+
+        def build_check(name, naming: nil, scope: nil, &block)
+          merge = lambda { |data, new_issues|
+            existing = Array(data&.dig("content", "issues"))
+            all = existing + new_issues
+            { "content" => { "ok" => all.empty?, "issues" => all, "count" => all.size } }
+          }
+
+          if naming
+            raise ArgumentError.new("check :#{name} requires a scope: for naming checks") unless scope
+
+            lambda { |data, ctx|
+              entries = ctx.container.manifest.resolver.enumerate.select do |row|
+                match_pattern?(scope, row[:key].to_s)
+              end
+              new_issues = check_naming(
+                entries, pattern: naming, code: "check.#{name}",
+                         fix: "rename to match #{naming.inspect}"
+              )
+              merge.call(data, new_issues)
+            }
+          elsif block
+            ->(data, ctx) { merge.call(data, block.call(ctx) || []) }
+          else
+            raise ArgumentError.new("check :#{name} requires naming: or a block")
+          end
+        end
+
+        def build_parallel(steps)
+          Parallel.new(steps: steps)
+        end
+      end
+    end
+  end
+end

data/lib/textus/workflow/dsl.rb

@@ -2,41 +2,131 @@ module Textus
   module Workflow
     module DSL
       Step = Data.define(:name, :callable, :timeout)
+      Parallel = Data.define(:steps)
+      PublishTarget = Data.define(:to, :template, :tree, :inject_boot)
 
       class Definition
-        attr_reader :name, :steps, :match_pattern, :publish_block
+        include StepBuilder
+        include PatternMatcher
+        include Lifecycle
+
+        attr_reader :name, :steps, :on_patterns, :save_to, :notify_keys,
+                    :publish_block, :publish_targets,
+                    :handled_events, :workflow_type
+
+        def self.register(defn)
+          @definitions ||= []
+          @definitions << defn
+        end
+
+        def self.definitions
+          @definitions || []
+        end
+
+        def self.clear_registered
+          @definitions = []
+        end
 
         def initialize(name)
-          @name          = name
-          @steps         = []
-          @match_pattern = nil
-          @publish_block = nil
+          @name                = name
+          @steps               = []
+          @on_patterns         = []
+          @save_to             = nil
+          @notify_keys         = []
+          @publish_block       = nil
+          @publish_targets     = []
+          @priority            = 0
+          @handled_events      = []
+          @max_attempts        = 3
+          @workflow_type       = name
         end
 
-        def match(pattern)
-          @match_pattern = pattern
+        # ── Event handling (internal) ──
+        def handles(*event_types)
+          @handled_events.concat(event_types.map(&:to_s).freeze)
         end
 
-        def step(name, callable_or_opt = nil, timeout: nil, &block)
-          callable = if callable_or_opt.respond_to?(:call)
-                       callable_or_opt
-                     elsif block
-                       block
-                     else
-                       raise ArgumentError.new("step :#{name} requires a block or a callable (got neither)")
-                     end
-          t = callable_or_opt.is_a?(Hash) ? callable_or_opt[:timeout] : timeout
-          @steps << Step.new(name: name, callable: callable, timeout: t)
+        def type
+          @workflow_type
         end
 
-        def publish(&block)
-          @publish_block = block || :default
+        def max_attempts(n = nil)
+          return @max_attempts if n.nil?
+
+          @max_attempts = max_attempts_value(n)
         end
 
+        # ── Trigger ──
+        def on(*patterns)
+          @on_patterns = patterns
+        end
+
+        # ── Steps ──
+        def step(name, callable = nil, timeout: nil, &)
+          @steps << build_step(name, callable, timeout:, &)
+        end
+
+        def check(name, naming: nil, scope: nil, &)
+          callable = build_check(name, naming:, scope:, &)
+          @steps << Step.new(name: :"check_#{name}", callable: callable, timeout: nil)
+        end
+
+        def parallel(&)
+          saved = @steps
+          @steps = []
+          instance_eval(&)
+          parallel_steps = @steps.dup
+          @steps = saved << build_parallel(parallel_steps)
+        end
+
+        # ── Output ──
+        def publish(to: nil, template: nil, tree: nil, inject_boot: nil, &block)
+          if block
+            @publish_block = block
+          elsif to || tree
+            @publish_targets << PublishTarget.new(to: to, template: template, tree: tree, inject_boot: inject_boot)
+          else
+            raise ArgumentError.new("publish requires to: (file), tree:, or a block; use save to: for store keys")
+          end
+        end
+
+        def save(to:)
+          @save_to = to
+        end
+
+        def notify(key)
+          @notify_keys << key
+        end
+
+        # ── Ordering ──
+        def priority(n = nil)
+          return @priority if n.nil?
+
+          @priority = priority_value(n)
+        end
+
+        # ── Lifecycle ──
+        def every(cadence = :__no_arg__)
+          return @ttl if cadence == :__no_arg__
+
+          @ttl = ttl_value(cadence)
+        end
+
+        alias ttl every
+
+        def on_expire(action = :__no_arg__)
+          @on_expire = expire_action(action)
+        end
+
+        # ── Matching (internal) ──
         def match?(key)
-          return false unless @match_pattern
+          return false unless @on_patterns&.any?
+
+          @on_patterns.any? { |p| match_pattern?(p, key) }
+        end
 
-          Pattern.match?(@match_pattern, key)
+        def multi_match?
+          @on_patterns&.any? { |p| p.end_with?("**") }
         end
       end
     end

data/lib/textus/workflow/event_emitter.rb

@@ -0,0 +1,21 @@
+module Textus
+  module Workflow
+    class EventEmitter
+      def initialize(workflow_queue, registry:)
+        @workflow_queue = workflow_queue
+        @registry = registry
+      end
+
+      def emit(event_type:, key:, lane: "artifacts")
+        workflows = @registry.workflows_for(event_type)
+        workflows.each do |wf|
+          @workflow_queue.push(
+            event_type: event_type.to_s, workflow_type: wf.type,
+            key:, lane:, max_attempts: wf.max_attempts
+          )
+        end
+        workflows.size
+      end
+    end
+  end
+end

data/lib/textus/workflow/publisher.rb

@@ -0,0 +1,59 @@
+module Textus
+  module Workflow
+    class Publisher
+      def initialize(container:, call:)
+        @container    = container
+        @call         = call
+        @store_engine = container.store_engine
+      end
+
+      def publish(key, data, ctx, definition)
+        definition.publish_targets.each { |t| publish_one(key, data, ctx, target: t) }
+
+        write_to_key(definition.save_to, data, ctx) if definition.save_to
+
+        definition.notify_keys.each { |nk| notify_key(nk, ctx) }
+
+        definition.publish_block&.call(data, ctx)
+      end
+
+      private
+
+      def write_to_key(target_key, data, ctx) # rubocop:disable Lint/UnusedMethodArgument
+        res = @container.manifest.resolver.resolve(target_key)
+        normalized = Textus::Protocol::Format.data_to_payload(data, res.entry.format)
+        meta = stamped_meta(normalized[:meta])
+        @store_engine.put(key: target_key, meta:, body: normalized[:body], content: normalized[:content], call: @call)
+      end
+
+      def notify_key(target_key, ctx) # rubocop:disable Lint/UnusedMethodArgument
+        @store_engine.put(key: target_key, meta: {}, body: nil, content: {}, call: @call)
+      end
+
+      def write_and_pctx(key, data, ctx)
+        normalized = Textus::Protocol::Format.data_to_payload(data, ctx.entry.format)
+        meta = stamped_meta(normalized[:meta])
+        @store_engine.put(key:, meta:, body: normalized[:body], content: normalized[:content], call: @call)
+        Textus::Protocol::Manifest::Entry::Base::PublishContext.new(
+          container: @container,
+          reader: ->(key:) { @store_engine.read(key:) },
+        )
+      end
+
+      def publish_one(key, data, ctx, target:)
+        pctx = write_and_pctx(key, data, ctx)
+        attrs = { "to" => target.to, "template" => target.template,
+                  "tree" => target.tree }
+        attrs["inject_boot"] = true if target.inject_boot
+        pub_target = Textus::Protocol::Manifest::Policy::PublishTarget.new(attrs)
+        entry = ctx.entry.with_publish_targets([pub_target])
+        entry.publish_via(pctx)
+      end
+
+      def stamped_meta(meta)
+        now = Time.now.utc.iso8601
+        (meta || {}).merge("generated_at" => now)
+      end
+    end
+  end
+end