textus 0.26.0 → 0.29.0

data/lib/textus/ports/sentinel_store.rb

@@ -0,0 +1,67 @@
+require "json"
+require "digest"
+require "fileutils"
+
+module Textus
+  module Ports
+    # Persistence adapter for sentinel files. Owns the on-disk JSON shape, the
+    # path layout (<store_root>/sentinels/<target-rel-to-repo>.textus-managed.json),
+    # and all File/FileUtils I/O. Domain::Sentinel is a pure value object that
+    # depends on this port for reads and writes.
+    class SentinelStore
+      SUFFIX = ".textus-managed.json".freeze
+      DIR    = "sentinels".freeze
+
+      def write!(target:, source:, store_root:)
+        path = sentinel_path(target, store_root)
+        FileUtils.mkdir_p(File.dirname(path))
+        repo_root = File.dirname(store_root)
+        File.write(path, JSON.generate(
+                           "source" => rel_or_abs(source, repo_root),
+                           "target" => rel_or_abs(target, repo_root),
+                           "sha256" => Digest::SHA256.hexdigest(File.binread(target)),
+                           "mode" => "copy",
+                         ))
+      end
+
+      def load(path, repo_root)
+        raw = JSON.parse(File.read(path))
+        Textus::Domain::Sentinel.new(
+          target: absolutize(raw["target"], repo_root),
+          source: absolutize(raw["source"], repo_root),
+          sha256: raw["sha256"],
+          mode: raw["mode"],
+        )
+      rescue JSON::ParserError, Errno::ENOENT
+        nil
+      end
+
+      def sentinel_path(target, store_root)
+        repo_root = File.dirname(store_root)
+        rel = relative_to(target, repo_root) || File.basename(target)
+        File.join(store_root, DIR, rel + SUFFIX)
+      end
+
+      private
+
+      def rel_or_abs(path, repo_root)
+        relative_to(path, repo_root) || File.expand_path(path)
+      end
+
+      def relative_to(path, repo_root)
+        path = File.expand_path(path)
+        base = File.expand_path(repo_root)
+        return nil unless path.start_with?(base + File::SEPARATOR)
+
+        path[(base.length + 1)..]
+      end
+
+      def absolutize(path, repo_root)
+        return path if path.nil?
+        return path if File.absolute_path?(path)
+
+        File.expand_path(path, repo_root)
+      end
+    end
+  end
+end

data/lib/textus/ports/storage/file_stat.rb

@@ -0,0 +1,19 @@
+module Textus
+  module Ports
+    module Storage
+      # Read-only filesystem query port. The narrow interface that pure
+      # domain logic (staleness checks, sentinel value) depends on, so the
+      # domain never touches File/Dir directly. FileStore owns the write side.
+      class FileStat
+        def exists?(path)    = File.exist?(path)
+        def directory?(path) = File.directory?(path)
+        def read(path)       = File.binread(path)
+        def mtime(path)      = File.mtime(path)
+
+        # Ruby 3.3+ guarantees Dir.glob returns a sorted Array; no explicit sort
+        # needed, but callers can rely on ordered results for stable behaviour.
+        def glob(pattern)    = Dir.glob(pattern)
+      end
+    end
+  end
+end

data/lib/textus/{infra → ports}/storage/file_store.rb

@@ -1,7 +1,7 @@
 require "fileutils"
 
 module Textus
-  module Infra
+  module Ports
     module Storage
       # Pure filesystem I/O port. Wraps File/FileUtils/Etag with no knowledge
       # of envelopes, entries, schemas, or audit.

data/lib/textus/projection.rb

@@ -0,0 +1,91 @@
+require "time"
+require "timeout"
+
+module Textus
+  class Projection
+    MAX_LIMIT = 1000
+    REDUCER_TIMEOUT_SECONDS = 2
+
+    # `reader` — a callable `->(key) { envelope_or_nil }`. Caller picks
+    #   semantics: pure read (`ops.get`) for materialization paths;
+    #   `ops.get_or_refresh` if you want refresh-on-stale.
+    # `lister` — a callable `->(prefix:) { [ { "key" => ... }, ... ] }`.
+    # `rpc` — a `Hooks::RpcRegistry` used to dispatch `transform_rows` callables.
+    # `transform_context` — capability object handed to transform reducers as `caps:`.
+    def initialize(reader:, spec:, lister:, rpc:, transform_context:)
+      @reader            = reader
+      @spec              = spec || {}
+      @lister            = lister
+      @rpc               = rpc
+      @transform_context = transform_context
+      @limit = (@spec["limit"] || MAX_LIMIT).to_i
+      raise InvalidProjection.new("limit #{@limit} exceeds max #{MAX_LIMIT}") if @limit > MAX_LIMIT
+    end
+
+    def run
+      keys = collect_keys
+      explicit_pluck = !@spec["pluck"].nil? && @spec["pluck"] != "*"
+      rows = keys.map do |key|
+        env = @reader.call(key)
+        row = pluck(env.meta, env.body)
+        explicit_pluck ? row : row.merge("_key" => key)
+      end
+      reduced = apply_reducer(rows)
+      # Reducers may return either an Array of rows (legacy / templated builds)
+      # or a Hash that becomes the structured-format payload base. In the Hash
+      # case, downstream sort/limit/position markers don't apply, and the
+      # builder owns `_meta.generated_at` so we don't stamp it here.
+      return reduced if reduced.is_a?(Hash)
+
+      rows = reduced
+      rows = sort(rows)
+      rows = rows.first(@limit)
+      mark_positions(rows)
+      { "entries" => rows, "count" => rows.length, "generated_at" => Time.now.utc.iso8601 }
+    end
+
+    private
+
+    def apply_reducer(rows)
+      name = @spec["transform"] or return rows
+      Timeout.timeout(REDUCER_TIMEOUT_SECONDS) do
+        @rpc.invoke(:transform_rows, name,
+                    caps: @transform_context,
+                    rows: rows,
+                    config: @spec["transform_config"] || {})
+      end
+    rescue Timeout::Error
+      raise UsageError.new("transform_rows '#{name}' exceeded #{REDUCER_TIMEOUT_SECONDS}s timeout")
+    end
+
+    def collect_keys
+      prefixes = Array(@spec["select"])
+      prefixes.flat_map { |p| @lister.call(prefix: p).map { |row| row["key"] } }.uniq
+    end
+
+    def pluck(frontmatter, _body)
+      fields = @spec["pluck"]
+      if fields.nil? || fields == "*"
+        frontmatter
+      else
+        Array(fields).each_with_object({}) { |f, h| h[f] = frontmatter[f] if frontmatter.key?(f) }
+      end
+    end
+
+    # Adds `_first`, `_last`, and `_index` markers so templates can emit
+    # delimiters (e.g. JSON commas) via {{^_last}},{{/_last}}.
+    def mark_positions(rows)
+      last_idx = rows.length - 1
+      rows.each_with_index do |row, i|
+        row["_index"] = i
+        row["_first"] = i.zero?
+        row["_last"]  = (i == last_idx)
+      end
+    end
+
+    def sort(rows)
+      sb = @spec["sort_by"] or return rows
+      rows.sort_by { |r| r[sb].to_s }
+    end
+  end
+end

data/lib/textus/read/audit.rb

@@ -0,0 +1,111 @@
+require "json"
+require "time"
+
+module Textus
+  module Read
+    # Queries .textus/audit.log. Filters: key, zone, role, verb, since,
+    # correlation_id, limit. Reads the log file as JSON-Lines (legacy TSV
+    # rows produce nil and are skipped).
+    class Audit
+      # Value object that carries all filter parameters for an audit query.
+      # `matches?` checks the manifest-independent predicates so the loop body
+      # only needs to handle the zone check (which requires manifest access).
+      Query = Data.define(:key, :zone, :role, :verb, :since, :seq_since, :correlation_id, :limit) do
+        # rubocop:disable Metrics/ParameterLists
+        def self.build(key: nil, zone: nil, role: nil, verb: nil,
+                       since: nil, seq_since: nil, correlation_id: nil, limit: nil)
+          new(key:, zone:, role:, verb:, since:, seq_since:, correlation_id:, limit:)
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        def matches?(row)
+          return false if key && row["key"] != key
+          return false if role && row["role"] != role
+          return false if verb && row["verb"] != verb
+          return false if since && (row["ts"].nil? || Time.parse(row["ts"]) < since)
+          return false if seq_since && (row["seq"].nil? || row["seq"] <= seq_since)
+          return false if correlation_id && row.dig("extras", "correlation_id") != correlation_id
+
+          true
+        end
+      end
+
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest  = container.manifest
+        @root      = container.root
+        @log_path  = File.join(container.root, "audit.log")
+        @audit_log = container.audit_log
+      end
+
+      def call(**filters)
+        query = Query.build(**filters)
+        check_cursor_expiry!(query.seq_since)
+
+        files = all_log_files
+        return [] if files.empty?
+
+        rows = []
+        files.each do |file|
+          File.foreach(file) do |line|
+            parsed = parse_row(line.chomp)
+            next unless parsed
+            next unless query.matches?(parsed)
+            next if query.zone && !key_in_zone?(parsed["key"], query.zone)
+
+            rows << parsed
+            break if limit_reached?(rows, query)
+          end
+          break if limit_reached?(rows, query)
+        end
+        rows
+      end
+
+      # Accepts ISO8601 ("2026-01-15", "2026-01-15T10:00:00Z") or a relative
+      # offset matching /\A(\d+)([smhd])\z/. Returns nil for unparseable input.
+      def self.parse_since(str, now: Time.now.utc)
+        return nil if str.nil? || str.empty?
+        return Time.parse(str) if str =~ /\A\d{4}-\d{2}-\d{2}/
+
+        m = str.match(/\A(\d+)([smhd])\z/) or return nil
+        mult = { "s" => 1, "m" => 60, "h" => 3600, "d" => 86_400 }[m[2]]
+        now - (m[1].to_i * mult)
+      end
+
+      private
+
+      def limit_reached?(rows, query) = query.limit && rows.length >= query.limit
+
+      def check_cursor_expiry!(seq_since)
+        return unless seq_since
+
+        log = @audit_log || Textus::Ports::AuditLog.new(@root)
+        min = log.min_available_seq
+        raise Textus::CursorExpired.new(requested: seq_since, min_available: min) if min && seq_since < min - 1
+      end
+
+      def all_log_files
+        rotated = Dir.glob(File.join(@root, "audit.log.*"))
+                     .reject { |p| p.end_with?(".meta.json") }
+                     .sort_by { |p| -p.scan(/\d+$/).first.to_i } # .5 .4 .3 .2 .1 → oldest first
+        active = File.exist?(@log_path) ? [@log_path] : []
+        rotated + active
+      end
+
+      def parse_row(line)
+        return nil if line.empty?
+        return nil unless line.start_with?("{")
+
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def key_in_zone?(key, zone)
+        mentry = @manifest.resolver.resolve(key).entry
+        mentry && mentry.zone == zone
+      rescue Textus::Error
+        false
+      end
+    end
+  end
+end

data/lib/textus/read/blame.rb

@@ -0,0 +1,81 @@
+require "open3"
+
+module Textus
+  module Read
+    # For one key, joins every audit-log row with the git commit (sha,
+    # author, date, subject) that introduced the file state at that audit
+    # row. Falls back to `git => nil` when not in a git repo or when the
+    # file is untracked.
+    class Blame
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @container = container
+        @manifest  = container.manifest
+        @root      = container.root
+      end
+
+      def call(key:, limit: nil)
+        audit_rows = Textus::Read::Audit.new(container: @container).call(key: key, limit: limit)
+        path = resolve_path(key)
+        return audit_rows.map { |r| r.merge("git" => nil) } unless git_tracked?(path)
+
+        audit_rows.map { |r| r.merge("git" => git_commit_at(path, timestamp: r["ts"])) }
+      end
+
+      private
+
+      def resolve_path(key)
+        res = @manifest.resolver.resolve(key)
+        mentry = res.entry
+        path = res.path
+        # Nested entries resolve to a file under the entry path; leaf entries
+        # already have a fully-resolved path. Either way `path` is what git
+        # needs to know about.
+        path || Textus::Key::Path.resolve(@manifest.data, mentry)
+      rescue Textus::Error
+        nil
+      end
+
+      def git_tracked?(path)
+        return false if path.nil?
+        return false unless File.exist?(path)
+        return false unless git_repo?
+
+        _out, _err, status = Open3.capture3(
+          "git", "ls-files", "--error-unmatch", path,
+          chdir: @root
+        )
+        status.success?
+      rescue Errno::ENOENT
+        false
+      end
+
+      def git_repo?
+        # Walk up from store root to find a .git directory.
+        dir = @root
+        loop do
+          return true if File.directory?(File.join(dir, ".git"))
+
+          parent = File.dirname(dir)
+          return false if parent == dir
+
+          dir = parent
+        end
+      end
+
+      def git_commit_at(path, timestamp:)
+        args = ["git", "log", "-1"]
+        args << "--before=#{timestamp}" if timestamp
+        args += ["--format=%H%x09%an%x09%aI%x09%s", "--", path]
+        out, _err, status = Open3.capture3(*args, chdir: @root)
+        return nil unless status.success?
+
+        sha, author, date, subject = out.strip.split("\t", 4)
+        return nil if sha.nil? || sha.empty?
+
+        { "sha" => sha, "author" => author, "date" => date, "subject" => subject }
+      rescue Errno::ENOENT
+        nil
+      end
+    end
+  end
+end

data/lib/textus/read/boot.rb

@@ -0,0 +1,18 @@
+module Textus
+  module Read
+    # Dispatched use case for the `boot` verb. The orientation envelope is
+    # built by the Textus::Boot library module; this class is the uniform
+    # (container:, call:) entry point that Dispatcher::VERBS resolves to.
+    # Boot is role-independent, so `call` is not consulted.
+    class Boot
+      def initialize(container:, call:)
+        @container = container
+        @call      = call
+      end
+
+      def call
+        Textus::Boot.build(container: @container)
+      end
+    end
+  end
+end

data/lib/textus/read/deps.rb

@@ -0,0 +1,24 @@
+module Textus
+  module Read
+    class Deps
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest = container.manifest
+      end
+
+      def call(key)
+        entry = @manifest.data.entries.find { |e| e.key == key } or return []
+        return [] unless entry.is_a?(Textus::Manifest::Entry::Derived)
+
+        src = entry.source
+        result = if src.is_a?(Textus::Manifest::Entry::Derived::Projection)
+                   Array(src.select).compact
+                 elsif src.is_a?(Textus::Manifest::Entry::Derived::External)
+                   Array(src.sources).compact
+                 else
+                   []
+                 end
+        result.uniq
+      end
+    end
+  end
+end

data/lib/textus/read/doctor.rb

@@ -0,0 +1,19 @@
+module Textus
+  module Read
+    # Dispatched use case for the `doctor` verb. The health-check report is
+    # built by the Textus::Doctor library module; this class is the uniform
+    # (container:, call:) entry point that Dispatcher::VERBS resolves to.
+    # The acting role is irrelevant to a read-only health check, so `call`
+    # is not consulted.
+    class Doctor
+      def initialize(container:, call:)
+        @container = container
+        @call      = call
+      end
+
+      def call(checks: nil)
+        Textus::Doctor.build(container: @container, checks: checks)
+      end
+    end
+  end
+end

data/lib/textus/read/freshness.rb

@@ -0,0 +1,101 @@
+require "time"
+
+module Textus
+  module Read
+    # Per-entry freshness report. Walks every entry declared in the manifest,
+    # consults `rules_for(key)` for a refresh rule, and reports the
+    # current status. Status is one of :fresh, :stale, :never_refreshed, or
+    # :no_policy.
+    class Freshness
+      def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator)
+        @container  = container
+        @call       = call
+        @manifest   = container.manifest
+        @file_store = container.file_store
+        @evaluator  = evaluator
+        @cache      = {}
+      end
+
+      # Returns the soonest `next_due_at` across all entries with a refresh
+      # policy, as an ISO-8601 string, or nil if none.
+      def soonest_due(prefix: nil, zone: nil)
+        times = call(prefix: prefix, zone: zone)
+                .map { |r| r[:next_due_at] }
+                .compact
+                .map { |t| Time.parse(t) }
+        return nil if times.empty?
+
+        times.min.utc.iso8601
+      end
+
+      def call(prefix: nil, zone: nil)
+        rows = []
+        @manifest.data.entries.each do |mentry|
+          next if prefix && !mentry.key.start_with?(prefix)
+          next if zone && mentry.zone != zone
+
+          rows << row_for(mentry)
+        end
+        rows
+      end
+
+      private
+
+      def row_for(mentry)
+        set = @manifest.rules.for(mentry.key)
+        refresh = set.refresh
+        envelope = safe_get(mentry.key)
+        last = envelope&.meta&.dig("last_refreshed_at")
+
+        return base_row(mentry, last).merge(status: :no_policy) if refresh.nil?
+
+        fp = refresh.to_freshness_policy
+        cache_key = [mentry.key, last]
+        verdict = (@cache[cache_key] ||= @evaluator.call(fp, envelope, now: @call.now))
+        status = if verdict.fresh? then :fresh
+                 elsif last.nil?   then :never_refreshed
+                 else                   :stale
+                 end
+
+        base_row(mentry, last).merge(
+          ttl_seconds: fp.ttl_seconds,
+          on_stale: fp.on_stale,
+          status: status,
+          next_due_at: next_due(last, fp.ttl_seconds),
+        )
+      end
+
+      def base_row(mentry, last)
+        {
+          key: mentry.key,
+          zone: mentry.zone,
+          last_refreshed_at: last,
+          age_seconds: last ? (@call.now - Time.parse(last)).to_i : nil,
+        }
+      end
+
+      # Returns the raw envelope or nil. Nested entries (mentry.key is a
+      # prefix, not a leaf) and missing files both resolve to nil.
+      def safe_get(key)
+        res = @manifest.resolver.resolve(key)
+        return nil unless @file_store.exists?(res.path)
+
+        raw = @file_store.read(res.path)
+        parsed = Entry.for_format(res.entry.format).parse(raw, path: res.path)
+        Textus::Envelope.build(
+          key: key, mentry: res.entry, path: res.path,
+          meta: parsed["_meta"], body: parsed["body"],
+          etag: Etag.for_bytes(raw), content: parsed["content"]
+        )
+      rescue Textus::Error
+        nil
+      end
+
+      def next_due(last, ttl)
+        return nil if last.nil? || ttl.nil?
+
+        (Time.parse(last) + ttl).utc.iso8601
+      end
+    end
+  end
+end

data/lib/textus/read/get.rb

@@ -0,0 +1,66 @@
+module Textus
+  module Read
+    # Pure read: returns the on-disk envelope annotated with a freshness
+    # verdict. Never triggers refresh; never invokes the orchestrator.
+    #
+    # For interactive reads that want refresh-on-stale, use
+    # `Read::GetOrRefresh`, which composes this with the orchestrator.
+    class Get
+      def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator)
+        @container  = container
+        @call       = call
+        @manifest   = container.manifest
+        @file_store = container.file_store
+        @evaluator  = evaluator
+      end
+
+      def call(key)
+        envelope = read_raw_envelope(key)
+        return nil if envelope.nil?
+
+        policy_set = @manifest.rules.for(key)
+        refresh_policy = policy_set.refresh
+        return annotate_fresh(envelope) if refresh_policy.nil?
+
+        policy = refresh_policy.to_freshness_policy
+        verdict = @evaluator.call(policy, envelope, now: @call.now)
+
+        envelope.with(freshness: Textus::Domain::Freshness.build(
+          stale: verdict.stale?,
+          reason: verdict.reason,
+          refreshing: false,
+        ))
+      end
+
+      # Strict variant: raises UnknownKey when the entry is missing.
+      # Used by consumers (e.g. Validator) that need to distinguish absence
+      # from emptiness.
+      def get(key)
+        call(key) || raise(UnknownKey.new(key, suggestions: @manifest.resolver.suggestions_for(key)))
+      end
+
+      private
+
+      def read_raw_envelope(key)
+        res = @manifest.resolver.resolve(key)
+        mentry = res.entry
+        path = res.path
+        return nil unless @file_store.exists?(path)
+
+        raw = @file_store.read(path)
+        parsed = Entry.for_format(mentry.format).parse(raw, path: path)
+        Textus::Envelope.build(
+          key: key, mentry: mentry, path: path,
+          meta: parsed["_meta"], body: parsed["body"],
+          etag: Etag.for_bytes(raw), content: parsed["content"]
+        )
+      end
+
+      def annotate_fresh(envelope)
+        envelope.with(freshness: Textus::Domain::Freshness.build(
+          stale: false, reason: nil, refreshing: false,
+        ))
+      end
+    end
+  end
+end

data/lib/textus/read/get_or_refresh.rb

@@ -0,0 +1,69 @@
+module Textus
+  module Read
+    # Composes pure `Read::Get` with the refresh orchestrator: runs Get
+    # to obtain the envelope and freshness verdict, then if the verdict
+    # is stale and the rule's `on_stale` policy demands action, hands
+    # off to the orchestrator. Use for interactive reads where the
+    # caller wants the freshest obtainable envelope.
+    #
+    # Pure reads (build, projection, schema tooling) should use
+    # `Read::Get` directly; it has no orchestrator dependency.
+    class GetOrRefresh
+      def initialize(container:, call:, get: nil, orchestrator: nil)
+        @container    = container
+        @call         = call
+        @manifest     = container.manifest
+        @get          = get || Read::Get.new(container: container, call: call)
+        @orchestrator = orchestrator || build_orchestrator
+      end
+
+      private
+
+      def hook_context
+        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      end
+
+      def build_orchestrator
+        worker = Textus::Write::RefreshWorker.new(
+          container: @container, call: @call,
+        )
+        Textus::Write::RefreshOrchestrator.new(
+          worker: worker, store_root: @container.root, events: @container.events,
+          hook_context: hook_context
+        )
+      end
+
+      public
+
+      def call(key)
+        envelope = @get.call(key)
+        return nil if envelope.nil?
+        return envelope unless envelope.freshness&.stale
+
+        policy_set = @manifest.rules.for(key)
+        refresh_policy = policy_set.refresh
+        return envelope if refresh_policy.nil?
+
+        policy = refresh_policy.to_freshness_policy
+        verdict = Textus::Domain::Freshness::Verdict.stale(envelope.freshness.reason)
+        action = policy.decide(verdict)
+        outcome = @orchestrator.execute(action, key: key)
+
+        case outcome
+        when Textus::Domain::Outcome::Skipped
+          envelope
+        when Textus::Domain::Outcome::Refreshed
+          outcome.envelope.with(
+            freshness: Textus::Domain::Freshness.build(stale: false, reason: nil, refreshing: false),
+          )
+        when Textus::Domain::Outcome::Detached
+          envelope.with(freshness: envelope.freshness.with(refreshing: true))
+        when Textus::Domain::Outcome::Failed
+          envelope.with(
+            freshness: envelope.freshness.with(refresh_error: outcome.error.message),
+          )
+        end
+      end
+    end
+  end
+end