textus 0.53.0 → 0.54.1

data/lib/textus/step/catalog.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # The single source of truth for step event names and their required
-    # kwargs. EventBus, RegistryStore, and the Loader all read these
-    # tables directly — the registries do not keep their own copies. Catalog
-    # references no other constant, so it has no load-order cycle, which is
-    # what removed the previous drift hazard (EventBus held a hard-coded
-    # `RPC_EVENTS` list that could fall out of sync with RpcRegistry's table).
-    module Catalog
-      # Pub-sub events: 0..N handlers, fire-and-forget, receive `ctx:`.
-      PUBSUB = {
-        entry_written: %i[ctx key envelope],
-        entry_deleted: %i[ctx key],
-        entry_fetched: %i[ctx key envelope change],
-        entry_renamed: %i[ctx key from_key to_key envelope],
-        entry_produced: %i[ctx key envelope sources],
-        produce_failed: %i[ctx keys error],
-        proposal_accepted: %i[ctx key target_key],
-        proposal_rejected: %i[ctx key target_key],
-        entry_published: %i[ctx key envelope source target],
-        store_loaded: %i[ctx],
-        session_opened: %i[ctx role cursor],
-        entry_fetch_started: %i[ctx key mode],
-        entry_fetch_failed: %i[ctx key error_class error_message],
-      }.freeze
-
-      # RPC events: single handler, return value matters, receive `caps:`.
-      RPC = {
-        resolve_handler: %i[caps config args],
-        transform_rows: %i[caps rows config],
-        validate: %i[caps],
-      }.freeze
-    end
-  end
-end

data/lib/textus/step/context.rb

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # A narrow handle passed to user steps in place of the raw Store.
-    # All writes route back through the RoleScope so authorization, audit
-    # logging, and schema validation always fire.
-    class Context
-      attr_reader :role, :correlation_id
-
-      def self.for(container:, call:)
-        scope = Textus::Surfaces::RoleScope.new(
-          container: container,
-          role: call.role,
-          correlation_id: call.correlation_id,
-          dry_run: call.dry_run,
-        )
-        new(scope: scope)
-      end
-
-      def initialize(scope:)
-        @scope          = scope
-        @role           = scope.role
-        @correlation_id = scope.correlation_id
-      end
-
-      def backend
-        @scope
-      end
-
-      # read — a pure-observation surface: nothing here ingests. Since ADR 0089
-      # `get` itself is a pure read (the read-through that once forced this
-      # surface to opt out is gone, so the old re-entrancy/deadlock guard is no
-      # longer needed); `list`/`deps`/`freshness` are reads too. A hook observes
-      # current state and never triggers an I/O cascade.
-      def get(key)                = pure_reader.call(key)
-      def list(**)                = @scope.list(**)
-      def deps(key)               = @scope.deps(key)
-      def freshness(key)          = @scope.freshness(key)
-
-      # write (authorized + audited)
-      def put(key, **)          = @scope.put(key, **)
-      def delete(key, **)       = @scope.key_delete(key, **)
-
-      def audit(verb, key:, **)
-        @scope.container.audit_log.append(role: @role, verb: verb, key: key, **)
-      end
-
-      # fan-out
-      def publish_followup(event, **)
-        @scope.container.steps.publish(event, ctx: self, **)
-      end
-
-      def inspect
-        "#<Textus::Step::Context role=#{@role} correlation_id=#{@correlation_id}>"
-      end
-
-      private
-
-      def pure_reader
-        @pure_reader ||= lambda do |key|
-          Textus::Action::Get.new(key: key).call(
-            container: @scope.container,
-            call: Textus::Call.build(
-              role: @scope.role,
-              correlation_id: @scope.correlation_id,
-              dry_run: @scope.dry_run?,
-            ),
-          )
-        end
-      end
-    end
-  end
-end

data/lib/textus/step/discovery.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # Maps a discovered file path under .textus/steps to its (kind, name).
-    # kind = the directory segment directly under steps/; name = the basename
-    # without .rb (hyphens preserved). The single source of truth for valid
-    # kinds is the set of Base subclasses.
-    KINDS = %i[fetch transform validate observe].freeze
-
-    Discovery = Data.define(:kind, :name) do
-      def self.parse(path, base:)
-        rel = path.delete_prefix(base.to_s).delete_prefix("/")
-        parts = rel.split("/")
-        raise UsageError.new("step #{rel} must live under steps/<kind>/<name>.rb") unless parts.length == 2
-
-        kind = parts[0].to_sym
-        raise UsageError.new("unknown step kind '#{parts[0]}' (expected one of: #{KINDS.join(", ")})") unless KINDS.include?(kind)
-
-        new(kind: kind, name: File.basename(parts[1], ".rb").to_sym)
-      end
-    end
-  end
-end

data/lib/textus/step/error_log.rb

@@ -1,32 +0,0 @@
-module Textus
-  module Step
-    # Bounded in-memory ring buffer of recent hook failures (errored and
-    # timed_out). Each row carries the audit `seq` observed at the time of
-    # failure so pulse can filter "errors since cursor".
-    class ErrorLog
-      DEFAULT_CAPACITY = 256
-
-      def initialize(capacity: DEFAULT_CAPACITY)
-        @capacity = capacity
-        @rows = []
-        @mutex = Mutex.new
-      end
-
-      def record(seq:, event:, hook:, key:, error_class:, error_message:)
-        row = {
-          seq: seq, event: event, hook: hook, key: key,
-          error_class: error_class, error_message: error_message,
-          at: Time.now.utc.iso8601
-        }
-        @mutex.synchronize do
-          @rows << row
-          @rows.shift while @rows.size > @capacity
-        end
-      end
-
-      def since(seq)
-        @mutex.synchronize { @rows.select { |r| r[:seq] > seq }.dup }
-      end
-    end
-  end
-end

data/lib/textus/step/event_bus.rb

@@ -1,113 +0,0 @@
-# frozen_string_literal: true
-
-require "timeout"
-
-module Textus
-  module Step
-    class EventBus
-      HOOK_TIMEOUT_SECONDS = 2
-
-      class HookTimeout < StandardError; end
-
-      def initialize(error_log: ErrorLog.new)
-        @pubsub = Hash.new { |h, k| h[k] = [] }
-        @error_handlers = []
-        @error_log = error_log
-      end
-
-      attr_reader :error_log
-
-      def on(event, name, keys: nil, &) = register(event, name, keys: keys, &)
-
-      def register(event, name, keys: nil, &blk)
-        event_sym = event.to_sym
-        raise UsageError.new("#{event_sym} is an RPC event; register on RpcRegistry") if Catalog::RPC.key?(event_sym)
-
-        required = Catalog::PUBSUB[event_sym] or raise UsageError.new("unknown event: #{event}")
-        sig = Signature.new(blk)
-        missing = sig.missing(required)
-        if missing.any?
-          raise UsageError.new("#{event_sym} hooks must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})")
-        end
-
-        name = name.to_sym
-        raise UsageError.new("#{event_sym} hook '#{name}' already registered") if @pubsub[event_sym].any? { |h| h[:name] == name }
-
-        @pubsub[event_sym] << { name: name, callable: blk, keys: keys }
-      end
-
-      def on_error(&block) = @error_handlers << block
-
-      def listeners(event, key:) = @pubsub[event.to_sym].select { |h| match?(h[:keys], key) }
-
-      def pubsub_handlers(event) = @pubsub[event.to_sym]
-
-      def pubsub_handlers_names = @pubsub.values.flatten.map { |h| h[:name] }
-
-      def publish(event, strict: false, **kwargs)
-        key = kwargs[:key] || "-"
-        fired = []
-        errored = []
-        timed_out = []
-        raised = nil
-
-        @pubsub[event.to_sym].each do |sub|
-          next unless match?(sub[:keys], key)
-
-          outcome, err = invoke(event, sub, key, kwargs)
-          case outcome
-          when :ok        then fired << sub[:name]
-          when :errored   then errored << sub[:name]
-          when :timed_out then timed_out << sub[:name]
-          end
-          raised ||= err if strict && err
-        end
-
-        raise raised if strict && raised
-
-        FireReport.new(fired: fired, errored: errored, timed_out: timed_out)
-      end
-
-      private
-
-      def invoke(event, sub, key, kwargs)
-        accepted = Signature.new(sub[:callable]).filter(kwargs)
-        begin
-          Timeout.timeout(HOOK_TIMEOUT_SECONDS) do
-            sub[:callable].call(**accepted)
-          end
-          [:ok, nil]
-        rescue Timeout::Error
-          err = HookTimeout.new("hook #{sub[:name]} exceeded #{HOOK_TIMEOUT_SECONDS}s on event #{event}")
-          notify_error(event, sub, key, kwargs, err)
-          [:timed_out, err]
-        rescue StandardError => e
-          notify_error(event, sub, key, kwargs, e)
-          [:errored, e]
-        end
-      end
-
-      def notify_error(event, sub, key, kwargs, error)
-        @error_log.record(
-          seq: kwargs[:_audit_seq] || -1,
-          event: event,
-          hook: sub[:name],
-          key: key,
-          error_class: error.class.name,
-          error_message: error.message,
-        )
-        @error_handlers.each do |handler|
-          handler.call(event: event, hook: sub[:name], key: key, kwargs: kwargs, error: error)
-        rescue StandardError => e
-          warn "[textus] error handler failed: #{e.class}: #{e.message}"
-        end
-      end
-
-      def match?(globs, key)
-        return true if globs.nil?
-
-        Array(globs).any? { |g| File.fnmatch?(g, key.to_s, File::FNM_PATHNAME) }
-      end
-    end
-  end
-end

data/lib/textus/step/fetch.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # Acquires data from outside the store (the `fetch:` build input). Returns
-    # either { "content" => Hash } (structured) or { _meta:, body: } (rendered
-    # text). Replaces the :resolve_handler RPC. `caps:` is injected by the
-    # registry only if #call declares it.
-    class Fetch < Base
-      def self.required_kwargs = %i[config args]
-    end
-  end
-end

data/lib/textus/step/fire_report.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # Outcome of a single Dispatcher#publish call.
-    #
-    # fired      — hook names that ran to completion
-    # errored    — hook names that raised
-    # timed_out  — hook names whose worker thread exceeded the deadline
-    #
-    # Callers that care about hook health (tests, strict embedders) can
-    # check #ok? or inspect #failures. The dispatcher itself never raises
-    # on a hook failure unless strict: true was passed to #publish.
-    FireReport = Data.define(:fired, :errored, :timed_out) do
-      def initialize(fired:, errored:, timed_out:)
-        super(fired: fired.dup.freeze, errored: errored.dup.freeze, timed_out: timed_out.dup.freeze)
-      end
-
-      def ok? = errored.empty? && timed_out.empty?
-      def failures = errored + timed_out
-    end
-  end
-end

data/lib/textus/step/loader.rb

@@ -1,108 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # Convention discovery: glob .textus/steps/<kind>/<name>.rb, load each file,
-    # validate the class it defines against the discovered kind, assign the
-    # discovered name, and register it. No global queue, no Textus.hook.
-    class Loader
-      BASE_FOR = {
-        fetch: Step::Fetch, transform: Step::Transform,
-        validate: Step::Validate, observe: Step::Observe
-      }.freeze
-
-      def initialize(registry:)
-        @registry = registry
-      end
-
-      def load_dir(dir)
-        return unless File.directory?(dir)
-
-        loaded_paths = Set.new
-        Dir.glob(File.join(dir, "**/*.rb")).sort.each do |path| # rubocop:disable Lint/RedundantDirGlobSort
-          real_path = File.realpath(path)
-          next if loaded_paths.include?(real_path)
-
-          loaded_paths << real_path
-          load_one(dir, path)
-        end
-      end
-
-      private
-
-      def load_one(dir, path)
-        disc = Discovery.parse(path, base: dir)
-        klass = capture_defined_class(path, disc)
-        validate!(disc, klass, path, dir)
-
-        step = klass.new
-        step.name = disc.name
-        @registry.register(step)
-      rescue StandardError, ScriptError => e
-        raise UsageError.new("failed loading step #{rel(dir, path)}: #{e.class}: #{e.message}") unless e.is_a?(UsageError)
-
-        raise
-      end
-
-      # Load the file and return the Step::Base subclass it newly defined.
-      def capture_defined_class(path, disc)
-        before = descendants
-        load(path)
-        defined = descendants - before
-        return defined.first if defined.length == 1
-        raise UsageError.new("step #{path} defined more than one Textus::Step subclass") if defined.length > 1
-
-        fallback = find_existing_class_for(disc)
-        return fallback if fallback
-
-        raise UsageError.new("step #{path} defined no Textus::Step subclass")
-      end
-
-      def find_existing_class_for(disc)
-        expected = inferred_class_name_for(disc)
-        candidates = descendants.select do |klass|
-          klass < BASE_FOR.fetch(disc.kind) && klass.name&.split("::")&.last == expected
-        end
-        return nil if candidates.empty?
-        return candidates.first if candidates.length == 1
-
-        namespaced = candidates.find { |klass| klass.name == "Textus::Step::#{expected}" }
-        namespaced || candidates.first
-      end
-
-      def inferred_class_name_for(disc)
-        stem = disc.name.to_s.split(/[-_]/).map(&:capitalize).join
-        suffix = { fetch: "Fetch", transform: "Transform", validate: "Validate", observe: "Observe" }.fetch(disc.kind)
-        "#{stem}#{suffix}"
-      end
-
-      def validate!(disc, klass, path, dir)
-        expected = BASE_FOR.fetch(disc.kind)
-        actual_kind = klass.respond_to?(:kind) ? safe_kind(klass) : nil
-        unless klass < expected
-          raise UsageError.new("#{rel(dir, path)} defines a #{actual_kind || "non-step"} step but lives under #{disc.kind}/")
-        end
-
-        sig = Step::Signature.new(klass.instance_method(:call))
-        missing = sig.missing(klass.required_kwargs)
-        return if missing.empty?
-
-        msg = "#{disc.kind} step '#{disc.name}' #call must accept kwargs: " \
-              "#{klass.required_kwargs.join(", ")} (missing: #{missing.join(", ")})"
-        raise UsageError.new(msg)
-      end
-
-      def safe_kind(klass)
-        klass.kind
-      rescue StandardError
-        nil
-      end
-
-      def descendants
-        ObjectSpace.each_object(Class).select { |c| c < Step::Base }
-      end
-
-      def rel(dir, path) = path.delete_prefix(dir.to_s).delete_prefix("/")
-    end
-  end
-end

data/lib/textus/step/observe.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # Reacts to a lifecycle event (Catalog::PUBSUB). 0..N per event,
-    # fire-and-forget, no meaningful return, timeout-isolated by the EventBus.
-    # Declares its event with `on :event_name` and an optional key filter with
-    # `match "glob.**"`. Replaces user pub/sub subscribers.
-    class Observe < Base
-      def self.on(event = :__read__)
-        if event == :__read__
-          @event
-        else
-          @event = event.to_sym
-        end
-      end
-
-      def self.match(glob = :__read__)
-        if glob == :__read__
-          @match
-        else
-          @match = glob
-        end
-      end
-
-      class << self
-        attr_reader :event
-      end
-    end
-  end
-end

data/lib/textus/step/registry_store.rb

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # The single home for registered steps. Reuses Step::EventBus for observe
-    # (pub/sub) dispatch — including its timeout isolation and error ring buffer
-    # — and holds a kind->{name->instance} table for the invocable kinds
-    # (fetch/transform/validate). Replaces the EventBus+RpcRegistryStore pair.
-    class RegistryStore
-      def initialize(error_log: Step::ErrorLog.new)
-        @bus   = Step::EventBus.new(error_log: error_log)
-        @table = Hash.new { |h, k| h[k] = {} }
-      end
-
-      # Register either a Step instance (invocable/observe table) or a pub/sub
-      # subscriber (`register(event, name, keys:, &block)`) for internal/spec
-      # probes.
-      def register(step, *, keys: nil, &)
-        return @bus.register(step, *, keys: keys, &) unless step.is_a?(Step::Base)
-
-        kind = step.class.kind
-        name = step.name.to_sym
-        return register_observe(step) if kind == :observe
-
-        raise UsageError.new("#{kind} '#{name}' already registered") if @table[kind].key?(name)
-
-        @table[kind][name] = step
-      end
-
-      # Invoke an invocable step. Mirrors the old RpcRegistryStore#invoke: inject
-      # caps only when #call declares :caps or accepts keyrest.
-      def invoke(kind, name, caps:, **other)
-        step = @table[kind][name.to_sym] or raise UsageError.new("unknown #{kind}: #{name}")
-        sig = Step::Signature.new(step.method(:call))
-        kwargs = other.dup
-        kwargs[:caps] = caps if sig.accepts_keyrest? || sig.declared_keys.include?(:caps)
-        step.call(**kwargs)
-      end
-
-      def names(kind)
-        return @bus.pubsub_handlers_names if kind.to_sym == :observe
-
-        @table[kind.to_sym].keys
-      end
-
-      def pubsub_handlers(event)
-        @bus.pubsub_handlers(event)
-      end
-
-      # Pub/sub passthrough (observe + internal built-in subscribers).
-      def publish(event, **) = @bus.publish(event, **)
-      def on(event, name, keys: nil, &) = @bus.register(event, name, keys: keys, &)
-      def on_error(&) = @bus.on_error(&)
-      def error_log = @bus.error_log
-
-      private
-
-      def register_observe(step)
-        sig = Step::Signature.new(step.method(:call))
-        @bus.register(step.class.event, step.name, keys: step.class.match) do |**kw|
-          step.call(**sig.filter(kw))
-        end
-      end
-    end
-  end
-end

data/lib/textus/step/signature.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    class Signature
-      def initialize(callable)
-        @params = callable.parameters
-      end
-
-      def accepts_keyrest?
-        @params.any? { |type, _| type == :keyrest }
-      end
-
-      def declared_keys
-        @params.each_with_object([]) { |(t, n), acc| acc << n if %i[keyreq key].include?(t) }
-      end
-
-      def missing(required)
-        return [] if accepts_keyrest?
-
-        required - declared_keys
-      end
-
-      def filter(kwargs)
-        return kwargs if accepts_keyrest?
-
-        kwargs.slice(*declared_keys)
-      end
-    end
-  end
-end

data/lib/textus/step/transform.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # Combines/reshapes projected rows into an artifact shape. Returns a Hash
-    # (the structured payload base) or an Array of rows. Replaces the
-    # :transform_rows RPC. (Phase 2 will widen `rows:` to a named `inputs:` map.)
-    class Transform < Base
-      def self.required_kwargs = %i[rows config]
-    end
-  end
-end

data/lib/textus/step/validate.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Step
-    # Checks an artifact/store state and returns diagnostics. Replaces the
-    # :validate RPC. Receives only `caps:` (injected by the registry).
-    class Validate < Base
-      def self.required_kwargs = []
-    end
-  end
-end

data/lib/textus/step.rb

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  # A Step is a unit of user-extensible behaviour discovered by convention at
-  # .textus/steps/<kind>/<name>.rb. Five kinds: fetch (external acquisition),
-  # transform (combine/reshape into an artifact), validate (check an artifact),
-  # observe (react to a lifecycle event). Replaces the Textus.hook block queue.
-  module Step
-  end
-end

data/lib/textus/surfaces/mcp/session.rb

@@ -1,9 +0,0 @@
-module Textus
-  module Surfaces
-    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
-end

data/lib/textus/surfaces/mcp/tool_schemas.rb

@@ -1,17 +0,0 @@
-module Textus
-  module Surfaces
-    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
-end