textus 0.52.0 → 0.53.0

data/lib/textus/maintenance/worker.rb

@@ -1,74 +0,0 @@
-module Textus
-  module Maintenance
-    # Drains the job queue: lease a job, look up its handler in the registry, run
-    # it (as the job's stamped authority — wired in a later phase), then ack on
-    # success or fail (requeue/dead-letter) on a raise. `drain` runs until the
-    # queue is empty and returns a summary. Delivery is at-least-once.
-    class Worker
-      Summary = Struct.new(:completed, :failed, keyword_init: true)
-
-      # The standard convergence worker: the closed handler allow-list plus the
-      # lease TTL from worker_config. Both `drain` and `serve` build it this way.
-      def self.for(container:, queue:)
-        new(
-          queue: queue, registry: Textus::Jobs::Handlers.registry,
-          container: container, lease_ttl: container.manifest.data.worker_config[:lease_ttl]
-        )
-      end
-
-      def initialize(queue:, registry:, container:, lease_ttl: 60)
-        @queue = queue
-        @registry = registry
-        @container = container
-        @lease_ttl = lease_ttl
-      end
-
-      def drain(worker_id: "drain-#{Process.pid}")
-        completed = 0
-        failed = 0
-        loop do
-          leased = @queue.lease(worker_id: worker_id, lease_ttl: @lease_ttl)
-          break unless leased
-
-          case run_one(leased)
-          when :completed     then completed += 1
-          when :dead_lettered then failed += 1
-            # :requeued -> a transient failure; it re-leases on a later iteration
-          end
-        end
-        Summary.new(completed: completed, failed: failed)
-      end
-
-      def drain_pool(pool: 4)
-        summaries = []
-        mutex = Mutex.new
-        threads = Array.new(pool) do |i|
-          Thread.new do
-            s = drain(worker_id: "pool-#{Process.pid}-#{i}")
-            mutex.synchronize { summaries << s }
-          end
-        end
-        threads.each(&:join)
-        Summary.new(
-          completed: summaries.sum(&:completed),
-          failed: summaries.sum(&:failed),
-        )
-      end
-
-      private
-
-      # Returns :completed on ack, or the queue's failure verdict (:requeued |
-      # :dead_lettered) on a raise. A requeued job re-leases on the next loop
-      # iteration, so a transient failure still drains; only a dead-letter is a
-      # terminal failure that counts toward the summary.
-      def run_one(leased)
-        entry = @registry.lookup(leased.job.type)
-        entry.handler.call(job: leased.job, container: @container)
-        @queue.ack(leased)
-        :completed
-      rescue StandardError => e
-        @queue.fail(leased, error: e.message)
-      end
-    end
-  end
-end

data/lib/textus/maintenance/zone_mv.rb

@@ -1,64 +0,0 @@
-require "yaml"
-
-module Textus
-  module Maintenance
-    # Rename a zone — rewrites the manifest's zones[] entry, rewrites
-    # the `zone:` field on every entry under the old zone, and moves
-    # every file from zones/<old>/ to zones/<new>/.
-    class ZoneMv
-      extend Textus::Contract::DSL
-
-      verb     :zone_mv
-      summary  "Rename a zone — manifest + files. Refuses if destination exists."
-      surfaces :cli, :mcp
-      cli      "zone mv"
-      arg :from,    String, required: true, positional: true, description: "current zone name"
-      arg :to,      String, required: true, positional: true, description: "new zone name; refused if a zone by this name already exists"
-      arg :dry_run, :boolean, default: false,
-                              description: "when true, returns the planned zone move without applying it; " \
-                                           "defaults to false, so omitting it applies the move immediately"
-      view { |v, _i| v.to_h }
-
-      def initialize(container:, call:)
-        @container = container
-        @call      = call
-        @manifest  = container.manifest
-        @root      = container.root
-      end
-
-      def call(from, to, dry_run: false)
-        raise UsageError.new("from and to required") if from.nil? || to.nil? || from.empty? || to.empty?
-        raise UsageError.new("zone '#{from}' not declared") unless @manifest.data.declared_zone_kinds.key?(from)
-
-        dest_dir = File.join(@root, "zones", to)
-        raise UsageError.new("destination 'zones/#{to}' already exists") if File.exist?(dest_dir)
-
-        affected_keys = @manifest.data.entries.select { |e| e.zone == from }.map(&:key)
-
-        steps  = [{ "op" => "rename_zone", "from" => from, "to" => to }]
-        steps += affected_keys.map { |k| { "op" => "mv", "from" => k, "to" => "#{to}#{k[from.length..]}" } }
-
-        plan = Plan.new(steps: steps, warnings: [])
-        return plan if dry_run
-
-        rewrite_manifest!(from, to)
-        FileUtils.mv(File.join(@root, "zones", from), dest_dir)
-        plan
-      end
-
-      private
-
-      def rewrite_manifest!(from, to)
-        path = File.join(@root, "manifest.yaml")
-        raw = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: false)
-        raw["zones"].each { |z| z["name"] = to if z["name"] == from }
-        raw["entries"].each do |e|
-          e["zone"] = to if e["zone"] == from
-          e["key"]  = e["key"].sub(/\A#{Regexp.escape(from)}(\.|\z)/, "#{to}\\1")
-          e["path"] = e["path"].sub(%r{\A#{Regexp.escape(from)}(/|\z)}, "#{to}\\1")
-        end
-        File.write(path, YAML.dump(raw))
-      end
-    end
-  end
-end

data/lib/textus/maintenance.rb

@@ -1,15 +0,0 @@
-module Textus
-  # Bulk and structural changes to a textus store. Each use case returns
-  # a Plan when called with dry_run: true, and applies the plan when
-  # called with dry_run: false.
-  module Maintenance
-    # A Plan is a JSON-shaped preview. Steps are op-tagged hashes the
-    # use case knows how to apply. Warnings are strings surfaced to
-    # the operator (skipped keys, ambiguities).
-    Plan = Data.define(:steps, :warnings) do
-      def to_h
-        { "steps" => steps, "warnings" => warnings }
-      end
-    end
-  end
-end

data/lib/textus/mcp/catalog.rb

@@ -1,70 +0,0 @@
-module Textus
-  module MCP
-    # Derives the entire MCP tool surface from the per-verb contracts
-    # (ADR 0039). `tool_schemas` feeds tools/list; `call` is the generic
-    # tools/call dispatch: map JSON args -> (positional, keyword) per the
-    # contract, invoke the verb through the role scope, then shape the
-    # return value with the contract's default view. No per-tool code.
-    module Catalog
-      module_function
-
-      # Contracts of every MCP-surfaced verb, in Dispatcher order.
-      def specs
-        Textus::Dispatcher::VERBS.values
-                                 .select { |k| mcp_surfaced?(k) }
-                                 .map(&:contract)
-      end
-
-      def tool_schemas
-        specs.map do |s|
-          { name: s.verb.to_s, description: s.summary, inputSchema: s.input_schema }
-        end.freeze
-      end
-
-      def names
-        specs.map { |s| s.verb.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.
-      def read_verbs
-        Textus::Dispatcher::VERBS
-          .select { |_verb, klass| mcp_surfaced?(klass) && klass.name.start_with?("Textus::Read::") }
-          .keys.map(&: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::Dispatcher::VERBS
-          .select { |_verb, klass| mcp_surfaced?(klass) && klass.name.start_with?("Textus::Write::") }
-          .keys.map(&:to_s)
-      end
-
-      def mcp_surfaced?(klass)
-        klass.respond_to?(:contract?) && klass.contract? && klass.contract.mcp?
-      end
-
-      def call(name, session:, store:, args:)
-        klass = Textus::Dispatcher::VERBS[name.to_sym]
-        raise ToolError.new("unknown tool: #{name}") unless klass && mcp_surfaced?(klass)
-
-        spec = klass.contract
-        inputs = Textus::Contract::Binder.inputs_from_wire(spec, args)
-        result = store.as(session.role).dispatch_bound(spec.verb, inputs, session: session)
-        Textus::Contract::View.render(spec, :default, result, inputs)
-      rescue Textus::Contract::MissingArgs => e
-        raise ToolError.new("#{spec.verb}: missing #{e.missing.map { |a| a.wire.to_s }.join(", ")}")
-      rescue ContractDrift, CursorExpired
-        raise
-      rescue Textus::Error => e
-        raise ToolError.new("#{name}: #{e.message}")
-      end
-    end
-  end
-end

data/lib/textus/mcp/errors.rb

@@ -1,32 +0,0 @@
-module Textus
-  module MCP
-    # Manifest fingerprint changed mid-session. Client should re-boot.
-    class ContractDrift < Textus::Error
-      JSONRPC_CODE = -32_001
-
-      def initialize(message, details: {})
-        super("contract_drift", message, details: details)
-      end
-    end
-
-    # 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
-      JSONRPC_CODE = -32_000
-
-      def initialize(message, details: {})
-        super("tool_error", message, details: details)
-      end
-    end
-  end
-end

data/lib/textus/mcp/server.rb

@@ -1,138 +0,0 @@
-require "json"
-
-module Textus
-  module MCP
-    # Stdio JSON-RPC 2.0 server speaking MCP draft 2024-11-05. One line per
-    # message (NDJSON). Holds a single Session for the lifetime of stdin.
-    class Server
-      PROTOCOL_VERSION = "2024-11-05"
-      SERVER_INFO = { "name" => "textus", "version" => Textus::VERSION }.freeze
-
-      def initialize(store:, stdin: $stdin, stdout: $stdout, role: Textus::Role::DEFAULT)
-        @store   = store
-        @stdin   = stdin
-        @stdout  = stdout
-        @role    = role
-        @session = nil
-      end
-
-      def run
-        @stdin.each_line do |line|
-          line = line.strip
-          next if line.empty?
-
-          handle_line(line)
-        end
-      end
-
-      private
-
-      def handle_line(line)
-        msg = JSON.parse(line)
-      rescue JSON::ParserError => e
-        emit_error(nil, -32_700, "parse error: #{e.message}")
-      else
-        dispatch(msg)
-      end
-
-      def dispatch(msg)
-        rid = msg["id"]
-        case msg["method"]
-        when "initialize"                then handle_initialize(rid, msg["params"] || {})
-        when "tools/list"                then handle_tools_list(rid)
-        when "tools/call"                then handle_tools_call(rid, msg["params"] || {})
-        when "ping"                      then emit_result(rid, {})
-        when "shutdown"                  then emit_result(rid, nil)
-        when "notifications/initialized" then nil
-        else emit_error(rid, -32_601, "method not found: #{msg["method"]}")
-        end
-      end
-
-      def handle_initialize(rid, _params)
-        # The acting role IS the resolved connection role (ADR 0040): the MCP
-        # transport defaults to `agent`, which can write the queue, so its
-        # propose_zone resolves directly. If a connection's role cannot propose,
-        # propose_zone is nil and the `propose` tool reports that honestly.
-        propose_zone = @store.manifest.policy.propose_zone_for(@role)
-
-        @session = Session.new(
-          role: @role,
-          cursor: @store.audit_log.latest_seq,
-          propose_zone: propose_zone,
-          contract_etag: contract_etag,
-        )
-
-        # ADR 0075: announce the connection to connect-time hooks with the
-        # resolved role. Distinct from :store_loaded (fired at Store.new under
-        # the default role, before any connection's role is known).
-        @store.events.publish(
-          :session_opened,
-          ctx: Hooks::Context.new(scope: @store.as(@role)),
-          role: @role,
-          cursor: @session.cursor,
-        )
-
-        emit_result(rid, {
-                      "protocolVersion" => PROTOCOL_VERSION,
-                      "serverInfo" => SERVER_INFO,
-                      "capabilities" => { "tools" => {} },
-                    })
-      end
-
-      def handle_tools_list(rid)
-        emit_result(rid, { "tools" => Catalog.tool_schemas })
-      end
-
-      def handle_tools_call(rid, params)
-        unless @session
-          emit_error(rid, -32_002, "session not initialized; call 'initialize' first")
-          return
-        end
-
-        name = params["name"]
-        args = params["arguments"] || {}
-
-        # ADR 0083: the contract-drift guard gates mutating verbs — every MCP
-        # verb that is NOT a pure read (Write:: + the destructive Maintenance::
-        # verbs drain/zone_mv/key_*_prefix). Reads and boot bypass it (a stale
-        # read returns on-disk truth; boot re-orients). Keying on read_verbs
-        # (not write_verbs) keeps the destructive Maintenance:: verbs gated.
-        @session.check_etag!(contract_etag) unless Catalog.read_verbs.include?(name)
-
-        result = Catalog.call(name, session: @session, store: @store, args: args)
-        @session = @session.advance_cursor(@store.audit_log.latest_seq) if name == "pulse"
-        @session = @session.with(contract_etag: contract_etag) if name == "boot"
-
-        emit_result(rid, {
-                      "content" => [{ "type" => "text", "text" => JSON.dump(result) }],
-                      "isError" => false,
-                    })
-      rescue ContractDrift => e
-        emit_error(rid, ContractDrift::JSONRPC_CODE, e.message)
-      rescue CursorExpired => e
-        emit_error(rid, CursorExpired::JSONRPC_CODE, e.message)
-      rescue ToolError => e
-        emit_error(rid, ToolError::JSONRPC_CODE, e.message)
-      rescue StandardError => e
-        emit_error(rid, -32_603, "internal: #{e.class}: #{e.message}")
-      end
-
-      def contract_etag
-        Textus::Etag.for_contract(@store.root)
-      end
-
-      def emit_result(rid, result)
-        write({ "jsonrpc" => "2.0", "id" => rid, "result" => result })
-      end
-
-      def emit_error(rid, code, message)
-        write({ "jsonrpc" => "2.0", "id" => rid, "error" => { "code" => code, "message" => message } })
-      end
-
-      def write(obj)
-        @stdout.puts(JSON.dump(obj))
-        @stdout.flush
-      end
-    end
-  end
-end

data/lib/textus/mcp/session.rb

@@ -1,7 +0,0 @@
-module Textus
-  module MCP
-    # The session value now lives in core (ADR 0036); retained here as an
-    # alias so existing MCP references keep resolving.
-    Session = Textus::Session
-  end
-end

data/lib/textus/mcp/tool_schemas.rb

@@ -1,15 +0,0 @@
-module Textus
-  module MCP
-    # Kept for name stability (ADR 0039). The JSON schemas are DERIVED from
-    # per-verb contracts; this delegates to MCP::Catalog. The hand-written
-    # array is gone — a kwarg rename now updates the schema automatically (and
-    # the signature guard fails if the contract lags the use-case).
-    module ToolSchemas
-      module_function
-
-      def all
-        Catalog.tool_schemas
-      end
-    end
-  end
-end

data/lib/textus/mcp.rb

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

data/lib/textus/mustache.rb

@@ -1,117 +0,0 @@
-module Textus
-  module Mustache
-    MAX_DEPTH = 8
-    TAG = %r{\{\{(?<sigil>[#^/!&]?)\s*(?<name>[\w.-]+)\s*\}\}}
-
-    def self.render(template, context, strict: false, depth: 0) # rubocop:disable Metrics/AbcSize
-      raise TemplateError.new("template recursion depth #{depth} exceeded #{MAX_DEPTH}") if depth > MAX_DEPTH
-
-      out = +""
-      pos = 0
-      while (m = template.match(TAG, pos))
-        out << template[pos...m.begin(0)]
-        case m[:sigil]
-        when "!"
-          # comment, skip
-        when "#"
-          section, new_pos = parse_section(template, m, m[:name])
-          value = lookup(context, m[:name])
-          out << render_section(section, value, context, strict, depth)
-          pos = new_pos
-          next
-        when "^"
-          section, new_pos = parse_section(template, m, m[:name])
-          value = lookup(context, m[:name])
-          if falsy?(value)
-            raise TemplateError.new("template recursion depth #{depth + 1} exceeded #{MAX_DEPTH}") if depth + 1 > MAX_DEPTH
-
-            out << render(section, context, strict: strict, depth: depth + 1)
-          end
-          pos = new_pos
-          next
-        when "/"
-          raise TemplateError.new("unexpected closing tag #{m[:name]}")
-        else
-          val = lookup(context, m[:name])
-          if val.nil?
-            raise TemplateError.new("missing variable: #{m[:name]}") if strict
-          else
-            out << val.to_s
-          end
-        end
-        pos = m.end(0)
-      end
-      out << template[pos..]
-      out
-    end
-
-    def self.parse_section(template, open_match, name)
-      open_re  = /\{\{#\s*#{Regexp.escape(name)}\s*\}\}|\{\{\^\s*#{Regexp.escape(name)}\s*\}\}/
-      close_re = %r{\{\{/\s*#{Regexp.escape(name)}\s*\}\}}
-      both = Regexp.union(open_re, close_re)
-      depth = 1
-      cursor = open_match.end(0)
-      while (m = template.match(both, cursor))
-        if m[0].start_with?("{{/")
-          depth -= 1
-          return [template[open_match.end(0)...m.begin(0)], m.end(0)] if depth.zero?
-        else
-          depth += 1
-        end
-        cursor = m.end(0)
-      end
-      raise TemplateError.new("unclosed section: #{name}")
-    end
-
-    def self.render_section(section, value, context, strict, depth)
-      raise TemplateError.new("template recursion depth #{depth + 1} exceeded #{MAX_DEPTH}") if depth + 1 > MAX_DEPTH
-
-      case value
-      when Array
-        value.map { |v| render(section, scope_for(context, v), strict: strict, depth: depth + 1) }.join
-      when Hash
-        render(section, merge(context, value), strict: strict, depth: depth + 1)
-      when true
-        render(section, context, strict: strict, depth: depth + 1)
-      when false, nil
-        # falsy in regular section: render nothing.
-        # render_section is only called for inverted sections when falsy? is true at the call site,
-        # so this branch is only hit for normal sections with falsy values.
-        ""
-      else
-        render(section, context, strict: strict, depth: depth + 1)
-      end || ""
-    end
-
-    def self.lookup(context, name)
-      # Implicit iterator: {{.}} refers to the current scope itself (used when
-      # iterating arrays of primitive values).
-      return context["."] if name == "." && context.is_a?(Hash) && context.key?(".")
-      return context[name] if context.is_a?(Hash) && context.key?(name)
-
-      name.split(".").reduce(context) do |acc, seg|
-        return nil unless acc.is_a?(Hash)
-
-        acc[seg]
-      end
-    end
-
-    # Build the rendering scope for one iteration of a section. Hash items
-    # merge into the outer context; primitive items (strings, numbers) bind
-    # to the implicit iterator under key ".".
-    def self.scope_for(context, item)
-      return merge(context, item) if item.is_a?(Hash)
-
-      base = context.is_a?(Hash) ? context : {}
-      base.merge("." => item)
-    end
-
-    def self.merge(base, override)
-      return base unless override.is_a?(Hash)
-
-      base.merge(override)
-    end
-
-    def self.falsy?(v) = v.nil? || v == false || v == [] || v == ""
-  end
-end

data/lib/textus/ports/produce_on_write_subscriber.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Ports
-    # ADR 0093 / job-queue model: on a canon write, enqueue a `materialize` job
-    # for each derived entry that depends on the written key (rdeps ∩ producible).
-    # Async-only — the write returns immediately; a worker (drain/serve) converges
-    # the jobs. There is no inline `sync` path and no in-process thread: freshness
-    # is re-homed to drain (at the commit/CI gate) and the daemon. A write INTO a
-    # derived entry does not fan out (recursion guard). Produce self-elevates, so
-    # the job is stamped automation. Attached at Store boot, alongside
-    # AuditSubscriber.
-    class ProduceOnWriteSubscriber
-      def initialize(container)
-        @container = container
-      end
-
-      def attach(bus)
-        bus.on(:entry_written, :produce_on_write) do |key:, **|
-          on_write(key: key)
-        end
-        # Closes the ADR 0087 gap: a delete/rename of a source must re-materialize
-        # its orphaned dependents too, not just a write. These fire distinct
-        # events (:entry_deleted / :entry_renamed), so subscribe to each.
-        bus.on(:entry_deleted, :produce_on_delete) do |key:, **|
-          on_write(key: key)
-        end
-        bus.on(:entry_renamed, :produce_on_rename) do |from_key:, to_key:, **|
-          on_write(key: from_key)
-          on_write(key: to_key)
-        end
-        self
-      end
-
-      def on_write(key:)
-        return if derived_write?(key) # recursion guard: produce output is not a source change
-
-        affected = Textus::Read::Rdeps.new(container: @container).call(key)["rdeps"]
-        producible = affected.select { |k| producible?(k) }
-        return if producible.empty?
-
-        queue = Textus::Ports::Queue.new(root: @container.root)
-        producible.each do |k|
-          queue.enqueue(
-            Textus::Domain::Jobs::Job.new(
-              type: "materialize", args: { "key" => k }, enqueued_by: Textus::Role::AUTOMATION,
-            ),
-          )
-        end
-      end
-
-      private
-
-      def derived_write?(key)
-        @container.manifest.resolver.resolve(key).entry.derived?
-      rescue Textus::Error
-        false
-      end
-
-      # The producible scope mirrors Produce::Engine#produce_one: derived
-      # entries render+publish, and nested publish_tree entries mirror their
-      # source subtree (ADR 0047). Including the latter restores reactive
-      # re-mirroring on a write into a tree's source — dropped when the scope
-      # narrowed to `derived?` only.
-      def producible?(key)
-        entry = @container.manifest.resolver.resolve(key).entry
-        entry.derived? || !entry.publish_tree.nil?
-      rescue Textus::Error
-        false
-      end
-    end
-  end
-end

data/lib/textus/produce/events.rb

@@ -1,36 +0,0 @@
-module Textus
-  module Produce
-    # Single home for the fetch lifecycle event vocabulary (ADR 0048 D5).
-    # Produce::Acquire::Intake (the ingest executor driven by converge + hook) emits through
-    # this seam so the event names and payload shapes live in one place with one
-    # derived hook context.
-    class Events
-      def self.from(container:, call:)
-        new(
-          events: container.events,
-          hook_context: Textus::Hooks::Context.for(container: container, call: call),
-        )
-      end
-
-      def initialize(events:, hook_context:)
-        @events = events
-        @hook_context = hook_context
-      end
-
-      def started(key, mode: :sync)
-        @events.publish(:entry_fetch_started, ctx: @hook_context, key: key, mode: mode)
-      end
-
-      def failed(key, error)
-        @events.publish(:entry_fetch_failed, ctx: @hook_context, key: key,
-                                             error_class: error.class.name, error_message: error.message)
-      end
-
-      def fetched(key, envelope, change)
-        return if change == :unchanged
-
-        @events.publish(:entry_fetched, ctx: @hook_context, key: key, envelope: envelope, change: change)
-      end
-    end
-  end
-end