textus 0.49.0 → 0.51.0

data/lib/textus/ports/fetch/lock.rb

@@ -1,44 +0,0 @@
-require "fileutils"
-
-module Textus
-  module Ports
-    module Fetch
-      class Lock
-        def initialize(root:, key:)
-          @root = root
-          @key  = key
-          @path = File.join(Textus::Layout.locks(root), "#{safe_key}.lock")
-          @file = nil
-        end
-
-        def try_acquire # rubocop:disable Naming/PredicateMethod
-          FileUtils.mkdir_p(File.dirname(@path))
-          @file = File.open(@path, File::RDWR | File::CREAT, 0o644)
-          acquired = @file.flock(File::LOCK_EX | File::LOCK_NB)
-          unless acquired
-            @file.close
-            @file = nil
-            return false
-          end
-          @file.write(Process.pid.to_s)
-          @file.flush
-          true
-        end
-
-        def release
-          return unless @file
-
-          @file.flock(File::LOCK_UN)
-          @file.close
-          @file = nil
-        end
-
-        private
-
-        def safe_key
-          @key.to_s.gsub(/[^a-zA-Z0-9._-]/, "_")
-        end
-      end
-    end
-  end
-end

data/lib/textus/write/build.rb

@@ -1,90 +0,0 @@
-module Textus
-  module Write
-    # Single-pass build use case (the verb `build`, ADR 0061): dispatches
-    # polymorphically to each entry's `publish_via` method — the copy-out step
-    # (`publish` is the output-destination concept the verb drives, not the verb).
-    # Derived entries materialize their body via Materializer; Nested entries
-    # mirror their subtree via publish_tree; Leaf and Intake entries copy their
-    # stored body to publish_to targets. The Build layer owns wiring (context,
-    # accumulation) but not per-kind logic.
-    #
-    # Return shape: { "protocol", "built", "published_leaves" }
-    class Build
-      extend Textus::Contract::DSL
-
-      verb     :build
-      summary  "materialize derived entries; publish_to and publish_tree fan out copies"
-      surfaces :cli, :mcp
-      cli      "build"
-      around   :build_lock
-      arg :prefix, String, required: false, description: "limit the build to keys under this prefix"
-
-      def initialize(container:, call:)
-        @container = container
-        @call      = call
-        @manifest  = container.manifest
-      end
-
-      def call(prefix: nil)
-        build_role = @manifest.policy.actor_for("build") or
-          raise Textus::UsageError.new(
-            "no role holds the 'build' capability",
-            hint: "declare a role with `can: [build]` in .textus/manifest.yaml",
-          )
-        build_call = Textus::Call.build(
-          role: build_role,
-          correlation_id: @call.correlation_id,
-          dry_run: @call.dry_run,
-        )
-
-        built  = []
-        leaves = []
-        pruned = []
-        context = build_context(build_call)
-
-        @manifest.data.entries.each do |mentry|
-          next if prefix && !entry_matches_prefix?(mentry, prefix)
-
-          result = mentry.publish_via(context, prefix: prefix)
-          next if result.nil?
-
-          case result[:kind]
-          when :built then built << result[:value]
-          when :leaves
-            leaves.concat(result[:value])
-            pruned.concat(result[:pruned]) if result[:pruned]
-          end
-        end
-
-        { "protocol" => Textus::PROTOCOL, "built" => built, "published_leaves" => leaves, "pruned" => pruned }
-      end
-
-      private
-
-      def build_context(call)
-        Textus::Manifest::Entry::Base::PublishContext.new(
-          container: @container,
-          call: call,
-          reader: reader(call),
-        )
-      end
-
-      # Whether the entry should be processed for the given prefix filter.
-      def entry_matches_prefix?(mentry, prefix)
-        return true unless prefix
-
-        case mentry
-        when Textus::Manifest::Entry::Nested
-          mentry.key.start_with?(prefix) ||
-            prefix.start_with?("#{mentry.key}.")
-        else
-          mentry.key.start_with?(prefix)
-        end
-      end
-
-      def reader(call)
-        Textus::Read::Get.new(container: @container, call: call)
-      end
-    end
-  end
-end

data/lib/textus/write/fetch_events.rb

@@ -1,42 +0,0 @@
-module Textus
-  module Write
-    # Single home for the fetch lifecycle event vocabulary (ADR 0048 D5). Both
-    # FetchWorker (synchronous semantics) and FetchOrchestrator (async policy)
-    # emit through this seam so the event names and payload shapes live in one
-    # place with one derived hook context.
-    class FetchEvents
-      def self.from(container:, call:)
-        new(
-          events: container.events,
-          hook_context: Textus::Hooks::Context.for(container: container, call: call),
-        )
-      end
-
-      def initialize(events:, hook_context:)
-        @events = events
-        @hook_context = hook_context
-      end
-
-      def started(key, mode: :sync)
-        @events.publish(:fetch_started, ctx: @hook_context, key: key, mode: mode)
-      end
-
-      def failed(key, error)
-        @events.publish(:fetch_failed, ctx: @hook_context, key: key,
-                                       error_class: error.class.name, error_message: error.message)
-      end
-
-      def fetched(key, envelope, change)
-        return if change == :unchanged
-
-        @events.publish(:entry_fetched, ctx: @hook_context, key: key, envelope: envelope, change: change)
-      end
-
-      def backgrounded(key, started_at:, budget_ms:)
-        payload = { key: key, started_at: started_at, budget_ms: budget_ms }
-        payload[:ctx] = @hook_context if @hook_context
-        @events.publish(:fetch_backgrounded, **payload)
-      end
-    end
-  end
-end

data/lib/textus/write/fetch_orchestrator.rb

@@ -1,101 +0,0 @@
-module Textus
-  module Write
-    class FetchOrchestrator
-      # Collaborator (not a Dispatcher verb): constructed directly by FetchWorker /
-      # Read::Get, which pass their derived hook_context in. That's why this takes
-      # hook_context: explicitly while verb use cases derive their own.
-      def initialize(worker:, store_root:, events:, hook_context: nil, detached_spawner: nil)
-        @worker       = worker
-        @store_root   = store_root
-        @events       = events
-        @hook_context = hook_context
-        @detached_spawner = detached_spawner || default_spawner
-        @fetch_events = Textus::Write::FetchEvents.new(events: @events, hook_context: @hook_context)
-      end
-
-      def execute(action, key:)
-        case action
-        when Textus::Domain::Action::Return then Textus::Domain::Outcome::Skipped.new
-        when Textus::Domain::Action::FetchSync  then run_sync(key)
-        when Textus::Domain::Action::FetchTimed then run_timed(action.budget_ms, key)
-        else raise ArgumentError.new("unknown action: #{action.inspect}")
-        end
-      end
-
-      private
-
-      def run_sync(key)
-        envelope = @worker.run(key)
-        Textus::Domain::Outcome::Fetched.new(envelope: envelope)
-      rescue Textus::Error => e
-        Textus::Domain::Outcome::Failed.new(error: e)
-      end
-
-      def run_timed(budget_ms, key)
-        return run_timed_with_fork(budget_ms, key) if Textus::Ports::Fetch::Detached.supported?
-
-        run_timed_cooperative(budget_ms, key)
-      end
-
-      def run_timed_cooperative(budget_ms, key)
-        result = nil
-        thread = Thread.new do
-          result = @worker.run(key)
-        rescue Textus::Error => e
-          result = e
-        end
-
-        thread.join(budget_ms / 1000.0)
-        if thread.alive?
-          thread.kill
-          return Textus::Domain::Outcome::Failed.new(
-            error: Textus::UsageError.new(
-              "fetch exceeded budget #{budget_ms}ms (no fork available — cooperative cancel)",
-            ),
-          )
-        end
-
-        if result.is_a?(Textus::Error)
-          Textus::Domain::Outcome::Failed.new(error: result)
-        else
-          Textus::Domain::Outcome::Fetched.new(envelope: result)
-        end
-      end
-
-      def run_timed_with_fork(budget_ms, key)
-        result = nil
-        thread = Thread.new do
-          result = @worker.run(key)
-        rescue Textus::Error => e
-          result = e
-        end
-
-        thread.join(budget_ms / 1000.0)
-
-        if thread.alive?
-          thread.kill
-
-          # Single-flight: if a sibling process / earlier fork holds the
-          # per-leaf lock, don't fork another worker — they're already
-          # doing this work.
-          probe = Textus::Ports::Fetch::Lock.new(root: @store_root, key: key)
-          return Textus::Domain::Outcome::Detached.new unless probe.try_acquire
-
-          probe.release
-
-          @fetch_events.backgrounded(key, started_at: Time.now.utc.iso8601, budget_ms: budget_ms)
-          @detached_spawner.call(store_root: @store_root, key: key)
-          Textus::Domain::Outcome::Detached.new
-        elsif result.is_a?(Textus::Error)
-          Textus::Domain::Outcome::Failed.new(error: result)
-        else
-          Textus::Domain::Outcome::Fetched.new(envelope: result)
-        end
-      end
-
-      def default_spawner
-        Textus::Ports::Fetch::Detached.method(:spawn)
-      end
-    end
-  end
-end

data/lib/textus/write/fetch_worker.rb

@@ -1,127 +0,0 @@
-require "timeout"
-
-module Textus
-  module Write
-    # Internal fetch executor for one quarantine/intake entry. No longer a
-    # public verb (ADR 0079 collapsed the `fetch` surface): used by `get`'s
-    # orchestrator (read-through refresh) and by the `tend` sweep.
-    class FetchWorker
-      FETCH_TIMEOUT_SECONDS = IntakeFetch::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.is_a?(Textus::Manifest::Entry::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 ||= FetchEvents.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)
-        IntakeFetch.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(:fetch, key).check!(
-          Textus::Domain::Policy::Evaluation.new(
-            actor: @call.role, transition: :fetch, 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

data/lib/textus/write/intake_fetch.rb

@@ -1,25 +0,0 @@
-require "timeout"
-
-module Textus
-  module Write
-    # Invokes a :resolve_intake hook handler by name under a timeout — the single
-    # home for "call the intake handler under a deadline" (ADR 0048 D1). Shared by
-    # FetchWorker (the :fetch verb), `textus put --fetch`, and `textus hook run`.
-    # 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 IntakeFetch
-      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_intake, 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

data/lib/textus/write/materializer.rb

@@ -1,51 +0,0 @@
-require "fileutils"
-
-module Textus
-  module Write
-    # Materializes a single projection-derived manifest entry onto disk by
-    # running the builder pipeline (projection + template render). External
-    # entries are NOT materialized here — they are generated by an out-of-band
-    # runner and only staleness-tracked, so Derived#publish_via filters them out
-    # before reaching this point.
-    # Extracted from Write::Build so that Publish can reuse
-    # it without creating a Build dependency.
-    class Materializer
-      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 builder pipeline for `mentry` and returns the on-disk
-      # target_path string.
-      def run(mentry)
-        reader = Textus::Read::Get.new(container: @container, call: @call)
-        lister = Textus::Read::List.new(container: @container)
-        Builder::Pipeline.run(
-          mentry: mentry,
-          deps: Builder::Pipeline::Deps.new(
-            manifest: @manifest,
-            reader: reader.method(:call),
-            lister: lister.method(:call),
-            rpc: @rpc,
-            template_loader: ->(name) { read_template(name) },
-            transform_context: @container,
-            inject_boot: -> { Textus::Boot.build(container: @container) },
-          ),
-        )
-      end
-
-      private
-
-      def read_template(name)
-        tpl_path = File.join(@root, "templates", name)
-        raise TemplateError.new("template not found: #{tpl_path}", template_name: name) unless File.exist?(tpl_path)
-
-        File.read(tpl_path)
-      end
-    end
-  end
-end