textus 0.20.2 → 0.26.0

data/lib/textus/application/read/audit.rb

@@ -0,0 +1,106 @@
+require "json"
+require "time"
+
+module Textus
+  module Application
+    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).
+      module Audit
+        def self.call(*, session:, ctx:, caps:, **) # rubocop:disable Lint/UnusedMethodArgument
+          Impl.new(caps: caps).call(*, **)
+        end
+
+        def self.parse_since(str, now: Time.now.utc)
+          Impl.parse_since(str, now: now)
+        end
+
+        class Impl
+          def initialize(caps:)
+            @manifest  = caps.manifest
+            @root      = caps.root
+            @log_path  = File.join(caps.root, "audit.log")
+            @audit_log = caps.audit_log
+          end
+
+          # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+          def call(key: nil, zone: nil, role: nil, verb: nil, since: nil, seq_since: nil, correlation_id: nil, limit: nil)
+            check_cursor_expiry!(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 if key && parsed["key"] != key
+                next if role && parsed["role"] != role
+                next if verb && parsed["verb"] != verb
+                next if zone && !key_in_zone?(parsed["key"], zone)
+                next if since && (parsed["ts"].nil? || Time.parse(parsed["ts"]) < since)
+                next if seq_since && (parsed["seq"].nil? || parsed["seq"] <= seq_since)
+                next if correlation_id && parsed.dig("extras", "correlation_id") != correlation_id
+
+                rows << parsed
+                break if limit && rows.length >= limit
+              end
+              break if limit && rows.length >= limit
+            end
+            rows
+          end
+          # rubocop:enable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+          # 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 check_cursor_expiry!(seq_since)
+            return unless seq_since
+
+            log = @audit_log || Textus::Infra::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
+  end
+end
+
+Textus::Application::UseCase.register(:audit, Textus::Application::Read::Audit, caps: :read)

data/lib/textus/application/read/blame.rb

@@ -0,0 +1,91 @@
+require "open3"
+
+module Textus
+  module Application
+    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.
+      module Blame
+        def self.call(*, session:, ctx:, caps:, **) # rubocop:disable Lint/UnusedMethodArgument
+          Impl.new(caps: caps).call(*, **)
+        end
+
+        class Impl
+          def initialize(caps:)
+            @caps = caps
+            @manifest = caps.manifest
+            @root     = caps.root
+          end
+
+          def call(key:, limit: nil)
+            audit_rows = Textus::Application::Read::Audit::Impl.new(caps: @caps).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
+  end
+end
+
+Textus::Application::UseCase.register(:blame, Textus::Application::Read::Blame, caps: :read)

data/lib/textus/application/read/deps.rb

@@ -0,0 +1,34 @@
+module Textus
+  module Application
+    module Read
+      module Deps
+        def self.call(*, session:, ctx:, caps:, **) # rubocop:disable Lint/UnusedMethodArgument
+          Impl.new(caps: caps).call(*, **)
+        end
+
+        class Impl
+          def initialize(caps:)
+            @manifest = caps.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
+  end
+end
+
+Textus::Application::UseCase.register(:deps, Textus::Application::Read::Deps, caps: :read)

data/lib/textus/application/read/freshness.rb

@@ -0,0 +1,110 @@
+require "time"
+
+module Textus
+  module Application
+    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.
+      module Freshness
+        def self.call(*, session:, ctx:, caps:, **) # rubocop:disable Lint/UnusedMethodArgument
+          Impl.new(ctx: ctx, caps: caps).call(*, **)
+        end
+
+        class Impl
+          def initialize(ctx:, caps:, evaluator: Textus::Domain::Freshness::Evaluator)
+            @ctx        = ctx
+            @manifest   = caps.manifest
+            @file_store = caps.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: @ctx.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 ? (@ctx.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
+  end
+end
+
+Textus::Application::UseCase.register(:freshness, Textus::Application::Read::Freshness, caps: :read)

data/lib/textus/application/read/get.rb

@@ -0,0 +1,75 @@
+module Textus
+  module Application
+    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.
+      module Get
+        def self.call(*, session:, ctx:, caps:, **) # rubocop:disable Lint/UnusedMethodArgument
+          Impl.new(ctx: ctx, caps: caps).call(*, **)
+        end
+
+        class Impl
+          def initialize(ctx:, caps:, evaluator: Textus::Domain::Freshness::Evaluator)
+            @ctx        = ctx
+            @manifest   = caps.manifest
+            @file_store = caps.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: @ctx.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
+  end
+end
+
+Textus::Application::UseCase.register(:get, Textus::Application::Read::Get, caps: :read)

data/lib/textus/application/read/get_or_refresh.rb

@@ -0,0 +1,63 @@
+module Textus
+  module Application
+    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.
+      module GetOrRefresh
+        def self.call(*, session:, ctx:, caps:, **)
+          Impl.new(
+            caps: caps,
+            get: Read::Get::Impl.new(ctx: ctx, caps: caps),
+            orchestrator: session.refresh_orchestrator,
+          ).call(*, **)
+        end
+
+        class Impl
+          def initialize(caps:, get:, orchestrator:)
+            @manifest     = caps.manifest
+            @get          = get
+            @orchestrator = orchestrator
+          end
+
+          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
+  end
+end
+
+Textus::Application::UseCase.register(:get_or_refresh, Textus::Application::Read::GetOrRefresh, caps: :write)

data/lib/textus/application/read/list.rb

@@ -0,0 +1,25 @@
+module Textus
+  module Application
+    module Read
+      module List
+        def self.call(*, session:, ctx:, caps:, **) # rubocop:disable Lint/UnusedMethodArgument
+          Impl.new(caps: caps).call(*, **)
+        end
+
+        class Impl
+          def initialize(caps:)
+            @manifest = caps.manifest
+          end
+
+          def call(prefix: nil, zone: nil)
+            rows = @manifest.resolver.enumerate(prefix: prefix)
+            rows = rows.select { |r| r[:manifest_entry].zone == zone } if zone
+            rows.map { |row| { "key" => row[:key], "zone" => row[:manifest_entry].zone, "path" => row[:path] } }
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:list, Textus::Application::Read::List, caps: :read)

data/lib/textus/application/read/policy_explain.rb

@@ -0,0 +1,47 @@
+module Textus
+  module Application
+    module Read
+      # For one key, surface every matching policy block along with the
+      # per-slot effective value (which loses ties win-by-specificity).
+      module PolicyExplain
+        def self.call(*, session:, ctx:, caps:, **) # rubocop:disable Lint/UnusedMethodArgument
+          Impl.new(caps: caps).call(*, **)
+        end
+
+        class Impl
+          def initialize(caps:)
+            @manifest = caps.manifest
+          end
+
+          def call(key:)
+            policies = @manifest.rules
+            matching = policies.explain(key)
+            winners  = policies.for(key)
+
+            {
+              key: key,
+              matched_blocks: matching.map do |b|
+                {
+                  match: b.match,
+                  refresh: !b.refresh.nil?,
+                  handler_allowlist: !b.handler_allowlist.nil?,
+                  promote: !b.promote.nil?,
+                }
+              end,
+              effective: {
+                refresh: winners.refresh && {
+                  ttl_seconds: winners.refresh.ttl_seconds,
+                  on_stale: winners.refresh.on_stale,
+                },
+                handler_allowlist: winners.handler_allowlist&.handlers,
+                promotion: winners.promote && { requires: winners.promote.requires },
+              },
+            }
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:policy_explain, Textus::Application::Read::PolicyExplain, caps: :read)

data/lib/textus/application/read/published.rb

@@ -0,0 +1,25 @@
+module Textus
+  module Application
+    module Read
+      module Published
+        def self.call(*, session:, ctx:, caps:, **) # rubocop:disable Lint/UnusedMethodArgument
+          Impl.new(caps: caps).call(*, **)
+        end
+
+        class Impl
+          def initialize(caps:)
+            @manifest = caps.manifest
+          end
+
+          def call
+            @manifest.data.entries.reject { |e| e.publish_to.empty? }.map do |e|
+              { "key" => e.key, "publish_to" => e.publish_to }
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:published, Textus::Application::Read::Published, caps: :read)

data/lib/textus/application/read/pulse.rb

@@ -0,0 +1,101 @@
+require "digest"
+require "time"
+
+module Textus
+  module Application
+    module Read
+      # Aggregator over audit + freshness + review + doctor. One round-trip
+      # for an agent's per-turn heartbeat. All component reads are existing
+      # APIs; pulse is sugar with a stable envelope shape and a monotonic
+      # cursor (seq).
+      module Pulse
+        def self.call(*, session:, ctx:, caps:, **)
+          Impl.new(ctx: ctx, caps: caps, session: session).call(*, **)
+        end
+
+        class Impl
+          def initialize(ctx:, caps:, session:)
+            @ctx = ctx
+            @caps = caps
+            @manifest   = caps.manifest
+            @file_store = caps.file_store
+            @audit_log  = caps.audit_log
+            @root       = caps.root
+            @events     = caps.events
+            @session    = session
+          end
+
+          def call(since: 0)
+            freshness_rows = freshness.call
+            {
+              "cursor" => @audit_log.latest_seq,
+              "changed" => audit_changes_since(since),
+              "stale" => freshness_rows.select { |r| r[:status] == :stale }.map { |r| r[:key] },
+              "pending_review" => review_keys,
+              "doctor" => doctor_summary,
+              "manifest_etag" => manifest_etag,
+              "next_due_at" => soonest_due(freshness_rows),
+              "hook_errors" => hook_errors_since(since),
+            }
+          end
+
+          private
+
+          def audit_changes_since(seq)
+            Read::Audit::Impl.new(caps: @caps).call(seq_since: seq)
+          end
+
+          def freshness
+            @freshness ||= Read::Freshness::Impl.new(ctx: @ctx, caps: @caps)
+          end
+
+          def soonest_due(rows)
+            times = rows.map { |r| r[:next_due_at] }.compact.map { |t| Time.parse(t) }
+            return nil if times.empty?
+
+            times.min.utc.iso8601
+          end
+
+          def review_keys
+            # List constructor takes only manifest:; returns hashes with string keys.
+            # Guard: zones is a Hash keyed by name string.
+            return [] unless @manifest.data.zones.key?("review")
+
+            rows = Read::List::Impl.new(caps: @caps).call(zone: "review")
+            rows.map { |r| r.is_a?(Hash) ? (r["key"] || r[:key]) : r }
+          end
+
+          def doctor_summary
+            result  = Textus::Doctor.run(@session)
+            issues  = result["issues"] || []
+            {
+              "ok" => result["ok"],
+              "warn" => issues.count { |i| i["level"] == "warning" },
+              "fail" => issues.count { |i| i["level"] == "error" },
+            }
+          end
+
+          def manifest_etag
+            Digest::SHA256.hexdigest(File.read(File.join(@root, "manifest.yaml")))
+          end
+
+          def hook_errors_since(seq)
+            @events.error_log.since(seq).map do |r|
+              {
+                "seq" => r[:seq],
+                "event" => r[:event].to_s,
+                "hook" => r[:hook].to_s,
+                "key" => r[:key],
+                "error_class" => r[:error_class],
+                "error_message" => r[:error_message],
+                "at" => r[:at],
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:pulse, Textus::Application::Read::Pulse, caps: :read)