textus 0.22.0 → 0.29.0

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

@@ -1,82 +0,0 @@
-require "open3"
-
-module Textus
-  module Application
-    module Reads
-      # 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(manifest:, root:)
-          @manifest = manifest
-          @root = root
-        end
-
-        def call(key:, limit: nil)
-          audit_rows = Textus::Application::Reads::Audit.new(manifest: @manifest, root: @root).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, 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

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

@@ -1,26 +0,0 @@
-module Textus
-  module Application
-    module Reads
-      class Deps
-        def initialize(manifest:)
-          @manifest = manifest
-        end
-
-        def call(key)
-          entry = @manifest.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

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

@@ -1,88 +0,0 @@
-require "time"
-
-module Textus
-  module Application
-    module Reads
-      # 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(ctx:, manifest:, file_store:, evaluator: Textus::Domain::Freshness::Evaluator)
-          @ctx        = ctx
-          @manifest   = manifest
-          @file_store = file_store
-          @evaluator  = evaluator
-        end
-
-        def call(prefix: nil, zone: nil)
-          rows = []
-          @manifest.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
-          verdict = @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)
-          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

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

@@ -1,67 +0,0 @@
-module Textus
-  module Application
-    module Reads
-      # 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
-      # `Reads::GetOrRefresh`, which composes this with the orchestrator.
-      class Get
-        def initialize(ctx:, manifest:, file_store:, evaluator: Textus::Domain::Freshness::Evaluator)
-          @ctx        = ctx
-          @manifest   = manifest
-          @file_store = 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)
-          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

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

@@ -1,51 +0,0 @@
-module Textus
-  module Application
-    module Reads
-      # Composes pure `Reads::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
-      # `Reads::Get` directly; it has no orchestrator dependency.
-      class GetOrRefresh
-        def initialize(manifest:, get:, orchestrator:)
-          @manifest     = 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

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

@@ -1,17 +0,0 @@
-module Textus
-  module Application
-    module Reads
-      class List
-        def initialize(manifest:)
-          @manifest = 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

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

@@ -1,39 +0,0 @@
-module Textus
-  module Application
-    module Reads
-      # For one key, surface every matching policy block along with the
-      # per-slot effective value (which loses ties win-by-specificity).
-      class PolicyExplain
-        def initialize(manifest:)
-          @manifest = 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

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

@@ -1,17 +0,0 @@
-module Textus
-  module Application
-    module Reads
-      class Published
-        def initialize(manifest:)
-          @manifest = manifest
-        end
-
-        def call
-          @manifest.entries.reject { |e| e.publish_to.empty? }.map do |e|
-            { "key" => e.key, "publish_to" => e.publish_to }
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,63 +0,0 @@
-module Textus
-  module Application
-    module Reads
-      # 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).
-      class Pulse
-        def initialize(ctx:, manifest:, file_store:, audit_log:, root:, store:)
-          @ctx        = ctx
-          @manifest   = manifest
-          @file_store = file_store
-          @audit_log  = audit_log
-          @root       = root
-          @store      = store
-        end
-
-        def call(since: 0)
-          changed = audit_changes_since(since)
-          {
-            "cursor" => @audit_log.latest_seq,
-            "changed" => changed,
-            "stale" => stale_keys,
-            "pending_review" => review_keys,
-            "doctor" => doctor_summary,
-          }
-        end
-
-        private
-
-        def audit_changes_since(seq)
-          Reads::Audit.new(manifest: @manifest, root: @root, audit_log: @audit_log)
-                      .call(seq_since: seq)
-        end
-
-        def stale_keys
-          # Freshness rows use symbol keys: { key: "x.y", status: :stale, ... }
-          rows = Reads::Freshness.new(ctx: @ctx, manifest: @manifest, file_store: @file_store).call
-          rows.select { |r| r[:status] == :stale }.map { |r| r[:key] }
-        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.zones.key?("review")
-
-          rows = Reads::List.new(manifest: @manifest).call(zone: "review")
-          rows.map { |r| r.is_a?(Hash) ? (r["key"] || r[:key]) : r }
-        end
-
-        def doctor_summary
-          result  = Textus::Doctor.run(@store)
-          issues  = result["issues"] || []
-          {
-            "ok" => result["ok"],
-            "warn" => issues.count { |i| i["level"] == "warning" },
-            "fail" => issues.count { |i| i["level"] == "error" },
-          }
-        end
-      end
-    end
-  end
-end

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

@@ -1,27 +0,0 @@
-module Textus
-  module Application
-    module Reads
-      class Rdeps
-        def initialize(manifest:)
-          @manifest = manifest
-        end
-
-        def call(key)
-          @manifest.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

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

@@ -1,18 +0,0 @@
-module Textus
-  module Application
-    module Reads
-      class SchemaEnvelope
-        def initialize(manifest:, schemas:)
-          @manifest = manifest
-          @schemas = 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

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

@@ -1,15 +0,0 @@
-module Textus
-  module Application
-    module Reads
-      class Stale
-        def initialize(manifest:)
-          @manifest = manifest
-        end
-
-        def call(prefix: nil, zone: nil)
-          Textus::Domain::Staleness.new(manifest: @manifest).call(prefix: prefix, zone: zone)
-        end
-      end
-    end
-  end
-end

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

@@ -1,23 +0,0 @@
-module Textus
-  module Application
-    module Reads
-      class Uid
-        def initialize(ctx:, manifest:, file_store:)
-          @ctx        = ctx
-          @manifest   = manifest
-          @file_store = file_store
-        end
-
-        def call(key)
-          get.get(key).uid
-        end
-
-        private
-
-        def get
-          @get ||= Get.new(ctx: @ctx, manifest: @manifest, file_store: @file_store)
-        end
-      end
-    end
-  end
-end

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

@@ -1,24 +0,0 @@
-module Textus
-  module Application
-    module Reads
-      class ValidateAll
-        def initialize(ctx:, manifest:, file_store:, schemas:, audit_log:)
-          @ctx        = ctx
-          @manifest   = manifest
-          @file_store = file_store
-          @schemas    = schemas
-          @audit_log  = audit_log
-        end
-
-        def call
-          Validator.new(
-            reader: Get.new(ctx: @ctx, manifest: @manifest, file_store: @file_store),
-            manifest: @manifest,
-            audit_log: @audit_log,
-            schema_for: ->(name) { @schemas.fetch_or_nil(name) },
-          ).call
-        end
-      end
-    end
-  end
-end

data/lib/textus/application/reads/validator.rb

@@ -1,86 +0,0 @@
-module Textus
-  module Application
-    module Reads
-      class Validator
-        def initialize(reader:, manifest:, audit_log:, schema_for:)
-          @reader = reader
-          @manifest = manifest
-          @audit_log = audit_log
-          @schema_for = schema_for
-        end
-
-        def call
-          violations = []
-          check_content_violations(violations)
-          check_role_authority_violations(violations)
-          { "protocol" => PROTOCOL, "ok" => violations.empty?, "violations" => violations }
-        end
-
-        private
-
-        def check_content_violations(violations)
-          @manifest.resolver.enumerate.each do |row|
-            key = row[:key]
-            mentry = row[:manifest_entry]
-            env = fetch_envelope(key, violations) or next
-            schema = mentry.schema && @schema_for.call(mentry.schema)
-            next unless schema
-
-            begin
-              validate_schema!(schema, env, mentry.format)
-            rescue Textus::Error => e
-              violations << { "key" => key, "code" => e.code, "message" => e.message }
-            end
-          end
-        end
-
-        def check_role_authority_violations(violations)
-          @manifest.resolver.enumerate.each do |row|
-            mentry = row[:manifest_entry]
-            next unless mentry.schema
-
-            schema = @schema_for.call(mentry.schema)
-            next unless schema
-
-            env = begin
-              @reader.get(row[:key])
-            rescue StandardError
-              next
-            end
-            append_authority_violations(violations, row[:key], env, schema)
-          end
-        end
-
-        def append_authority_violations(violations, key, env, schema)
-          last_writer = @audit_log.last_writer_for(key)
-          return if last_writer.nil?
-
-          last_writer_is_authority = @manifest.role_kind(last_writer) == :accept_authority
-
-          env.meta.each_key do |field|
-            owner = schema.maintained_by(field)
-            next if owner.nil? || last_writer == owner || last_writer_is_authority
-
-            violations << { "key" => key, "code" => "role_authority",
-                            "field" => field, "expected" => owner, "last_writer" => last_writer }
-          end
-        end
-
-        def fetch_envelope(key, violations)
-          @reader.get(key)
-        rescue Textus::Error => e
-          violations << { "key" => key, "code" => e.code, "message" => e.message }
-          nil
-        end
-
-        def validate_schema!(schema, envelope, format)
-          payload = case format
-                    when "json", "yaml" then envelope.content || {}
-                    else envelope.meta || {}
-                    end
-          schema.validate!(payload)
-        end
-      end
-    end
-  end
-end

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

@@ -1,18 +0,0 @@
-module Textus
-  module Application
-    module Reads
-      class Where
-        def initialize(manifest:)
-          @manifest = 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