textus 0.52.0 → 0.54.0

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/audit_subscriber.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module Textus
-  module Ports
-    # Writes an "event_error" audit row when a user hook raises during
-    # Hooks::EventBus publish. Attached at Store boot.
-    #
-    # Integration: uses Hooks::EventBus#on_error callback (chosen over a
-    # synthetic :hook_error event because the bus already owns the
-    # rescue and the failure is a bus-internal concern, not a domain
-    # event subscribers should be able to filter by key glob).
-    #
-    # Lifecycle audit rows for verb: "put" / "key_delete" / "key_mv" are written
-    # by Envelope::IO::Writer directly (it owns the
-    # audit-append-as-final-step invariant); this subscriber covers the
-    # hook-failure case the writer never sees.
-    class AuditSubscriber
-      def initialize(audit_log)
-        @audit_log = audit_log
-      end
-
-      def attach(bus)
-        bus.on_error do |event:, hook:, key:, kwargs:, error:|
-          record_error(event: event, hook: hook, key: key, kwargs: kwargs, error: error)
-        end
-        self
-      end
-
-      private
-
-      def record_error(event:, hook:, key:, kwargs:, error:)
-        extras = { "event" => event.to_s, "hook" => hook.to_s, "error" => "#{error.class}: #{error.message}" }
-        extras["target_key"]  = kwargs[:target_key]  if kwargs.key?(:target_key)
-        extras["pending_key"] = kwargs[:pending_key] if kwargs.key?(:pending_key)
-        @audit_log.append(
-          role: Textus::Role::AUTOMATION, verb: "event_error", key: key,
-          etag_before: nil, etag_after: nil, extras: extras
-        )
-      end
-    end
-  end
-end

data/lib/textus/ports/produce_on_write_subscriber.rb

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

data/lib/textus/produce/acquire/handler.rb

@@ -1,29 +0,0 @@
-require "timeout"
-
-module Textus
-  module Produce
-    module Acquire
-      # Invokes a :resolve_handler hook handler by name under a timeout — the single
-      # home for "call the intake handler under a deadline" (ADR 0048 D1). Shared by
-      # Produce::Acquire::Intake (the internal ingest mechanism — no public verb since ADR 0079)
-      # as driven by the converge sweep (drain/serve) and `textus hook run` (ADR 0089 made
-      # ingest system-pushed; there is no read or put trigger).
-      # Always passes a Container as `caps:` so the hook contract (ADR 0027) is
-      # uniform across every entry point. Maps Timeout::Error to a UsageError;
-      # leaves any other error to the caller (call sites differ in how they wrap).
-      module Handler
-        FETCH_TIMEOUT_SECONDS = 30
-
-        module_function
-
-        def invoke(caps:, handler:, config:, args:, label:, timeout: FETCH_TIMEOUT_SECONDS)
-          Timeout.timeout(timeout) do
-            caps.rpc.invoke(:resolve_handler, handler, caps: caps, config: config, args: args)
-          end
-        rescue Timeout::Error
-          raise Textus::UsageError.new("#{label} '#{handler}' exceeded #{timeout}s timeout")
-        end
-      end
-    end
-  end
-end

data/lib/textus/produce/acquire/intake.rb

@@ -1,130 +0,0 @@
-require "timeout"
-
-module Textus
-  module Produce
-    module Acquire
-      # Internal ingest executor for one machine-zone intake entry. No longer a
-      # public verb (ADR 0079 collapsed the `fetch` surface): used by the
-      # converge sweep (drain/serve) and `textus hook run` only — ingest is system-pushed
-      # (ADR 0089 removed the read-through that once also drove it).
-      class Intake
-        FETCH_TIMEOUT_SECONDS = Textus::Produce::Acquire::Handler::FETCH_TIMEOUT_SECONDS
-
-        def initialize(container:, call:)
-          @container    = container
-          @call         = call
-          @manifest     = container.manifest
-          @schemas      = container.schemas
-          @rpc          = container.rpc
-        end
-
-        # call(key) is the primary entry; run is kept as an alias for
-        # Orchestrator and FetchAll which call worker.run(key).
-        def call(key)
-          run(key)
-        end
-
-        def run(key)
-          res = @manifest.resolver.resolve(key)
-          mentry = res.entry
-          path = res.path
-          remaining = res.remaining
-          raise UsageError.new("no intake declared for '#{key}'") unless mentry.intake?
-
-          before_etag = @container.file_store.exists?(path) ? @container.file_store.etag(path) : nil
-          result = fetch_with_events(key, mentry, remaining)
-          persist_and_notify(key, mentry, result, before_etag)
-        end
-
-        def self.normalize_action_result(res, format:)
-          res = res.transform_keys(&:to_s) if res.is_a?(Hash)
-          res ||= {}
-          meta_val = res["_meta"]
-          body     = res["body"]
-          content  = res["content"]
-
-          case format
-          when "markdown" then { meta: meta_val || {}, body: body.to_s, content: nil }
-          when "text"     then { meta: {}, body: body.to_s, content: nil }
-          when "json", "yaml"
-            if !content.nil?
-              { meta: meta_val || {}, body: nil, content: content }
-            elsif !body.nil?
-              { meta: {}, body: body.to_s, content: nil }
-            else
-              raise Textus::UsageError.new("intake for #{format} returned neither content nor body")
-            end
-          else
-            raise Textus::UsageError.new("unknown format #{format.inspect}")
-          end
-        end
-
-        private
-
-        def fetch_events
-          @fetch_events ||= Textus::Produce::Events.from(container: @container, call: @call)
-        end
-
-        # ADR 0079: a per-rule fetch_timeout_seconds override was an accepted loss
-        # in the fetch:/retention: → lifecycle: collapse; the constant ceiling
-        # applies to every intake.
-        def fetch_timeout_for(_key)
-          FETCH_TIMEOUT_SECONDS
-        end
-
-        def fetch_with_events(key, mentry, remaining)
-          fetch_events.started(key)
-          call_intake(key, mentry, remaining)
-        end
-
-        def call_intake(key, mentry, remaining)
-          Textus::Produce::Acquire::Handler.invoke(
-            caps: @container, handler: mentry.handler,
-            config: mentry.config,
-            args: { trigger_key: key, leaf_segments: remaining || [] },
-            label: "intake", timeout: fetch_timeout_for(key)
-          )
-        rescue Textus::Error => e
-          fetch_events.failed(key, e)
-          raise
-        rescue StandardError => e
-          fetch_events.failed(key, e)
-          raise UsageError.new("intake '#{mentry.handler}' raised: #{e.class}: #{e.message}")
-        end
-
-        def persist_and_notify(key, mentry, result, before_etag)
-          normalized = self.class.normalize_action_result(result, format: mentry.format)
-          Textus::Domain::Policy::GuardFactory.new(
-            manifest: @manifest, schemas: @schemas,
-          ).for(:converge, key).check!(
-            Textus::Domain::Policy::Evaluation.new(
-              actor: @call.role, transition: :converge, origin: nil,
-              target: key, envelope: nil, manifest: @manifest
-            ),
-          )
-          envelope = writer.put(
-            key,
-            mentry: mentry,
-            payload: Textus::Envelope::IO::Writer::Payload.new(
-              meta: normalized[:meta], body: normalized[:body], content: normalized[:content],
-            ),
-          )
-          change = detect_change(before_etag, envelope)
-          fetch_events.fetched(key, envelope, change)
-          envelope
-        end
-
-        def detect_change(before_etag, envelope)
-          if before_etag.nil? then :created
-          elsif envelope.etag == before_etag then :unchanged
-          else :updated
-          end
-        end
-
-        def writer
-          @writer ||= Textus::Envelope::IO::Writer.from(container: @container, call: @call)
-        end
-      end
-    end
-  end
-end

data/lib/textus/produce/acquire/projection.rb

@@ -1,127 +0,0 @@
-require "fileutils"
-
-module Textus
-  module Produce
-    module Acquire
-      # Builds an entry's DATA artifact (ADR 0094) by running the projection
-      # pipeline; rendering is a publish concern. External entries are NOT built
-      # here — they are generated by an out-of-band runner; Derived#publish_via
-      # filters them out before reaching this point.
-      #
-      # Merges the former Write::DataBuilder wrapper and Builder::Pipeline module
-      # into one class (ADR 0100 produce/ topology refactor).
-      class Projection
-        # Injects provenance metadata as the first key in the serialized output.
-        # Carries only deterministic provenance (`from`/`reduce`) — the volatile
-        # `generated_at` is deliberately NOT stamped, so the built artifact is
-        # content-addressed and a rebuild is a byte-for-byte no-op (ADR 0070).
-        # Build time lives out of the tracked artifact.
-        module InjectMeta
-          def self.call(content_hash, mentry)
-            meta = {}
-            if mentry.derived?
-              src = mentry.source
-              if src.projection?
-                from = Array(src.select).compact
-                meta["from"] = from unless from.empty?
-                meta["reduce"] = src.transform if src.transform
-              end
-            end
-
-            out = { "_meta" => meta }
-            content_hash.each { |k, v| out[k] = v unless k == "_meta" }
-            out
-          end
-        end
-
-        Deps = Data.define(:manifest, :reader, :lister, :rpc, :transform_context)
-
-        def self.renderers
-          @renderers ||= {
-            "text" => Produce::Acquire::Serializer::Text,
-            "json" => Produce::Acquire::Serializer::Json,
-            "yaml" => Produce::Acquire::Serializer::Yaml,
-          }
-        end
-
-        def initialize(container:, call:)
-          @container  = container
-          @call       = call
-          @manifest   = container.manifest
-          @file_store = container.file_store
-          @rpc        = container.rpc
-          @root       = container.root
-        end
-
-        # Runs the projection pipeline for `mentry` and returns the on-disk
-        # target_path string.
-        def run(mentry)
-          reader   = Textus::Read::Get.new(container: @container, call: @call)
-          # Projections must be able to read source data from any nested entry,
-          # including keyless (publish_tree) ones like knowledge.decisions.
-          # The `include_keyless: true` option makes the resolver walk those dirs
-          # without exposing them on the public `list` / CLI surface (ADR 0047).
-          resolver = @manifest.resolver
-          lister = lambda do |prefix:|
-            resolver.enumerate(prefix: prefix, include_keyless: true)
-                    .map { |row| { "key" => row[:key], "zone" => row[:manifest_entry].zone, "path" => row[:path] } }
-          end
-          self.class.pipeline_run(
-            mentry: mentry,
-            deps: Deps.new(
-              manifest: @manifest,
-              reader: reader.method(:call),
-              lister: lister,
-              rpc: @rpc,
-              transform_context: @container,
-            ),
-          )
-        end
-
-        def self.pipeline_run(mentry:, deps:)
-          # 1. Load sources + project + reduce. Only projection-derived entries are
-          # buildable in-process; External entries are generated out-of-band and are
-          # filtered out upstream (Derived#publish_via), so reaching here with a
-          # non-projection source is a wiring bug — fail loudly rather than emit an
-          # empty payload (and never re-stamp the volatile generated_at, ADR 0070).
-          unless mentry.projection?
-            raise UsageError.new(
-              "builder: '#{mentry.key}' is not a projection-derived entry; only projections are buildable",
-            )
-          end
-
-          data =
-            Textus::Projection.new(
-              reader: deps.reader,
-              spec: mentry.source.projection_spec,
-              lister: deps.lister,
-              rpc: deps.rpc,
-              transform_context: deps.transform_context,
-            ).run
-
-          # 2. Serialize as DATA. Rendering through a template is a publish concern
-          # (ADR 0094) — the build never consults a template.
-          klass = renderers[mentry.format] or
-            raise UsageError.new("builder: unsupported data format #{mentry.format.inspect} for '#{mentry.key}'")
-          bytes = klass.new.call(mentry: mentry, data: data)
-
-          # 3. Write (idempotent: skip if only generated_at would differ)
-          target_path = Key::Path.resolve(deps.manifest.data, mentry)
-          FileUtils.mkdir_p(File.dirname(target_path))
-          write_if_changed(target_path, bytes, mentry.format)
-
-          target_path
-        end
-
-        # Built artifacts are content-addressed (no volatile timestamp, ADR 0070),
-        # so identity is plain byte-equality: skip the write when nothing changed.
-        # `format` is retained for signature stability across renderers.
-        def self.write_if_changed(target_path, bytes, _format)
-          return if File.exist?(target_path) && File.binread(target_path) == bytes
-
-          File.binwrite(target_path, bytes)
-        end
-      end
-    end
-  end
-end

data/lib/textus/produce/acquire/serializer/json.rb

@@ -1,31 +0,0 @@
-require "json"
-
-module Textus
-  module Produce
-    module Acquire
-      class Serializer
-        class Json < Serializer
-          def call(mentry:, data:)
-            content = default_shape(mentry, data)
-            final   = Produce::Acquire::Projection::InjectMeta.call(content, mentry)
-            Entry.for_format("json").serialize(meta: {}, body: "", content: final)
-          end
-
-          private
-
-          def default_shape(mentry, data)
-            has_transform = mentry.projection? &&
-                            mentry.source.transform
-            if has_transform && data.is_a?(Hash) && !data.key?("entries")
-              data
-            elsif data.is_a?(Hash) && data["entries"].is_a?(Array)
-              { "entries" => data["entries"] }
-            else
-              data.is_a?(Hash) ? data : { "entries" => Array(data) }
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/produce/acquire/serializer/text.rb

@@ -1,16 +0,0 @@
-module Textus
-  module Produce
-    module Acquire
-      class Serializer
-        class Text < Serializer
-          def call(mentry:, data:) # rubocop:disable Lint/UnusedMethodArgument
-            # Text format serializes data as plain-text. Rendering through a
-            # template is a publish concern (ADR 0094) — build emits data only.
-            body = data.is_a?(Hash) ? data.to_s : data.inspect
-            Entry.for_format("text").serialize(meta: {}, body: body)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/produce/acquire/serializer/yaml.rb

@@ -1,31 +0,0 @@
-require "yaml"
-
-module Textus
-  module Produce
-    module Acquire
-      class Serializer
-        class Yaml < Serializer
-          def call(mentry:, data:)
-            content = default_shape(mentry, data)
-            final   = Produce::Acquire::Projection::InjectMeta.call(content, mentry)
-            Entry.for_format("yaml").serialize(meta: {}, body: "", content: final)
-          end
-
-          private
-
-          def default_shape(mentry, data)
-            has_transform = mentry.projection? &&
-                            mentry.source.transform
-            if has_transform && data.is_a?(Hash) && !data.key?("entries")
-              data
-            elsif data.is_a?(Hash) && data["entries"].is_a?(Array)
-              { "entries" => data["entries"] }
-            else
-              data.is_a?(Hash) ? data : { "entries" => Array(data) }
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/produce/acquire/serializer.rb

@@ -1,17 +0,0 @@
-module Textus
-  module Produce
-    module Acquire
-      # Abstract base for output serializers. Each concrete serializer owns
-      # producing the bytes for one manifest format (json/yaml/text).
-      # Rendering through a template is a publish concern (ADR 0094) — serializers
-      # here only serialize data; they take no arguments.
-      class Serializer
-        def call(mentry:, data:)
-          _ = mentry
-          _ = data
-          raise NotImplementedError.new("#{self.class.name}#call not implemented")
-        end
-      end
-    end
-  end
-end