textus 0.52.0 → 0.53.0

data/lib/textus/projection.rb

@@ -10,13 +10,13 @@ module Textus
     #   read on every path (ADR 0089): it annotates freshness but never ingests,
     #   so materialization and any other reader share the same side-effect-free read.
     # `lister` — a callable `->(prefix:) { [ { "key" => ... }, ... ] }`.
-    # `rpc` — a `Hooks::RpcRegistry` used to dispatch `transform_rows` callables.
+    # `rpc` — a `Step::RpcRegistry` used to dispatch `transform_rows` callables.
     # `transform_context` — capability object handed to transform reducers as `caps:`.
-    def initialize(reader:, spec:, lister:, rpc:, transform_context:)
+    def initialize(reader:, spec:, lister:, steps:, transform_context:)
       @reader            = reader
       @spec              = spec || {}
       @lister            = lister
-      @rpc               = rpc
+      @steps             = steps
       @transform_context = transform_context
       @limit = (@spec["limit"] || MAX_LIMIT).to_i
       raise InvalidProjection.new("limit #{@limit} exceeds max #{MAX_LIMIT}") if @limit > MAX_LIMIT
@@ -55,13 +55,13 @@ module Textus
     def apply_reducer(rows)
       name = @spec["transform"] or return rows
       Timeout.timeout(REDUCER_TIMEOUT_SECONDS) do
-        @rpc.invoke(:transform_rows, name,
-                    caps: @transform_context,
-                    rows: rows,
-                    config: @spec["transform_config"] || {})
+        @steps.invoke(:transform, name,
+                      caps: @transform_context,
+                      rows: rows,
+                      config: @spec["transform_config"] || {})
       end
     rescue Timeout::Error
-      raise UsageError.new("transform_rows '#{name}' exceeded #{REDUCER_TIMEOUT_SECONDS}s timeout")
+      raise UsageError.new("transform '#{name}' exceeded #{REDUCER_TIMEOUT_SECONDS}s timeout")
     end
 
     def collect_keys

data/lib/textus/schema/tools.rb

@@ -84,10 +84,11 @@ module Textus
       # Orchestrator-free read: schema tooling must never trigger a fetch
       # while inspecting/migrating entries (ADR 0062).
       def self.pure_get(store, role, key)
-        Textus::Read::Get.new(
-          container: store.as(role).container,
+        scope = store.as(role)
+        Textus::Action::Get.new(key: key).call(
+          container: scope.container,
           call: Textus::Call.build(role: role),
-        ).call(key)
+        )
       end
 
       def self.load_schema(store, name)

data/lib/textus/session.rb

@@ -1,15 +1,18 @@
 module Textus
   # The agent session: per-connection (MCP), per-process (CLI), or per-loop
   # (Ruby) orientation state — the audit cursor plus the contract etag and
-  # propose_zone captured at boot. Immutable Data value; advance_cursor
+  # propose_lane captured at boot. Immutable Data value; advance_cursor
   # returns a new instance. ADR 0036; contract_etag widened in ADR 0074.
-  Session = Data.define(:role, :cursor, :propose_zone, :contract_etag) do
+  Session = Data.define(:role, :cursor, :propose_lane, :contract_etag) do
+    # Back-compat reader while lane terminology migrates.
+    def propose_zone = propose_lane
+
     def advance_cursor(new_cursor) = with(cursor: new_cursor)
 
     def check_etag!(observed_etag)
       return if observed_etag == contract_etag
 
-      raise Textus::MCP::ContractDrift.new(
+      raise Textus::Surfaces::MCP::ContractDrift.new(
         "contract changed (manifest/hooks/schemas were #{short_etag(contract_etag)}, " \
         "now #{short_etag(observed_etag)}); re-run boot",
       )

data/lib/textus/step/base.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Textus
+  module Step
+    class Base
+      class << self
+        # The step kind is derived from class hierarchy.
+        def kind
+          return :fetch if defined?(Step::Fetch) && self <= Step::Fetch
+          return :transform if defined?(Step::Transform) && self <= Step::Transform
+          return :validate if defined?(Step::Validate) && self <= Step::Validate
+          return :observe if defined?(Step::Observe) && self <= Step::Observe
+
+          raise NotImplementedError.new("#{self} is not a known step kind")
+        end
+
+        # Required #call kwargs the loader validates against the subclass.
+        def required_kwargs = []
+
+        # Built-ins (and only built-ins) override the registered name when the
+        # Ruby class name can't carry it (e.g. "markdown-links").
+        def step_name(value = :__read__)
+          if value == :__read__
+            @step_name
+          else
+            @step_name = value.to_s
+          end
+        end
+      end
+
+      # Assigned by the loader/registry at registration time.
+      attr_accessor :name
+    end
+  end
+end

data/lib/textus/step/builtin/csv_fetch.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "csv"
+require "yaml"
+
+module Textus
+  module Step
+    module Builtin
+      class CsvFetch < Step::Fetch
+        step_name "csv"
+        def call(config:, args:, **)
+          _ = args
+          rows = CSV.parse(config["bytes"].to_s, headers: true).map(&:to_h)
+          { _meta: {}, body: YAML.dump(rows) }
+        end
+      end
+    end
+  end
+end

data/lib/textus/step/builtin/ical_events_fetch.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Textus
+  module Step
+    module Builtin
+      class IcalEventsFetch < Step::Fetch
+        step_name "ical-events"
+        def call(config:, args:, **)
+          _ = args
+          events_list = []
+          current = nil
+          config["bytes"].to_s.each_line do |line|
+            line = line.strip
+            case line
+            when "BEGIN:VEVENT" then current = {}
+            when "END:VEVENT"
+              events_list << current if current
+              current = nil
+            when /\A(SUMMARY|DTSTART|DTEND|UID|LOCATION|DESCRIPTION):(.*)\z/
+              current[Regexp.last_match(1).downcase] = Regexp.last_match(2) if current
+            end
+          end
+          { _meta: {}, body: YAML.dump(events_list) }
+        end
+      end
+    end
+  end
+end

data/lib/textus/step/builtin/json_fetch.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module Textus
+  module Step
+    module Builtin
+      class JsonFetch < Step::Fetch
+        step_name "json"
+        def call(config:, args:, **)
+          _ = args
+          { _meta: {}, body: YAML.dump(JSON.parse(config["bytes"].to_s)) }
+        end
+      end
+    end
+  end
+end

data/lib/textus/step/builtin/markdown_links_fetch.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Textus
+  module Step
+    module Builtin
+      class MarkdownLinksFetch < Step::Fetch
+        step_name "markdown-links"
+        def call(config:, args:, **)
+          _ = args
+          links = config["bytes"].to_s.scan(%r{\[([^\]]+)\]\((https?://[^)\s]+)\)}).map do |text, href|
+            { "text" => text, "href" => href }
+          end
+          { _meta: {}, body: YAML.dump(links) }
+        end
+      end
+    end
+  end
+end

data/lib/textus/step/builtin/rss_fetch.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "rexml/document"
+require "yaml"
+
+module Textus
+  module Step
+    module Builtin
+      class RssFetch < Step::Fetch
+        step_name "rss"
+        def call(config:, args:, **)
+          _ = args
+          doc = REXML::Document.new(config["bytes"].to_s)
+          items = doc.elements.to_a("//item").map do |item|
+            {
+              "title" => item.elements["title"]&.text,
+              "link" => item.elements["link"]&.text,
+              "pubDate" => item.elements["pubDate"]&.text,
+            }
+          end
+          { _meta: {}, body: YAML.dump(items) }
+        end
+      end
+    end
+  end
+end

data/lib/textus/step/builtin.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Textus
+  module Step
+    # Registers the framework-provided fetch steps (json/csv/markdown-links/
+    # ical-events/rss) into a registry at Store construction. The successor to
+    # Step::Builtin.register_all.
+    module Builtin
+      STEPS = [
+        JsonFetch, CsvFetch, MarkdownLinksFetch, IcalEventsFetch, RssFetch
+      ].freeze
+
+      def self.register_all(registry)
+        STEPS.each do |klass|
+          step = klass.new
+          step.name = klass.step_name
+          registry.register(step)
+        end
+      end
+    end
+  end
+end

data/lib/textus/{hooks → step}/catalog.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module Textus
-  module Hooks
-    # The single source of truth for hook event names and their required
-    # kwargs. EventBus, RpcRegistry, and the Loader DSL router all read these
+  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

data/lib/textus/{hooks → step}/context.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 module Textus
-  module Hooks
-    # A narrow handle passed to user hooks in place of the raw Store.
+  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::RoleScope.new(
+        scope = Textus::Surfaces::RoleScope.new(
           container: container,
           role: call.role,
           correlation_id: call.correlation_id,
@@ -48,24 +48,26 @@ module Textus
 
       # fan-out
       def publish_followup(event, **)
-        @scope.container.events.publish(event, ctx: self, **)
+        @scope.container.steps.publish(event, ctx: self, **)
       end
 
       def inspect
-        "#<Textus::Hooks::Context role=#{@role} correlation_id=#{@correlation_id}>"
+        "#<Textus::Step::Context role=#{@role} correlation_id=#{@correlation_id}>"
       end
 
       private
 
       def pure_reader
-        @pure_reader ||= Textus::Read::Get.new(
-          container: @scope.container,
-          call: Textus::Call.build(
-            role: @scope.role,
-            correlation_id: @scope.correlation_id,
-            dry_run: @scope.dry_run?,
-          ),
-        )
+        @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

data/lib/textus/step/discovery.rb

@@ -0,0 +1,24 @@
+# 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/{hooks → step}/error_log.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Hooks
+  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".

data/lib/textus/{hooks → step}/event_bus.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require "timeout"
+
 module Textus
-  module Hooks
+  module Step
     class EventBus
       HOOK_TIMEOUT_SECONDS = 2
 
@@ -40,6 +42,8 @@ module Textus
 
       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 = []
@@ -68,24 +72,19 @@ module Textus
 
       def invoke(event, sub, key, kwargs)
         accepted = Signature.new(sub[:callable]).filter(kwargs)
-        error = nil
-        # Thread#kill is unsafe in general but bounded here: post-commit, isolated, only a runaway user hook is affected.
-        thread = Thread.new do
-          sub[:callable].call(**accepted)
-        rescue StandardError => e
-          error = e
-        end
-        if thread.join(HOOK_TIMEOUT_SECONDS).nil?
-          thread.kill
+        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)
-          return [:timed_out, err]
-        end
-        if error
-          notify_error(event, sub, key, kwargs, error)
-          return [:errored, error]
+          [:timed_out, err]
+        rescue StandardError => e
+          notify_error(event, sub, key, kwargs, e)
+          [:errored, e]
         end
-        [:ok, nil]
       end
 
       def notify_error(event, sub, key, kwargs, error)

data/lib/textus/step/fetch.rb

@@ -0,0 +1,13 @@
+# 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/{hooks → step}/fire_report.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Textus
-  module Hooks
+  module Step
     # Outcome of a single Dispatcher#publish call.
     #
     # fired      — hook names that ran to completion

data/lib/textus/step/loader.rb

@@ -0,0 +1,108 @@
+# 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

@@ -0,0 +1,31 @@
+# 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

@@ -0,0 +1,66 @@
+# 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/{hooks → step}/signature.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Textus
-  module Hooks
+  module Step
     class Signature
       def initialize(callable)
         @params = callable.parameters

data/lib/textus/step/transform.rb

@@ -0,0 +1,12 @@
+# 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