textus 0.50.0 → 0.51.0

data/lib/textus/domain/staleness/generator_check.rb

@@ -1,109 +0,0 @@
-require "time"
-
-module Textus
-  module Domain
-    class Staleness
-      # Reports staleness for generator-zone entries — derived files whose
-      # generator's listed sources have been modified more recently than the
-      # entry's `_meta.generated.at` timestamp. Returns an Array of row hashes
-      # (possibly empty) per entry.
-      class GeneratorCheck
-        def initialize(manifest:, file_stat:)
-          @manifest  = manifest
-          @file_stat = file_stat
-        end
-
-        def rows_for(mentry)
-          return [] unless applicable?(mentry)
-
-          path = Textus::Key::Path.resolve(@manifest.data, mentry)
-          reason = stale_reason(mentry, path)
-          reason ? [stale_row(mentry, path, reason)] : []
-        end
-
-        private
-
-        def applicable?(mentry)
-          mentry.in_generator_zone?(@manifest.policy) &&
-            mentry.is_a?(Textus::Manifest::Entry::Derived) &&
-            mentry.source.is_a?(Textus::Manifest::Entry::Derived::External)
-        end
-
-        def stale_reason(mentry, path)
-          return "derived entry has never been generated" unless @file_stat.exists?(path)
-
-          generated_at = generated_at_of(mentry, path)
-          return "missing generated.at frontmatter" unless generated_at
-
-          gen_time = parse_time(generated_at)
-          return "unparseable generated.at: #{generated_at.inspect}" unless gen_time
-
-          offender = newest_source_after(mentry.source, gen_time)
-          "source '#{offender}' modified after generated.at" if offender
-        end
-
-        def generated_at_of(mentry, path)
-          Entry.for_format(mentry.format).parse(@file_stat.read(path), path: path)["_meta"].dig("generated", "at")
-        end
-
-        def parse_time(str)
-          Time.parse(str.to_s)
-        rescue StandardError
-          nil
-        end
-
-        def newest_source_after(external_src, gen_time)
-          Array(external_src.sources).each do |src|
-            offender = check_source(src, gen_time)
-            return offender if offender
-          end
-          nil
-        end
-
-        def check_source(src, gen_time)
-          if src.match?(/\A[a-z0-9.][a-z0-9._-]*\z/) && !src.include?("/")
-            @manifest.resolver.enumerate(prefix: src).each do |row|
-              return src if @file_stat.mtime(row[:path]) > gen_time
-            end
-            nil
-          else
-            check_filesystem_source(src, gen_time)
-          end
-        end
-
-        def check_filesystem_source(src, gen_time)
-          abs = absolutize_source(src)
-          if @file_stat.directory?(abs)
-            dir_has_newer_file?(abs, gen_time) ? src : nil
-          elsif @file_stat.exists?(abs) && @file_stat.mtime(abs) > gen_time
-            src
-          end
-        end
-
-        def absolutize_source(src)
-          File.absolute_path?(src) ? src : File.join(File.dirname(@manifest.data.root), src)
-        end
-
-        def dir_has_newer_file?(abs, gen_time)
-          @file_stat.glob(File.join(abs, "**", "*")).any? do |fpath|
-            file?(fpath) && @file_stat.mtime(fpath) > gen_time
-          end
-        end
-
-        # FileStat substitute for File.file?: excludes directories but treats
-        # special files (FIFOs/sockets/devices) as regular files — acceptable
-        # because a generator source tree won't contain them.
-        def file?(fpath) = !@file_stat.directory?(fpath) && @file_stat.exists?(fpath)
-
-        def stale_row(mentry, path, reason)
-          {
-            "key" => mentry.key,
-            "path" => path,
-            "generator" => mentry.raw["compute"],
-            "reason" => reason,
-          }
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/staleness.rb

@@ -1,29 +0,0 @@
-module Textus
-  module Domain
-    class Staleness
-      # ADR 0079: intake (age-based) staleness moved to the unified lifecycle
-      # path (Domain::Lifecycle / freshness); only generator/build drift —
-      # dependency-based, surfaced by the doctor `generator_drift` check —
-      # remains here.
-      def initialize(manifest:, file_stat:, clock: nil) # rubocop:disable Lint/UnusedMethodArgument
-        @manifest = manifest
-        @generator_check = GeneratorCheck.new(manifest: manifest, file_stat: file_stat)
-      end
-
-      def call(prefix: nil, zone: nil)
-        @manifest.data.entries
-                 .select { |m| entry_matches?(m, prefix: prefix, zone: zone) }
-                 .flat_map { |m| @generator_check.rows_for(m) }
-      end
-
-      private
-
-      def entry_matches?(mentry, prefix:, zone:)
-        return false if zone && mentry.zone != zone
-        return false if prefix && !(mentry.key == prefix || mentry.key.start_with?("#{prefix}."))
-
-        true
-      end
-    end
-  end
-end

data/lib/textus/maintenance/tend.rb

@@ -1,110 +0,0 @@
-require "fileutils"
-
-module Textus
-  module Maintenance
-    # The destructive-only lifecycle sweep (ADR 0079, supersedes the composite
-    # 0078 body). Drives off the unified Domain::Lifecycle reporter: it applies
-    # destructive actions a read never performs (drop = delete via Write::KeyDelete;
-    # archive = copy to <store>/archive/ then delete) and refreshes cold expired
-    # intake entries (on_expire: refresh) via Write::FetchWorker. Non-destructive
-    # annotation (warn) is left to the lazy `get`/`freshness` path. Adds no new
-    # authority — every sub-op runs with the CALLER's own `call` (role), and is
-    # gated exactly as on its own.
-    class Tend
-      extend Textus::Contract::DSL
-
-      verb     :tend
-      summary  "Run the destructive lifecycle sweep: drop/archive expired entries, refresh cold intake, report health."
-      surfaces :cli, :mcp
-      cli      "tend"
-      arg :prefix,  String, description: "restrict the sweep to keys under this dotted prefix"
-      arg :zone,    String, description: "restrict the sweep to entries in this zone"
-      arg :dry_run, :boolean, default: false,
-                              description: "when true, report what the sweep WOULD do without applying; " \
-                                           "defaults to false, so omitting it drops/archives/refreshes immediately"
-
-      def initialize(container:, call:)
-        @container = container
-        @call      = call
-      end
-
-      def call(prefix: nil, zone: nil, dry_run: false)
-        rows = Textus::Domain::Lifecycle.new(
-          manifest: @container.manifest,
-          file_stat: Textus::Ports::Storage::FileStat.new,
-          clock: Textus::Ports::Clock,
-        ).call(prefix: prefix, zone: zone)
-
-        health = Read::Doctor.new(container: @container, call: @call).call
-        return dry_run_result(rows, health) if dry_run
-
-        apply_result(apply(rows), health)
-      end
-
-      private
-
-      def dry_run_result(rows, health)
-        {
-          "protocol" => Textus::PROTOCOL, "ok" => true, "dry_run" => true,
-          "would_drop" => action_keys(rows, "drop"),
-          "would_archive" => action_keys(rows, "archive"),
-          "would_refresh" => action_keys(rows, "refresh"),
-          "health" => health
-        }
-      end
-
-      def apply_result(result, health)
-        {
-          "protocol" => Textus::PROTOCOL,
-          "ok" => result[:failed].empty?,
-          "dry_run" => false,
-          "dropped" => result[:dropped], "archived" => result[:archived],
-          "refreshed" => result[:refreshed], "failed" => result[:failed],
-          "health" => health
-        }
-      end
-
-      def action_keys(rows, action)
-        rows.select { |r| r["action"] == action }.map { |r| r["key"] }
-      end
-
-      def apply(rows)
-        out = { dropped: [], archived: [], refreshed: [], failed: [] }
-        delete  = Write::KeyDelete.new(container: @container, call: @call)
-        refresh = Write::FetchWorker.new(container: @container, call: @call)
-
-        rows.each do |row|
-          key = row["key"]
-          begin
-            case row["action"]
-            when "drop"
-              delete.call(key)
-              out[:dropped] << key
-            when "archive"
-              archive_leaf(row)
-              delete.call(key)
-              out[:archived] << key
-            when "refresh"
-              refresh.run(key)
-              out[:refreshed] << key
-            end
-          rescue Textus::Error => e
-            out[:failed] << { "key" => key, "error" => e.message }
-          end
-        end
-        out
-      end
-
-      # Copy the leaf into <store>/archive/<relative-path> before deletion.
-      # (Lifted from the retired RetentionSweep#archive_leaf.)
-      def archive_leaf(row)
-        src  = row["path"]
-        root = @container.root.to_s
-        rel  = src.delete_prefix("#{root}/")
-        dest = File.join(root, "archive", rel)
-        FileUtils.mkdir_p(File.dirname(dest))
-        FileUtils.cp(src, dest)
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/derived.rb

@@ -1,67 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      class Derived < Base
-        Projection = ::Data.define(:select, :pluck, :sort_by, :transform)
-        External   = ::Data.define(:sources, :command)
-
-        attr_reader :source, :template, :inject_boot, :provenance, :events
-
-        def initialize(source:, template: nil, inject_boot: false, provenance: true, events: {}, **rest)
-          super(**rest)
-          @source = source
-          @template = template
-          @inject_boot = inject_boot
-          @provenance = provenance
-          @events = events || {}
-        end
-
-        def derived? = true
-        def projection? = @source.is_a?(Projection)
-        def external?   = @source.is_a?(External)
-
-        def publish_via(pctx, prefix: nil) # rubocop:disable Lint/UnusedMethodArgument
-          return nil unless in_generator_zone?(pctx.manifest.policy)
-          # External entries are produced by an out-of-band runner — textus has
-          # no in-process runner. The build path only tracks their staleness
-          # (Domain::Staleness::GeneratorCheck); materializing here would clobber
-          # the runner's artifact with an empty render. Skip the build entirely.
-          return nil if external?
-
-          target_path = Textus::Write::Materializer.new(
-            container: pctx.container, call: pctx.call,
-          ).run(self)
-
-          envelope = pctx.reader.call(@key)
-          Array(publish_to).each do |rel|
-            target_abs = File.join(pctx.repo_root, rel)
-            Textus::Ports::Publisher.publish(source: target_path, target: target_abs, store_root: pctx.root)
-            pctx.emit(:file_published, key: @key, envelope: envelope, source: target_path, target: target_abs)
-          end
-
-          src = @source
-          selects = src.is_a?(Projection) ? Array(src.select).compact : []
-          pctx.emit(:build_completed, key: @key, envelope: envelope, sources: selects)
-
-          { kind: :built, value: { "key" => @key, "path" => target_path, "published_to" => publish_to } }
-        end
-
-        KIND = :derived
-
-        def self.from_raw(common, raw)
-          source = Parser.parse_source(raw, common[:key])
-          new(
-            source: source,
-            template: raw["template"],
-            inject_boot: raw["inject_boot"] == true,
-            provenance: raw.fetch("provenance", true) != false,
-            events: raw["events"] || {},
-            **common,
-          )
-        end
-
-        Entry::REGISTRY[KIND] = self
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/intake.rb

@@ -1,31 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      class Intake < Base
-        attr_reader :handler, :config, :events
-
-        def initialize(handler:, config: {}, events: {}, **rest)
-          super(**rest)
-          @handler = handler
-          @config = config || {}
-          @events = events || {}
-        end
-
-        def intake?  = true
-        def nested?  = !!@raw["nested"]
-
-        KIND = :intake
-
-        def self.from_raw(common, raw)
-          intake = raw["intake"] || {}
-          handler = intake["handler"] || raw["intake_handler"] or
-            raise UsageError.new("intake entry '#{common[:key]}' missing handler")
-          config = intake["config"] || raw["intake_config"] || {}
-          new(handler: handler, config: config, events: raw["events"] || {}, **common)
-        end
-
-        Entry::REGISTRY[KIND] = self
-      end
-    end
-  end
-end

data/lib/textus/manifest/entry/validators/inject_boot.rb

@@ -1,21 +0,0 @@
-module Textus
-  class Manifest
-    class Entry
-      module Validators
-        module InjectBoot
-          def self.call(entry, policy:)
-            return unless entry.inject_boot
-
-            unless entry.in_generator_zone?(policy)
-              raise UsageError.new("entry '#{entry.key}': inject_boot: is only valid on derived entries")
-            end
-
-            return unless entry.template.nil?
-
-            raise UsageError.new("entry '#{entry.key}': inject_boot: requires a template:")
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/mcp/tools.rb

@@ -1,14 +0,0 @@
-module Textus
-  module MCP
-    # Thin delegator kept for name stability (ADR 0039). The dispatch table
-    # and JSON schemas are now DERIVED from per-verb contracts by MCP::Catalog;
-    # this module only forwards.
-    module Tools
-      module_function
-
-      def call(name, session:, store:, args:)
-        Catalog.call(name, session: session, store: store, args: args || {})
-      end
-    end
-  end
-end

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

@@ -1,52 +0,0 @@
-module Textus
-  module Ports
-    module Fetch
-      module Detached
-        module_function
-
-        def supported?
-          Process.respond_to?(:fork)
-        end
-
-        def acting_role(store)
-          store.manifest.policy.actor_for("fetch")
-        end
-
-        def spawn(store_root:, key:)
-          return nil unless supported?
-
-          pid = Process.fork do
-            $stdin.close
-            $stdout.reopen(File::NULL, "w")
-            $stderr.reopen(File::NULL, "w")
-
-            lock = Textus::Ports::Fetch::Lock.new(root: store_root, key: key)
-            exit(0) unless lock.try_acquire
-
-            begin
-              store = Textus::Store.new(store_root)
-              # No fetch-holder configured — exit the child cleanly. In practice
-              # this is unreachable: the background fork only happens after a
-              # foreground fetch was already authorized (so a fetch-holder
-              # exists). Config-time detection is doctor's job (ADR 0044 Q2).
-              role = acting_role(store)
-              exit(0) unless role
-              # FetchWorker is the internal executor since the public `fetch`
-              # verb was collapsed (ADR 0079); drive it directly.
-              Textus::Write::FetchWorker.new(
-                container: store.container, call: Textus::Call.build(role: role),
-              ).run(key)
-            rescue StandardError
-              # Already logged via :fetch_failed; exit cleanly.
-            ensure
-              lock.release
-              exit(0)
-            end
-          end
-          Process.detach(pid)
-          pid
-        end
-      end
-    end
-  end
-end

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