textus 0.8.0 → 0.9.2

data/lib/textus/application/context.rb

@@ -0,0 +1,68 @@
+require "securerandom"
+
+module Textus
+  module Application
+    class Context
+      attr_reader :store, :role, :correlation_id
+
+      def initialize(store:, role:, correlation_id: nil, clock: Time, dry_run: false)
+        @store          = store
+        @role           = role.to_s
+        @correlation_id = correlation_id || SecureRandom.uuid
+        @clock          = clock
+        @dry_run        = dry_run
+        @now            = nil
+      end
+
+      def now
+        @now ||= @clock.now
+      end
+
+      def dry_run?
+        @dry_run
+      end
+
+      def can_write?(zone)
+        store.manifest.permission_for(zone.to_s).allows_write?(role)
+      end
+
+      def can_read?(zone)
+        store.manifest.permission_for(zone.to_s).allows_read?(role)
+      end
+
+      def with_role(new_role)
+        self.class.new(
+          store: @store,
+          role: new_role,
+          correlation_id: @correlation_id,
+          clock: @clock,
+          dry_run: @dry_run,
+        )
+      end
+
+      # Backward-compat for intake handlers receiving a Context (was Store::View)
+      # that call store.put/get/delete on it. Slated for removal in 0.10.0.
+      def put(key, **opts)
+        opts[:as] ||= role
+        store.put(key, **opts)
+      end
+
+      def delete(key, **opts)
+        opts[:as] ||= role
+        store.delete(key, **opts)
+      end
+
+      def get(key, **)
+        store.get(key, **)
+      end
+
+      def list(*, **)
+        store.list(*, **)
+      end
+
+      def where(*, **)
+        store.where(*, **)
+      end
+    end
+  end
+end

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,68 @@
+module Textus
+  module Application
+    module Refresh
+      class Orchestrator
+        def initialize(worker:, bus:, store_root:, store: nil, detached_spawner: nil)
+          @worker = worker
+          @bus = bus
+          @store_root = store_root
+          @store = store
+          @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::Store::View.new(@store) : 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
+          Store::View.new(@ctx.store)
+        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,43 @@
+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"
+            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)
+
+          store_view = Store::View.new(@ctx.store)
+          @bus.publish(:accepted,
+                       store: store_view,
+                       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,24 @@
+module Textus
+  module Application
+    module Writes
+      class Build
+        def initialize(ctx:, bus:)
+          @ctx = ctx
+          @bus = bus
+        end
+
+        def call(prefix: nil)
+          # Delegate to legacy Builder for the materialization/projection logic.
+          # Builder fires its own events through @store.fire_event; we do NOT
+          # double-fire from here. Full extraction of Builder internals into
+          # Writes::Build is deferred to 0.10.0.
+          #
+          # TODO(0.10.0): propagate @ctx.correlation_id through :built/:published
+          # events once Builder internals are extracted into this use case.
+          legacy = Textus::Builder.new(@ctx.store)
+          legacy.build(prefix: prefix)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+module Textus
+  module Application
+    module Writes
+      class Delete
+        def initialize(ctx:, bus:)
+          @ctx = ctx
+          @bus = bus
+        end
+
+        def call(key, if_etag: nil, suppress_events: false)
+          @ctx.store.manifest.validate_key!(key)
+          mentry, = @ctx.store.manifest.resolve(key)
+
+          unless @ctx.can_write?(mentry.zone)
+            raise WriteForbidden.new(key, mentry.zone,
+                                     writers: @ctx.store.manifest.zone_writers(mentry.zone))
+          end
+
+          @ctx.store.writer.delete_envelope_from_disk(
+            key, if_etag: if_etag, as: @ctx.role,
+                 correlation_id: @ctx.correlation_id
+          )
+
+          unless suppress_events
+            store_view = Store::View.new(@ctx.store)
+            @bus.publish(:deleted,
+                         store: store_view,
+                         key: key,
+                         correlation_id: @ctx.correlation_id)
+          end
+
+          { "protocol" => Textus::PROTOCOL, "ok" => true, "key" => key, "deleted" => true }
+        end
+      end
+    end
+  end
+end