textus 0.8.1 → 0.10.0

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

@@ -0,0 +1,69 @@
+require "json"
+require "time"
+
+module Textus
+  module Application
+    module Reads
+      # 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
+        def initialize(ctx:)
+          @ctx = ctx
+          @log_path = File.join(@ctx.store.root, "audit.log")
+        end
+
+        # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        def call(key: nil, zone: nil, role: nil, verb: nil, since: nil, correlation_id: nil, limit: nil)
+          return [] unless File.exist?(@log_path)
+
+          rows = []
+          File.foreach(@log_path) 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 correlation_id && parsed.dig("extras", "correlation_id") != correlation_id
+
+            rows << parsed
+            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 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, = @ctx.store.manifest.resolve(key)
+          mentry && mentry.zone == zone
+        rescue Textus::Error
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+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(ctx:)
+          @ctx = ctx
+        end
+
+        def call(key:, limit: nil)
+          audit_rows = Textus::Composition.audit(@ctx).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)
+          mentry, path, = @ctx.store.manifest.resolve(key)
+          # 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(@ctx.store.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: @ctx.store.root
+          )
+          status.success?
+        rescue Errno::ENOENT
+          false
+        end
+
+        def git_repo?
+          # Walk up from store root to find a .git directory.
+          dir = @ctx.store.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: @ctx.store.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/freshness.rb

@@ -0,0 +1,77 @@
+require "time"
+
+module Textus
+  module Application
+    module Reads
+      # Per-entry freshness report. Walks every entry declared in the manifest,
+      # consults `policies_for(key)` for a refresh policy, and reports the
+      # current status. Status is one of :fresh, :stale, :never_refreshed, or
+      # :no_policy.
+      class Freshness
+        def initialize(ctx:, evaluator: Textus::Domain::Freshness::Evaluator)
+          @ctx = ctx
+          @evaluator = evaluator
+        end
+
+        def call(prefix: nil, zone: nil)
+          rows = []
+          @ctx.store.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 = @ctx.store.manifest.policies_for(mentry.key)
+          refresh = set.refresh
+          envelope = safe_get(mentry.key)
+          last = envelope&.dig("_meta", "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)
+          @ctx.store.reader.read_raw_envelope(key)
+        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

@@ -0,0 +1,62 @@
+module Textus
+  module Application
+    module Reads
+      class Get
+        def initialize(ctx:, orchestrator:, evaluator: Textus::Domain::Freshness::Evaluator)
+          @ctx          = ctx
+          @orchestrator = orchestrator
+          @evaluator    = evaluator
+        end
+
+        def call(key)
+          envelope = @ctx.store.reader.read_raw_envelope(key)
+          return nil if envelope.nil?
+
+          policy_set = @ctx.store.manifest.policies_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)
+
+          return annotate(envelope, verdict, refreshing: false) if verdict.fresh?
+
+          action = policy.decide(verdict)
+          outcome = @orchestrator.execute(action, key: key)
+
+          case outcome
+          when Textus::Domain::Outcome::Skipped
+            annotate(envelope, verdict, refreshing: false)
+          when Textus::Domain::Outcome::Refreshed
+            fresh_verdict = @evaluator.call(policy, outcome.envelope, now: @ctx.now)
+            annotate(outcome.envelope, fresh_verdict, refreshing: false)
+          when Textus::Domain::Outcome::Detached
+            annotate(envelope, verdict, refreshing: true)
+          when Textus::Domain::Outcome::Failed
+            annotate(envelope, verdict, refreshing: false, refresh_error: outcome.error.message)
+          end
+        end
+
+        private
+
+        def annotate(envelope, verdict, refreshing:, refresh_error: nil)
+          envelope = envelope.dup
+          envelope["stale"]         = verdict.stale?
+          envelope["stale_reason"]  = verdict.reason
+          envelope["refreshing"]    = refreshing
+          envelope["refresh_error"] = refresh_error if refresh_error
+          envelope
+        end
+
+        # No refresh policy applies to this key — treat as fresh, skip evaluation/orchestration.
+        def annotate_fresh(envelope)
+          envelope = envelope.dup
+          envelope["stale"]        = false
+          envelope["stale_reason"] = nil
+          envelope["refreshing"]   = false
+          envelope
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+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(ctx:)
+          @ctx = ctx
+        end
+
+        def call(key:)
+          policies = @ctx.store.manifest.policies
+          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,
+              promote_requires: winners.promote&.requires,
+            },
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/refresh/all.rb

@@ -0,0 +1,41 @@
+module Textus
+  module Application
+    module Refresh
+      module All
+        module_function
+
+        def call(ctx, prefix: nil, zone: nil)
+          worker = Textus::Composition.refresh_worker(ctx)
+
+          stale_rows = ctx.store.stale(prefix: prefix, zone: zone)
+          refreshed = []
+          failed = []
+          skipped = []
+
+          stale_rows.each do |row|
+            key = row["key"] || row[:key]
+            reason = row["reason"] || row[:reason]
+            if reason.to_s.match?(/ttl exceeded|never refreshed/)
+              begin
+                worker.run(key)
+                refreshed << key
+              rescue Textus::Error => e
+                failed << { "key" => key, "error" => e.message }
+              end
+            else
+              skipped << { "key" => key, "reason" => reason }
+            end
+          end
+
+          {
+            "protocol" => Textus::PROTOCOL,
+            "ok" => failed.empty?,
+            "refreshed" => refreshed,
+            "failed" => failed,
+            "skipped" => skipped,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/refresh/orchestrator.rb

@@ -0,0 +1,69 @@
+module Textus
+  module Application
+    module Refresh
+      class Orchestrator
+        def initialize(worker:, bus:, store_root:, store: nil, role: "human", detached_spawner: nil)
+          @worker = worker
+          @bus = bus
+          @store_root = store_root
+          @store = store
+          @role = role
+          @detached_spawner = detached_spawner || default_spawner
+        end
+
+        def execute(action, key:)
+          case action
+          when Textus::Domain::Action::Return       then Textus::Domain::Outcome::Skipped.new
+          when Textus::Domain::Action::RefreshSync  then run_sync(key)
+          when Textus::Domain::Action::RefreshTimed then run_timed(action.budget_ms, key)
+          else raise ArgumentError.new("unknown action: #{action.inspect}")
+          end
+        end
+
+        private
+
+        def run_sync(key)
+          envelope = @worker.run(key)
+          Textus::Domain::Outcome::Refreshed.new(envelope: envelope)
+        rescue Textus::Error => e
+          Textus::Domain::Outcome::Failed.new(error: e)
+        end
+
+        def run_timed(budget_ms, key)
+          unless Textus::Infra::Refresh::Detached.supported?
+            return Textus::Domain::Outcome::Failed.new(
+              error: Textus::UsageError.new("timed_sync requires fork (Unix only)"),
+            )
+          end
+
+          result = nil
+          thread = Thread.new do
+            result = @worker.run(key)
+          rescue Textus::Error => e
+            result = e
+          end
+
+          thread.join(budget_ms / 1000.0)
+
+          if thread.alive?
+            thread.kill
+            store_view = @store ? Textus::Application::Context.new(store: @store, role: @role) : nil
+            payload = { key: key, started_at: Time.now.utc.iso8601, budget_ms: budget_ms }
+            payload[:store] = store_view if store_view
+            @bus.publish(:refresh_detached, **payload)
+            @detached_spawner.call(store_root: @store_root, key: key)
+            Textus::Domain::Outcome::Detached.new
+          elsif result.is_a?(Textus::Error)
+            Textus::Domain::Outcome::Failed.new(error: result)
+          else
+            Textus::Domain::Outcome::Refreshed.new(envelope: result)
+          end
+        end
+
+        def default_spawner
+          Textus::Infra::Refresh::Detached.method(:spawn)
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/refresh/worker.rb

@@ -0,0 +1,79 @@
+require "timeout"
+
+module Textus
+  module Application
+    module Refresh
+      class Worker
+        FETCH_TIMEOUT_SECONDS = 30
+
+        def initialize(ctx:, bus:)
+          @ctx = ctx
+          @bus = bus
+        end
+
+        def run(key)
+          mentry, path, = @ctx.store.manifest.resolve(key)
+          raise UsageError.new("no intake declared for '#{key}'") unless mentry.intake_handler
+
+          before_etag = File.exist?(path) ? Etag.for_file(path) : nil
+          result = fetch_with_bus(key, mentry)
+          persist_and_notify(key, mentry, result, before_etag)
+        end
+
+        private
+
+        def read_view
+          Application::Context.new(store: @ctx.store, role: @ctx.role)
+        end
+
+        def fetch_with_bus(key, mentry)
+          callable = @ctx.store.registry.rpc_callable(:intake, mentry.intake_handler)
+          @bus.publish(:refresh_began, store: read_view, key: key, mode: :sync,
+                                       correlation_id: @ctx.correlation_id)
+          call_intake(key, mentry, callable)
+        end
+
+        def call_intake(key, mentry, callable)
+          Timeout.timeout(FETCH_TIMEOUT_SECONDS) do
+            callable.call(store: @ctx, config: mentry.intake_config, args: {})
+          end
+        rescue Timeout::Error
+          @bus.publish(:refresh_failed, store: read_view, key: key, error_class: "Timeout::Error",
+                                        error_message: "intake '#{mentry.intake_handler}' exceeded #{FETCH_TIMEOUT_SECONDS}s",
+                                        correlation_id: @ctx.correlation_id)
+          raise UsageError.new("intake '#{mentry.intake_handler}' exceeded #{FETCH_TIMEOUT_SECONDS}s timeout")
+        rescue Textus::Error => e
+          @bus.publish(:refresh_failed, store: read_view, key: key, error_class: e.class.name,
+                                        error_message: e.message, correlation_id: @ctx.correlation_id)
+          raise
+        rescue StandardError => e
+          @bus.publish(:refresh_failed, store: read_view, key: key, error_class: e.class.name,
+                                        error_message: e.message, correlation_id: @ctx.correlation_id)
+          raise UsageError.new("intake '#{mentry.intake_handler}' raised: #{e.class}: #{e.message}")
+        end
+
+        def persist_and_notify(key, mentry, result, before_etag)
+          normalized = Textus::Refresh.normalize_action_result(result, format: mentry.format)
+          envelope = @ctx.store.put(
+            key,
+            meta: normalized[:meta], body: normalized[:body], content: normalized[:content],
+            as: @ctx.role, suppress_events: true
+          )
+          change = detect_change(before_etag, envelope)
+          unless change == :unchanged
+            @bus.publish(:refreshed, store: read_view, key: key, envelope: envelope, change: change,
+                                     correlation_id: @ctx.correlation_id)
+          end
+          envelope
+        end
+
+        def detect_change(before_etag, envelope)
+          if before_etag.nil? then :created
+          elsif envelope["etag"] == before_etag then :unchanged
+          else :updated
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/writes/accept.rb

@@ -0,0 +1,44 @@
+module Textus
+  module Application
+    module Writes
+      class Accept
+        def initialize(ctx:, bus:)
+          @ctx = ctx
+          @bus = bus
+        end
+
+        def call(pending_key)
+          raise ProposalError.new("only human role can accept proposals; got '#{@ctx.role}'") unless @ctx.role == "human"
+
+          env = @ctx.store.get(pending_key)
+          proposal = env["_meta"]["proposal"] or raise ProposalError.new("entry has no proposal block: #{pending_key}")
+          target = proposal["target_key"] or raise ProposalError.new("proposal missing target_key")
+          action = proposal["action"] || "put"
+
+          case action
+          when "put"
+            # Nested proposal "frontmatter" — the meta to write to the accepted
+            # target. Not related to the removed intake-handler legacy bridge.
+            target_meta = env["_meta"]["frontmatter"] || {}
+            target_body = env["body"]
+            Composition.writes_put(@ctx).call(target, meta: target_meta, body: target_body)
+          when "delete"
+            Composition.writes_delete(@ctx).call(target)
+          else
+            raise ProposalError.new("unknown action: #{action}")
+          end
+
+          Composition.writes_delete(@ctx).call(pending_key)
+
+          @bus.publish(:accepted,
+                       store: @ctx.with_role(@ctx.role),
+                       key: pending_key,
+                       target_key: target,
+                       correlation_id: @ctx.correlation_id)
+
+          { "protocol" => PROTOCOL, "accepted" => pending_key, "target_key" => target, "action" => action }
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/writes/build.rb

@@ -0,0 +1,116 @@
+require "fileutils"
+
+module Textus
+  module Application
+    module Writes
+      # Materializes generator-zone entries (template + projection) onto disk
+      # and copies the result to any configured `publish_to` / `publish_each`
+      # targets. Fires `:built` and `:published` events on the bus, tagged with
+      # the request's correlation_id for traceability.
+      class Build
+        def initialize(ctx:, bus:)
+          @ctx = ctx
+          @bus = bus
+        end
+
+        def call(prefix: nil)
+          built = []
+          manifest.entries.each do |mentry|
+            next unless mentry.in_generator_zone?
+            next unless mentry.projection || mentry.template
+            next if prefix && !mentry.key.start_with?(prefix)
+
+            built << materialize(mentry)
+          end
+          published_leaves = publish_leaves(prefix: prefix)
+          { "protocol" => Textus::PROTOCOL, "built" => built, "published_leaves" => published_leaves }
+        end
+
+        private
+
+        def store = @ctx.store
+        def manifest = store.manifest
+        def root = store.root
+
+        def publish_leaves(prefix: nil)
+          repo_root = File.dirname(root)
+          out = []
+          manifest.entries.each do |mentry|
+            next unless mentry.nested && mentry.publish_each
+            next if prefix && !mentry.key.start_with?(prefix) && !prefix.start_with?("#{mentry.key}.")
+
+            manifest.enumerate(prefix: mentry.key).each do |row|
+              next unless row[:manifest_entry].equal?(mentry)
+              next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
+
+              out << publish_leaf(mentry, row, repo_root)
+            end
+          end
+          out
+        end
+
+        def publish_leaf(mentry, row, repo_root)
+          target_rel = mentry.publish_target_for(row[:key])
+          target_abs = File.expand_path(File.join(repo_root, target_rel))
+          unless target_abs.start_with?(File.expand_path(repo_root) + File::SEPARATOR)
+            raise PublishError.new(
+              "entry '#{mentry.key}': publish_each target '#{target_rel}' for key '#{row[:key]}' escapes repo root",
+            )
+          end
+
+          Textus::Infra::Publisher.publish(source: row[:path], target: target_abs, store_root: root)
+          publish_event(:published,
+                        key: row[:key],
+                        envelope: store.get(row[:key]),
+                        source: row[:path],
+                        target: target_abs)
+          { "key" => row[:key], "source" => row[:path], "target" => target_abs }
+        end
+
+        def materialize(mentry)
+          target_path = Builder::Pipeline.run(
+            store: store,
+            mentry: mentry,
+            template_loader: ->(name) { read_template(name) },
+          )
+          publish_and_fire(mentry, target_path)
+          { "key" => mentry.key, "path" => target_path, "published_to" => mentry.publish_to }
+        end
+
+        def read_template(name)
+          tpl_path = File.join(root, "templates", name)
+          raise TemplateError.new("template not found: #{tpl_path}", template_name: name) unless File.exist?(tpl_path)
+
+          File.read(tpl_path)
+        end
+
+        def publish_and_fire(mentry, target_path)
+          envelope = store.get(mentry.key)
+          repo_root = File.dirname(root)
+
+          mentry.publish_to.each do |rel|
+            target_abs = File.join(repo_root, rel)
+            Textus::Infra::Publisher.publish(source: target_path, target: target_abs, store_root: root)
+            publish_event(:published,
+                          key: mentry.key,
+                          envelope: envelope,
+                          source: target_path,
+                          target: target_abs)
+          end
+
+          publish_event(:built,
+                        key: mentry.key,
+                        envelope: envelope,
+                        sources: Array(mentry.projection&.fetch("select", nil)).compact)
+        end
+
+        def publish_event(event, **payload)
+          # `with_role` returns a Context that preserves the original
+          # correlation_id, so hooks reading `store.correlation_id` see the
+          # same value as the event's top-level correlation_id key.
+          @bus.publish(event, store: @ctx.with_role(@ctx.role), correlation_id: @ctx.correlation_id, **payload)
+        end
+      end
+    end
+  end
+end