textus 0.49.0 → 0.51.0

data/lib/textus/doctor/check/fetch_locks.rb

@@ -1,49 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      # Lists per-key fetch lock files under <root>/.run/locks/ whose
-      # recorded PID is no longer running. These are forensic artifacts only:
-      # Fetch::Lock uses flock(2), which the kernel releases on process
-      # death, so stale files do not block subsequent acquires. The check
-      # exists to let users clean up clutter and notice unexpected accumulation
-      # (e.g. a fetch path that crashes repeatedly).
-      class FetchLocks < Check
-        def call
-          dir = Textus::Layout.locks(root)
-          return [] unless File.directory?(dir)
-
-          Dir.glob(File.join(dir, "*.lock")).filter_map { |path| inspect_lock(path) }
-        end
-
-        private
-
-        def inspect_lock(path)
-          pid = File.read(path).strip.to_i
-          return nil if pid.zero?
-          return nil if pid_alive?(pid)
-
-          {
-            "code" => "fetch_lock.stale",
-            "level" => "info",
-            "subject" => path,
-            "message" => "fetch lock file at #{path} records dead PID #{pid} " \
-                         "(does not block fetch; flock is kernel-released on exit)",
-            "fix" => "safe to delete: rm #{path}",
-          }
-        rescue Errno::ENOENT
-          nil
-        end
-
-        def pid_alive?(pid)
-          Process.kill(0, pid)
-          true
-        rescue Errno::ESRCH
-          false
-        rescue Errno::EPERM
-          # Process exists but owned by another user — treat as alive.
-          true
-        end
-      end
-    end
-  end
-end

data/lib/textus/doctor/check/lifecycle_action_invalid.rb

@@ -1,39 +0,0 @@
-module Textus
-  module Doctor
-    class Check
-      # ADR 0079: refresh is valid only for intake entries; drop/archive are
-      # invalid for intake entries (they would re-fetch, not prune).
-      class LifecycleActionInvalid < Check
-        def call
-          manifest.data.entries.filter_map do |mentry|
-            policy = manifest.rules.for(mentry.key).lifecycle
-            next if policy.nil?
-
-            intake = mentry.is_a?(Textus::Manifest::Entry::Intake)
-            bad = (policy.on_expire == :refresh && !intake) || (policy.destructive? && intake)
-            next unless bad
-
-            issue_for(mentry, policy, intake)
-          end
-        end
-
-        private
-
-        def issue_for(mentry, policy, intake)
-          {
-            "code" => "lifecycle.action_invalid",
-            "level" => "error",
-            "subject" => mentry.key,
-            "message" => "on_expire: #{policy.on_expire} is not valid for a " \
-                         "#{intake ? "intake" : "stored"} entry",
-            "fix" => if intake
-                       "use on_expire: refresh|warn for intake entries"
-                     else
-                       "use on_expire: drop|archive|warn for stored entries"
-                     end,
-          }
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/freshness/policy.rb

@@ -1,18 +0,0 @@
-module Textus
-  module Domain
-    class Freshness
-      Policy = Data.define(:ttl_seconds, :on_stale, :sync_budget_ms) do
-        def decide(verdict)
-          return Action::Return.new if verdict.fresh?
-
-          case on_stale
-          when :warn       then Action::Return.new
-          when :sync       then Action::FetchSync.new
-          when :timed_sync then Action::FetchTimed.new(budget_ms: sync_budget_ms)
-          else                  Action::Return.new
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/lifecycle.rb

@@ -1,83 +0,0 @@
-require "time"
-
-module Textus
-  module Domain
-    # Unified lifecycle reporter (ADR 0079): which entries are past their ttl,
-    # and the on_expire action that applies. Replaces both Staleness::IntakeCheck
-    # and Retention. Age basis: _meta.last_fetched_at (intake) when present, else
-    # file mtime (stored). `self.verdict` is the pure per-entry decision that BOTH
-    # this reporter and `Read::Get` (Plan 2) call, so the basis logic lives once.
-    class Lifecycle
-      # Pure: is the entry past its ttl? -> [expired(bool), reason(String|nil)].
-      def self.verdict(policy:, last_fetched_at:, mtime:, now:)
-        ttl = policy.ttl_seconds
-        return [false, nil] if ttl.nil?
-
-        basis = parse_time(last_fetched_at) || mtime
-        return [true, "never recorded"] if basis.nil?
-
-        age = (now - basis).to_i
-        age > ttl ? [true, "ttl exceeded (age=#{age}s, ttl=#{ttl}s)"] : [false, nil]
-      end
-
-      def self.parse_time(str)
-        return nil if str.nil?
-
-        Time.parse(str.to_s)
-      rescue ArgumentError, TypeError
-        nil
-      end
-
-      def initialize(manifest:, file_stat:, clock:)
-        @manifest  = manifest
-        @file_stat = file_stat
-        @clock     = clock
-      end
-
-      def call(prefix: nil, zone: nil)
-        @manifest.data.entries
-                 .select { |m| entry_matches?(m, prefix: prefix, zone: zone) }
-                 .flat_map { |m| 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
-
-      def rows_for(mentry)
-        policy = @manifest.rules.for(mentry.key).lifecycle
-        return [] if policy.nil?
-
-        @manifest.resolver.enumerate(prefix: mentry.key).filter_map do |row|
-          path = row[:path]
-          next unless @file_stat.exists?(path)
-
-          expired, _reason = self.class.verdict(
-            policy: policy,
-            last_fetched_at: last_fetched_at_of(mentry, path),
-            mtime: @file_stat.mtime(path),
-            now: @clock.now,
-          )
-          next unless expired
-
-          {
-            "key" => row[:key], "path" => path,
-            "action" => policy.on_expire.to_s, "expired" => true
-          }
-        end
-      end
-
-      # Reads _meta.last_fetched_at from the on-disk envelope (intake basis).
-      def last_fetched_at_of(mentry, path)
-        Entry.for_format(mentry.format).parse(@file_stat.read(path), path: path)["_meta"]["last_fetched_at"]
-      rescue StandardError
-        nil
-      end
-    end
-  end
-end

data/lib/textus/domain/outcome.rb

@@ -1,10 +0,0 @@
-module Textus
-  module Domain
-    module Outcome
-      Skipped = Data.define
-      Fetched = Data.define(:envelope)
-      Detached  = Data.define
-      Failed    = Data.define(:error)
-    end
-  end
-end

data/lib/textus/domain/policy/lifecycle.rb

@@ -1,35 +0,0 @@
-module Textus
-  module Domain
-    module Policy
-      # Unified per-entry lifecycle policy (ADR 0079): one ttl + one action.
-      # Replaces the separate Fetch (ttl/on_stale) and Retention
-      # (expire_after/archive_after) policies. The action's destructiveness
-      # decides WHERE it runs: lazy actions (refresh/warn) on get/list reads;
-      # destructive actions (drop/archive) only on the tend sweep.
-      class Lifecycle
-        LAZY        = %i[refresh warn].freeze
-        DESTRUCTIVE = %i[drop archive].freeze
-        ALLOWED     = (LAZY + DESTRUCTIVE).freeze
-
-        attr_reader :on_expire, :budget_ms
-
-        def initialize(ttl:, on_expire:, budget_ms: nil)
-          action = on_expire.is_a?(Symbol) ? on_expire : on_expire.to_s.to_sym
-          unless ALLOWED.include?(action)
-            raise Textus::UsageError.new(
-              "lifecycle on_expire must be one of #{ALLOWED.join("|")}, got #{on_expire.inspect}",
-            )
-          end
-
-          @ttl       = ttl
-          @on_expire = action
-          @budget_ms = budget_ms
-        end
-
-        def ttl_seconds = Textus::Domain::Duration.seconds(@ttl)
-        def destructive? = DESTRUCTIVE.include?(@on_expire)
-        def lazy?        = LAZY.include?(@on_expire)
-      end
-    end
-  end
-end

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,65 +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, :events
-
-        def initialize(source:, template: nil, inject_boot: false, events: {}, **rest)
-          super(**rest)
-          @source = source
-          @template = template
-          @inject_boot = inject_boot
-          @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,
-            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