textus 0.22.0 → 0.26.0

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)

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

@@ -0,0 +1,35 @@
+module Textus
+  module Application
+    module Read
+      module Rdeps
+        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)
+            @manifest.data.entries.each_with_object([]) do |e, acc|
+              next unless e.is_a?(Textus::Manifest::Entry::Derived)
+
+              src = e.source
+              sources = 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
+              acc << e.key if sources.any? { |s| s == key || key.start_with?("#{s}.") }
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:rdeps, Textus::Application::Read::Rdeps, caps: :read)

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

@@ -0,0 +1,26 @@
+module Textus
+  module Application
+    module Read
+      module SchemaEnvelope
+        def self.call(*, session:, ctx:, caps:, **) # rubocop:disable Lint/UnusedMethodArgument
+          Impl.new(caps: caps).call(*, **)
+        end
+
+        class Impl
+          def initialize(caps:)
+            @manifest = caps.manifest
+            @schemas  = caps.schemas
+          end
+
+          def call(key)
+            mentry = @manifest.resolver.resolve(key).entry
+            schema = @schemas.fetch_or_nil(mentry.schema)
+            { "protocol" => PROTOCOL, "key" => key, "schema_ref" => mentry.schema, "schema" => schema&.to_h }
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:schema_envelope, Textus::Application::Read::SchemaEnvelope, caps: :read)

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

@@ -0,0 +1,23 @@
+module Textus
+  module Application
+    module Read
+      module Stale
+        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)
+            Textus::Domain::Staleness.new(manifest: @manifest).call(prefix: prefix, zone: zone)
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:stale, Textus::Application::Read::Stale, caps: :read)

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

@@ -0,0 +1,30 @@
+module Textus
+  module Application
+    module Read
+      module Uid
+        def self.call(*, session:, ctx:, caps:, **) # rubocop:disable Lint/UnusedMethodArgument
+          Impl.new(ctx: ctx, caps: caps).call(*, **)
+        end
+
+        class Impl
+          def initialize(ctx:, caps:)
+            @ctx = ctx
+            @caps = caps
+          end
+
+          def call(key)
+            get.get(key).uid
+          end
+
+          private
+
+          def get
+            @get ||= Get::Impl.new(ctx: @ctx, caps: @caps)
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:uid, Textus::Application::Read::Uid, caps: :read)

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

@@ -0,0 +1,32 @@
+module Textus
+  module Application
+    module Read
+      module ValidateAll
+        def self.call(*, session:, ctx:, caps:, **) # rubocop:disable Lint/UnusedMethodArgument
+          Impl.new(ctx: ctx, caps: caps).call(*, **)
+        end
+
+        class Impl
+          def initialize(ctx:, caps:)
+            @ctx = ctx
+            @caps = caps
+            @manifest  = caps.manifest
+            @schemas   = caps.schemas
+            @audit_log = caps.audit_log
+          end
+
+          def call
+            Validator.new(
+              reader: Get::Impl.new(ctx: @ctx, caps: @caps),
+              manifest: @manifest,
+              audit_log: @audit_log,
+              schema_for: ->(name) { @schemas.fetch_or_nil(name) },
+            ).call
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:validate_all, Textus::Application::Read::ValidateAll, caps: :read)

data/lib/textus/application/{reads → read}/validator.rb

@@ -1,6 +1,6 @@
 module Textus
   module Application
-    module Reads
+    module Read
       class Validator
         def initialize(reader:, manifest:, audit_log:, schema_for:)
           @reader = reader
@@ -55,7 +55,7 @@ module Textus
           last_writer = @audit_log.last_writer_for(key)
           return if last_writer.nil?
 
-          last_writer_is_authority = @manifest.role_kind(last_writer) == :accept_authority
+          last_writer_is_authority = @manifest.policy.role_kind(last_writer) == :accept_authority
 
           env.meta.each_key do |field|
             owner = schema.maintained_by(field)

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

@@ -0,0 +1,26 @@
+module Textus
+  module Application
+    module Read
+      module Where
+        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)
+            res = @manifest.resolver.resolve(key)
+            mentry = res.entry
+            path = res.path
+            { "protocol" => PROTOCOL, "key" => key, "zone" => mentry.zone, "owner" => mentry.owner, "path" => path }
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:where, Textus::Application::Read::Where, caps: :read)