textus 0.51.0 → 0.53.0

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 reconcile/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,69 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Ports
-    # ADR 0093: on a canon write, converge the derived entries that depend on the
-    # written key (rdeps ∩ derived) by running Produce — scoped + non-destructive.
-    # This IS reconcile narrowed to a write's blast radius; there is no separate
-    # "reactive materialize" subsystem. Per-entry source.on_write (sync|async)
-    # picks inline-under-lock vs deferred. A write INTO a derived entry does not
-    # fan out (recursion guard). Failures never reach the writer (Produce.converge
-    # isolates them). 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 |ctx:, key:, **|
-          call = Textus::Call.build(role: ctx.role, correlation_id: ctx.correlation_id)
-          on_write(key: key, call: call)
-        end
-        self
-      end
-
-      def on_write(key:, call:)
-        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?
-
-        if any_sync?(producible)
-          Textus::Produce::Engine.converge(container: @container, call: call, keys: producible)
-        else
-          Textus::Produce::Engine::AsyncRunner.enqueue(container: @container, call: call, keys: producible)
-        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
-
-      # Only derived entries carry a source with on_write semantics; a nested
-      # publish_tree entry has no source and defaults to async.
-      def any_sync?(keys)
-        keys.any? do |k|
-          entry = @container.manifest.resolver.resolve(k).entry
-          entry.derived? && entry.source.sync?
-        end
-      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 reconcile + 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

data/lib/textus/read/audit.rb

@@ -1,130 +0,0 @@
-require "json"
-require "time"
-
-module Textus
-  module Read
-    # Queries .textus/.run/audit/audit.log. Filters: key, zone, role, verb, since,
-    # correlation_id, limit. Reads the log file as JSON-Lines (legacy TSV
-    # rows produce nil and are skipped).
-    class Audit
-      # Value object that carries all filter parameters for an audit query.
-      # `matches?` checks the manifest-independent predicates so the loop body
-      # only needs to handle the zone check (which requires manifest access).
-      Query = Data.define(:key, :zone, :role, :verb, :since, :seq_since, :correlation_id, :limit) do
-        # rubocop:disable Metrics/ParameterLists
-        def self.build(key: nil, zone: nil, role: nil, verb: nil,
-                       since: nil, seq_since: nil, correlation_id: nil, limit: nil)
-          new(key:, zone:, role:, verb:, since:, seq_since:, correlation_id:, limit:)
-        end
-        # rubocop:enable Metrics/ParameterLists
-
-        def matches?(row)
-          return false if key && row["key"] != key
-          return false if role && row["role"] != role
-          return false if verb && row["verb"] != verb
-          return false if since && (row["ts"].nil? || Time.parse(row["ts"]) < since)
-          return false if seq_since && (row["seq"].nil? || row["seq"] <= seq_since)
-          return false if correlation_id && row.dig("extras", "correlation_id") != correlation_id
-
-          true
-        end
-      end
-
-      extend Textus::Contract::DSL
-
-      verb     :audit
-      summary  "Query the audit log with optional filters."
-      surfaces :cli
-      cli      "audit"
-      # #call(**filters) — args map to Query.build keyword params (ADR 0063)
-      arg :key,            String,  required: false, description: "filter to rows for this key"
-      arg :zone,           String,  required: false, description: "filter to keys in this zone"
-      arg :role,           String,  required: false, description: "filter to rows written under this role"
-      arg :verb,           String,  required: false, description: "filter to rows for this verb"
-      arg :since,          String,  required: false,
-                                    coerce: ->(s) { Textus::Read::Audit.parse_since(s, now: Time.now) },
-                                    description: "ISO-8601 timestamp or relative offset (e.g. 1h, 30m)"
-      arg :seq_since,      Integer, required: false, description: "return rows with seq > this cursor value"
-      arg :correlation_id, String,  required: false, description: "filter to rows with this correlation_id"
-      arg :limit,          Integer, required: false, description: "maximum number of rows to return"
-      view(:cli) { |rows, _i| { "verb" => "audit", "rows" => rows } }
-
-      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
-        @manifest  = container.manifest
-        @root      = container.root
-        @log_path  = Textus::Layout.audit_log(container.root)
-        @audit_log = container.audit_log
-      end
-
-      def call(**filters)
-        query = Query.build(**filters)
-        check_cursor_expiry!(query.seq_since)
-
-        files = all_log_files
-        return [] if files.empty?
-
-        rows = []
-        files.each do |file|
-          File.foreach(file) do |line|
-            parsed = parse_row(line.chomp)
-            next unless parsed
-            next unless query.matches?(parsed)
-            next if query.zone && !key_in_zone?(parsed["key"], query.zone)
-
-            rows << parsed
-            break if limit_reached?(rows, query)
-          end
-          break if limit_reached?(rows, query)
-        end
-        rows
-      end
-
-      # Accepts ISO8601 ("2026-01-15", "2026-01-15T10:00:00Z") or a relative
-      # offset matching /\A(\d+)([smhd])\z/. Returns nil for unparseable input.
-      def self.parse_since(str, now: Time.now.utc)
-        return nil if str.nil? || str.empty?
-        return Time.parse(str) if str =~ /\A\d{4}-\d{2}-\d{2}/
-
-        m = str.match(/\A(\d+)([smhd])\z/) or return nil
-        mult = { "s" => 1, "m" => 60, "h" => 3600, "d" => 86_400 }[m[2]]
-        now - (m[1].to_i * mult)
-      end
-
-      private
-
-      def limit_reached?(rows, query) = query.limit && rows.length >= query.limit
-
-      def check_cursor_expiry!(seq_since)
-        return unless seq_since
-
-        log = @audit_log || Textus::Ports::AuditLog.new(@root)
-        min = log.min_available_seq
-        raise Textus::CursorExpired.new(requested: seq_since, min_available: min) if min && seq_since < min - 1
-      end
-
-      def all_log_files
-        rotated = Dir.glob(File.join(Textus::Layout.audit_dir(@root), "audit.log.*"))
-                     .reject { |p| p.end_with?(".meta.json") }
-                     .sort_by { |p| -p.scan(/\d+$/).first.to_i } # .5 .4 .3 .2 .1 → oldest first
-        active = File.exist?(@log_path) ? [@log_path] : []
-        rotated + active
-      end
-
-      def parse_row(line)
-        return nil if line.empty?
-        return nil unless line.start_with?("{")
-
-        JSON.parse(line)
-      rescue JSON::ParserError
-        nil
-      end
-
-      def key_in_zone?(key, zone)
-        mentry = @manifest.resolver.resolve(key).entry
-        mentry && mentry.zone == zone
-      rescue Textus::Error
-        false
-      end
-    end
-  end
-end

data/lib/textus/read/boot.rb

@@ -1,26 +0,0 @@
-module Textus
-  module Read
-    # Dispatched use case for the `boot` verb. The orientation envelope is
-    # built by the Textus::Boot library module; this class is the uniform
-    # (container:, call:) entry point that Dispatcher::VERBS resolves to.
-    # Boot is role-independent, so `call` is not consulted.
-    class Boot
-      extend Textus::Contract::DSL
-
-      verb     :boot
-      summary  "Return the orientation contract: zones, entries, schemas, write_flows, agent_quickstart."
-      surfaces :cli, :mcp
-      arg :lean, :boolean,
-          description: "return only orientation essentials (zones, agent_quickstart, contract_etag) for cheap session-start injection"
-
-      def initialize(container:, call:)
-        @container = container
-        @call      = call
-      end
-
-      def call(lean: false)
-        Textus::Boot.build(container: @container, lean: lean)
-      end
-    end
-  end
-end

data/lib/textus/read/capabilities.rb

@@ -1,70 +0,0 @@
-module Textus
-  module Read
-    # A machine-readable projection of the contract surface: every verb, the
-    # transports it reaches, and its full argument schema — sourced from the
-    # same Contract DSL the CLI/MCP/boot already project from (ADR 0039/0063).
-    #
-    # Integrators assert their docs against this in CI so they can't drift
-    # (#161 F4 — patrick-nexus docs claimed "MCP exposes 3 verbs" while ~20 are
-    # surfaced). It also makes the per-surface `dry_run` default asymmetry
-    # (#161 F6) self-documenting: each arg carries both `default` (agent wire)
-    # and `cli_default` (CLI), so the divergence is visible, not folklore.
-    #
-    # Pure contract introspection — it reads no store data; `container` is
-    # accepted only for the uniform use-case constructor.
-    class Capabilities
-      extend Textus::Contract::DSL
-
-      verb     :capabilities
-      summary  "Machine-readable contract surface: every verb, its transports, and arg schema."
-      surfaces :cli, :mcp
-      arg :verb, String, required: false, description: "filter to a single verb by name"
-      view { |result, _i| result }
-
-      def initialize(container: nil, call: nil); end
-
-      def call(verb: nil)
-        klasses = Textus::Dispatcher::VERBS.values.select { |k| contract?(k) }
-        rows = klasses.map { |k| project(k.contract) }
-        rows.select! { |r| r["verb"] == verb } if verb
-        { "verbs" => rows.sort_by { |r| r["verb"] } }
-      end
-
-      private
-
-      def contract?(klass)
-        klass.respond_to?(:contract?) && klass.contract?
-      end
-
-      def project(spec)
-        {
-          "verb" => spec.verb.to_s,
-          "summary" => spec.summary,
-          "surfaces" => spec.surfaces.map(&:to_s) + ["ruby"],
-          "cli" => spec.cli? ? spec.cli_path : nil,
-          "args" => spec.args.map { |a| project_arg(a) },
-        }
-      end
-
-      def project_arg(arg)
-        out = {
-          "name" => arg.wire.to_s,
-          "type" => json_type(arg.type),
-          "required" => arg.required,
-          "positional" => arg.positional,
-        }
-        out["description"] = arg.description if arg.description
-        out["default"] = arg.default unless arg.default.nil?
-        out["cli_default"] = arg.cli_default unless arg.cli_default == :__unset
-        out["session_default"] = arg.session_default.to_s if arg.session_default
-        out
-      end
-
-      def json_type(type)
-        Textus::Contract.json_type(type)
-      rescue ArgumentError
-        "string"
-      end
-    end
-  end
-end