textus 0.52.0 → 0.54.0

data/lib/textus/hooks/context.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Hooks
-    # A narrow handle passed to user hooks 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(
-          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.events.publish(event, ctx: self, **)
-      end
-
-      def inspect
-        "#<Textus::Hooks::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?,
-          ),
-        )
-      end
-    end
-  end
-end

data/lib/textus/hooks/error_log.rb

@@ -1,32 +0,0 @@
-module Textus
-  module Hooks
-    # 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/hooks/event_bus.rb

@@ -1,114 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Hooks
-    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 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)
-        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
-          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]
-        end
-        [:ok, nil]
-      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/hooks/fire_report.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Hooks
-    # 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/hooks/loader.rb

@@ -1,54 +0,0 @@
-module Textus
-  module Hooks
-    class Loader
-      # A small DSL object passed to user hook blocks. Routes `.on(...)` to the
-      # EventBus and `.rpc(...)` / `.register(...)` to the RpcRegistry.
-      class Dsl
-        def initialize(events:, rpc:)
-          @events = events
-          @rpc    = rpc
-        end
-
-        # Pubsub registration — delegates to EventBus.
-        # Also handles RPC event names by delegating to RpcRegistry.
-        def on(event, name, keys: nil, &)
-          if Hooks::Catalog::RPC.key?(event.to_sym)
-            @rpc.register(event, name, &)
-          else
-            @events.register(event, name, keys: keys, &)
-          end
-        end
-
-        # Explicit RPC registration.
-        def register(event, name, &)
-          @rpc.register(event, name, &)
-        end
-      end
-
-      def initialize(events:, rpc:)
-        @events = events
-        @rpc    = rpc
-        @dsl    = Dsl.new(events: @events, rpc: @rpc)
-      end
-
-      def load_dir(dir)
-        return unless File.directory?(dir)
-
-        # Discard any leftover blocks from a prior partial load.
-        Textus.drain_hook_blocks
-
-        Dir.glob(File.join(dir, "**/*.rb")).sort.each do |f| # rubocop:disable Lint/RedundantDirGlobSort
-          load(f)
-        rescue StandardError, ScriptError => e
-          raise UsageError.new("failed loading hook #{File.basename(f)}: #{e.class}: #{e.message}")
-        end
-
-        Textus.drain_hook_blocks.each do |blk|
-          blk.call(@dsl)
-        rescue StandardError, ScriptError => e
-          raise UsageError.new("failed registering hook: #{e.class}: #{e.message}")
-        end
-      end
-    end
-  end
-end

data/lib/textus/hooks/rpc_registry.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Hooks
-    class RpcRegistry
-      def initialize
-        @table = Hash.new { |h, k| h[k] = {} }
-      end
-
-      def register(event, name, &blk)
-        event_sym = event.to_sym
-        raise UsageError.new("#{event_sym} is a pubsub event; register on EventBus") if Catalog::PUBSUB.key?(event_sym)
-
-        required = Catalog::RPC[event_sym] or raise UsageError.new("unknown RPC event: #{event}")
-        sig = Signature.new(blk)
-        missing = sig.missing(required)
-        raise UsageError.new("#{event_sym} RPC must accept kwargs: #{required.join(", ")} (missing: #{missing.join(", ")})") if missing.any?
-
-        name = name.to_sym
-        raise UsageError.new("#{event_sym} '#{name}' already registered") if @table[event_sym].key?(name)
-
-        @table[event_sym][name] = blk
-      end
-
-      def names(event) = @table[event.to_sym].keys
-
-      def callable(event, name)
-        @table[event.to_sym][name.to_sym] or raise UsageError.new("unknown #{event}: #{name}")
-      end
-
-      # Invoke a registered callable, injecting `caps:` only if the callable
-      # declares it (or accepts keyrest). Mis-named kwargs (e.g. the legacy
-      # `store:`) are rejected at registration time, not here.
-      def invoke(event, name, caps:, **other)
-        blk = callable(event, name)
-        sig = Signature.new(blk)
-        kwargs = other.dup
-        kwargs[:caps] = caps if sig.accepts_keyrest? || sig.declared_keys.include?(:caps)
-        blk.call(**kwargs)
-      end
-    end
-  end
-end

data/lib/textus/hooks/signature.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Hooks
-    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/init/templates/machine_intake.rb

@@ -1,45 +0,0 @@
-# .textus/hooks/machine_intake.rb
-# Scaffolded by `textus init` — CUSTOMIZE FREELY, or delete the feeds.machines
-# entry from manifest.yaml if you don't want it.
-# Feeds a per-host SNAPSHOT into feeds.machines.<host> on `textus drain`
-# (never on the per-turn boot/pulse path). It is NESTED so it grows to a fleet: the
-# `local` leaf scans THIS host; add ssh hosts with the cookbook recipe
-# (docs/cookbook/environment-scan.md). tracked:false → gitignored. Keep this an
-# ALLOWLIST of versions and counts — NEVER secrets, raw `env`, or package lists.
-Textus.hook do |reg|
-  reg.on(:resolve_handler, :machines) do |config:, args:, **|
-    machine = args[:leaf_segments].first or
-      raise "machines intake needs a host leaf, e.g. the 'local' in feeds.machines.local"
-    spec = (config["machines"] || {}).fetch(machine) { raise "unknown machine: #{machine}" }
-    unless (spec["via"] || "local").to_s == "local"
-      raise "machine #{machine}: only `via: local` is scaffolded — see " \
-            "docs/cookbook/environment-scan.md for the SSH (remote) fan-out"
-    end
-
-    sh    = ->(cmd) { `#{cmd}`.strip }                      # local shell-out, no network
-    ver   = ->(cmd) { o = `#{cmd} 2>/dev/null`.strip; o.empty? ? nil : o } # nil if tool absent
-    count = ->(cmd) { n = `#{cmd} 2>/dev/null`.strip.lines.size; n.zero? ? nil : n }
-    { content: {
-      # git_* describe THIS repo on the control host — only meaningful for `local`.
-      "git_head"       => sh.call("git rev-parse --short HEAD 2>/dev/null"),
-      "git_branch"     => sh.call("git rev-parse --abbrev-ref HEAD 2>/dev/null"),
-      "git_dirty"      => !sh.call("git status --porcelain 2>/dev/null").empty?,
-      "repo_root"      => sh.call("git rev-parse --show-toplevel 2>/dev/null"),
-      "captured_at"    => Time.now.utc.iso8601,
-      "os"             => RbConfig::CONFIG["host_os"],
-      "arch"           => RbConfig::CONFIG["host_cpu"],
-      "ruby_version"   => RUBY_VERSION,
-      "runtimes"       => {                                 # versions only; nil when not installed
-        "node"   => ver.call("node --version"),
-        "python" => ver.call("python3 --version"),
-        "go"     => ver.call("go version"),
-      },
-      "packages"       => {                                 # COUNTS only — never the list (size/secrets)
-        "brew" => count.call("brew list --formula"),        # ~1-3s on macOS; runs only on fetch, amortized by the ttl rule
-        "apt"  => count.call("dpkg-query -f '.\n' -W"),
-      },
-      "textus_version" => Textus::VERSION,
-      "protocol"       => Textus::PROTOCOL,
-    } }
-  end
-end

data/lib/textus/init/templates/orientation_reducer.rb

@@ -1,17 +0,0 @@
-# Reducer that reshapes the raw projection rows into the keys the
-# orientation.mustache template references. Without this, the template
-# would only have access to the flat rows list.
-Textus.hook do |reg|
-  reg.on(:transform_rows, :orientation_reducer) do |rows:, **|
-    project_row = rows.find { |r| r["_key"] == "knowledge.project" } || {}
-    runbook_rows = rows.select { |r| r["_key"]&.start_with?("knowledge.runbooks.") }
-
-    {
-      "project" => {
-        "name" => project_row["name"],
-        "description" => project_row["description"]
-      },
-      "runbooks" => runbook_rows.map { |r| { "name" => r["name"], "description" => r["description"] } }
-    }
-  end
-end

data/lib/textus/jobs/handlers.rb

@@ -1,62 +0,0 @@
-module Textus
-  module Jobs
-    # Wires the closed allow-list of convergence job types to the existing
-    # convergence code. Authority is read from the job's frozen `enqueued_by`
-    # and turned into the Call the handler runs under: produce self-elevates
-    # inside Produce::Engine regardless; destructive sweep runs AS the caller.
-    module Handlers
-      module_function
-
-      def registry
-        reg = Textus::Domain::Jobs::Registry.new
-        # produce is pure (self-elevates) — any caller may request a rematerialize.
-        reg.register("materialize", handler: method(:produce))
-        reg.register("re-pull",     handler: method(:produce))
-        # sweep is destructive — gate ad-hoc enqueue to the automation authority.
-        reg.register("sweep",       handler: method(:sweep), required_role: Textus::Role::AUTOMATION)
-        reg
-      end
-
-      # produce: render derived / re-pull intake for a single key. Engine
-      # self-elevates to the build actor internally; the passed call carries
-      # only correlation/dry_run plus the stamped role for audit. Engine#call
-      # isolates per-key produce errors into its result hash rather than raising,
-      # so surface them as :produce_failed events (the converge result hash used
-      # to carry them; the worker drops the return, so re-publish here).
-      def produce(job:, container:)
-        call = call_for(job)
-        result = Textus::Produce::Engine.converge(container: container, call: call, keys: [job.args["key"]])
-        return unless result.is_a?(Hash)
-
-        Array(result[:failed]).each do |failure|
-          container.events.publish(
-            :produce_failed,
-            ctx: Textus::Hooks::Context.for(container: container, call: call),
-            keys: [failure["key"]], error: failure["error"]
-          )
-        end
-      end
-
-      # sweep: compute retention rows for the scope, then apply destructively AS
-      # the job's role (no self-elevation).
-      def sweep(job:, container:)
-        call = call_for(job)
-        scope = job.args["scope"]
-        rows = Textus::Domain::Retention::Sweep.new(
-          manifest: container.manifest,
-          file_stat: Textus::Ports::Storage::FileStat.new,
-          clock: Textus::Ports::Clock.new,
-        ).call(prefix: scope_prefix(scope), zone: scope_zone(scope))
-        Textus::Maintenance::Retention::Apply.new(container: container, call: call).call(rows)
-      end
-
-      def call_for(job)
-        Textus::Call.build(role: job.enqueued_by || Textus::Role::AUTOMATION)
-      end
-
-      # A scope is `{ "prefix" => ..., "zone" => ... }` or nil (whole store).
-      def scope_prefix(scope) = scope.is_a?(Hash) ? scope["prefix"] : nil
-      def scope_zone(scope)   = scope.is_a?(Hash) ? scope["zone"]   : nil
-    end
-  end
-end

data/lib/textus/jobs/scheduler.rb

@@ -1,36 +0,0 @@
-module Textus
-  module Jobs
-    # Time-based seeding for the daemon: at each tick, enqueue a re-pull job for
-    # every intake key past its source.ttl and a sweep job to GC entries past
-    # retention.ttl. Dedup means a job already queued from a prior tick is a
-    # no-op. Both are stamped automation (the daemon's own authority); the sweep
-    # handler runs retention as that role.
-    class Scheduler
-      def initialize(container:, queue:)
-        @container = container
-        @queue = queue
-      end
-
-      def run_once
-        stale_intake.each do |key|
-          @queue.enqueue(job("re-pull", { "key" => key }))
-        end
-        @queue.enqueue(job("sweep", { "scope" => { "prefix" => nil, "zone" => nil } }))
-      end
-
-      private
-
-      def stale_intake
-        Textus::Domain::Freshness::Evaluator.new(
-          manifest: @container.manifest,
-          file_stat: Textus::Ports::Storage::FileStat.new,
-          clock: Textus::Ports::Clock.new,
-        ).stale_intake_keys(prefix: nil, zone: nil)
-      end
-
-      def job(type, args)
-        Textus::Domain::Jobs::Job.new(type: type, args: args, enqueued_by: Textus::Role::AUTOMATION)
-      end
-    end
-  end
-end

data/lib/textus/jobs/seeder.rb

@@ -1,57 +0,0 @@
-module Textus
-  module Jobs
-    # Enqueues the full convergence set for a scope: a produce job per derived /
-    # publish_tree / publish.to entry, a re-pull job per stale intake key, and a
-    # single sweep job for the scope. The scope logic mirrors
-    # the converge scope (Produce::Engine) so `drain` and `serve` converge identically.
-    # Produce jobs self-elevate (stamped automation); the sweep job carries the
-    # caller's role (destructive runs as caller).
-    class Seeder
-      def initialize(container:, queue:, call:)
-        @container = container
-        @queue = queue
-        @call = call
-        @manifest = container.manifest
-      end
-
-      def seed(prefix:, zone:)
-        file_stat = Textus::Ports::Storage::FileStat.new
-
-        producible_keys(prefix, zone).each do |key|
-          @queue.enqueue(job("materialize", { "key" => key }, Textus::Role::AUTOMATION))
-        end
-        stale_intake_keys(prefix, zone, file_stat).each do |key|
-          @queue.enqueue(job("re-pull", { "key" => key }, Textus::Role::AUTOMATION))
-        end
-        @queue.enqueue(job("sweep", { "scope" => { "prefix" => prefix, "zone" => zone } }, @call.role))
-      end
-
-      private
-
-      def job(type, args, role)
-        Textus::Domain::Jobs::Job.new(type: type, args: args, enqueued_by: role)
-      end
-
-      # Mirrors the converge scope (the publishable arm).
-      def producible_keys(prefix, zone)
-        @manifest.data.entries
-                 .select { |e| e.derived? || !e.publish_tree.nil? || !e.publish_to.empty? }
-                 .select { |e| in_scope?(e, prefix, zone) }
-                 .map(&:key)
-      end
-
-      def stale_intake_keys(prefix, zone, file_stat)
-        Textus::Domain::Freshness::Evaluator.new(
-          manifest: @manifest, file_stat: file_stat, clock: Textus::Ports::Clock.new,
-        ).stale_intake_keys(prefix: prefix, zone: zone)
-      end
-
-      def in_scope?(entry, prefix, zone)
-        return false if zone && entry.zone != zone
-        return false if prefix && !entry.key.start_with?(prefix)
-
-        true
-      end
-    end
-  end
-end

data/lib/textus/maintenance/drain.rb

@@ -1,42 +0,0 @@
-module Textus
-  module Maintenance
-    # Converge-and-exit: seed the full convergence set for the scope, run the
-    # worker until the queue is empty, return a health summary. Exits not-ok if
-    # any job dead-lettered. This is the converge entry point and what CI
-    # runs. Single-pass (serial) on purpose: each produce job self-locks via
-    # Produce::Engine.converge, so running them in turn keeps the build lock
-    # uncontended; a concurrent pool would make all-but-one produce job hit
-    # BuildInProgress and skip.
-    class Drain
-      extend Textus::Contract::DSL
-
-      verb     :drain
-      summary  "Converge everything now: seed produce + retention jobs and drain the queue to empty."
-      surfaces :cli, :mcp
-      cli      "drain"
-      arg :prefix, String, description: "restrict convergence to keys under this dotted prefix"
-      arg :zone,   String, description: "restrict convergence to entries in this zone"
-
-      def initialize(container:, call:)
-        @container = container
-        @call = call
-      end
-
-      def call(prefix: nil, zone: nil)
-        queue = Textus::Ports::Queue.new(root: @container.root)
-        Textus::Jobs::Seeder.new(container: @container, queue: queue, call: @call).seed(prefix: prefix, zone: zone)
-
-        summary = Worker.for(container: @container, queue: queue).drain
-        health = Read::Doctor.new(container: @container, call: @call).call
-
-        {
-          "protocol" => Textus::PROTOCOL,
-          "ok" => summary.failed.zero?,
-          "completed" => summary.completed,
-          "failed" => summary.failed,
-          "health" => health,
-        }
-      end
-    end
-  end
-end