textus 0.22.0 → 0.26.0

data/lib/textus/application/{writes/envelope_io.rb → envelope/writer.rb}

@@ -2,55 +2,37 @@ require "fileutils"
 
 module Textus
   module Application
-    module Writes
-      # Owns the write pipeline (validate, serialize, etag-check, write, audit)
-      # extracted from Store::Writer. Talks to ports (FileStore, Schemas,
-      # AuditLog, Manifest) instead of File/FileUtils and Store directly.
+    module Envelope
+      # Owns the write pipeline (validate, serialize, etag-check, write, audit).
+      # Talks to ports (FileStore, Schemas, AuditLog, Manifest) and an
+      # Reader for the existing-uid lookup.
+      #
+      # Invariant: every public method's final action is @audit_log.append(...).
       #
       # No permission check, no event firing — those belong to the caller
-      # (Application::Writes::Put / ::Delete / ::Mv).
-      class EnvelopeIO
+      # (Application::Write::Put / ::Delete / ::Mv).
+      class Writer
         Payload = Data.define(:meta, :body, :content)
 
-        def initialize(file_store:, manifest:, schemas:, audit_log:, ctx:)
+        def initialize(file_store:, manifest:, schemas:, audit_log:, ctx:, reader:)
           @file_store = file_store
           @manifest   = manifest
           @schemas    = schemas
           @audit_log  = audit_log
           @ctx        = ctx
+          @reader     = reader
         end
 
-        def exists?(path) = @file_store.exists?(path)
-
-        # Reads an envelope by key, returning nil when absent. Used by Mv
-        # to inspect pre-move state (UID presence, content surfacing) so
-        # the move pipeline can consolidate I/O in one place.
-        def read_envelope(key)
-          res = @manifest.resolver.resolve(key)
-          path = res.path
-          return nil unless @file_store.exists?(path)
-
-          mentry = res.entry
-          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 write(key, mentry:, payload:, if_etag: nil)
+        def put(key, mentry:, payload:, if_etag: nil)
           path = @manifest.resolver.resolve(key).path
 
           meta = payload.meta || {}
-          strategy = Entry.for_format(mentry.format)
 
-          existing_uid = existing_uid_for(mentry, path)
+          existing_uid = @reader.existing_uid(key)
           meta, content = ensure_uid(mentry.format, meta, payload.content, existing_uid)
 
           bytes, eff_meta, eff_body, eff_content = serialize_for_put(
-            mentry: mentry, path: path, strategy: strategy,
+            mentry: mentry, path: path,
             meta: meta, body: payload.body, content: content
           )
 
@@ -69,19 +51,22 @@ module Textus
 
           @file_store.write(path, bytes)
           etag_after = Etag.for_bytes(bytes)
+          envelope = Textus::Envelope.build(
+            key: key, mentry: mentry, path: path,
+            meta: eff_meta, body: eff_body, etag: etag_after, content: eff_content
+          )
           @audit_log.append(
             role: @ctx.role, verb: "put", key: key,
             etag_before: etag_before, etag_after: etag_after,
             extras: @ctx.correlation_id ? { "correlation_id" => @ctx.correlation_id } : nil
           )
-          Envelope.build(
-            key: key, mentry: mentry, path: path,
-            meta: eff_meta, body: eff_body, etag: etag_after, content: eff_content
-          )
+          envelope
         end
 
-        def delete(key, mentry:, if_etag: nil)
-          _ = mentry
+        def delete(key, mentry: nil, if_etag: nil) # rubocop:disable Lint/UnusedMethodArgument
+          # `mentry:` is accepted for symmetry with `put` / `move` and to
+          # leave room for future format-specific delete hooks; no field
+          # on it is needed today.
           path = @manifest.resolver.resolve(key).path
           raise UnknownKey.new(key, suggestions: @manifest.resolver.suggestions_for(key)) unless @file_store.exists?(path)
 
@@ -112,7 +97,7 @@ module Textus
 
           raw = @file_store.read(to_path)
           parsed = Entry.for_format(new_mentry.format).parse(raw, path: to_path)
-          envelope = Envelope.build(
+          envelope = Textus::Envelope.build(
             key: to_key, mentry: new_mentry, path: to_path,
             meta: parsed["_meta"], body: parsed["body"],
             etag: etag_after, content: parsed["content"]
@@ -136,16 +121,6 @@ module Textus
 
         private
 
-        def existing_uid_for(mentry, path)
-          return nil unless @file_store.exists?(path)
-
-          raw = @file_store.read(path)
-          parsed = Entry.for_format(mentry.format).parse(raw, path: path)
-          Envelope.extract_uid(parsed["_meta"])
-        rescue StandardError
-          nil
-        end
-
         def ensure_uid(format, meta, content, existing_uid)
           Textus::Entry.for_format(format).inject_uid(meta, content, existing_uid)
         end
@@ -154,8 +129,7 @@ module Textus
           Textus::Entry.for_format(format).enforce_name_match!(path, meta)
         end
 
-        def serialize_for_put(mentry:, path:, strategy:, meta:, body:, content:)
-          _ = strategy
+        def serialize_for_put(mentry:, path:, meta:, body:, content:)
           Textus::Entry.for_format(mentry.format).serialize_for_put(
             meta: meta, body: body, content: content, path: path,
           )

data/lib/textus/application/maintenance/key_delete_prefix.rb

@@ -0,0 +1,44 @@
+module Textus
+  module Application
+    module Maintenance
+      # Bulk-delete every leaf key under `prefix`.
+      module KeyDeletePrefix
+        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
+            @session = session
+          end
+
+          def call(prefix:, dry_run: false)
+            raise UsageError.new("prefix required") if prefix.nil? || prefix.empty?
+
+            leaves = Read::List::Impl.new(caps: @caps)
+                                     .call(prefix: prefix)
+                                     .map { |r| r.is_a?(Hash) ? (r["key"] || r[:key]) : r }
+
+            warnings = leaves.empty? ? ["no keys under #{prefix}"] : []
+            steps = leaves.map { |k| { "op" => "delete", "key" => k } }
+
+            plan = Plan.new(steps: steps, warnings: warnings)
+            return plan if dry_run
+
+            steps.each do |s|
+              Textus::Application::Write::Delete.call(
+                s["key"],
+                session: @session, ctx: @ctx, caps: @session.write_caps,
+              )
+            end
+            plan
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:key_delete_prefix, Textus::Application::Maintenance::KeyDeletePrefix, caps: :write)

data/lib/textus/application/maintenance/key_mv_prefix.rb

@@ -0,0 +1,57 @@
+module Textus
+  module Application
+    module Maintenance
+      # Bulk-rename every leaf key under `from_prefix` to `to_prefix`.
+      # Calls Write::Mv directly for each entry — emits one audit row per file moved.
+      module KeyMvPrefix
+        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
+            @session = session
+          end
+
+          def call(from_prefix:, to_prefix:, dry_run: false)
+            raise UsageError.new("from_prefix and to_prefix required") if from_prefix.nil? || to_prefix.nil?
+
+            leaves = list_leaves_under(from_prefix)
+            warnings = []
+            warnings << "no keys under #{from_prefix}" if leaves.empty?
+
+            steps = leaves.map do |old_key|
+              tail = old_key.delete_prefix("#{from_prefix}.")
+              new_key = "#{to_prefix}.#{tail}"
+              { "op" => "mv", "from" => old_key, "to" => new_key }
+            end
+
+            plan = Plan.new(steps: steps, warnings: warnings)
+            return plan if dry_run
+
+            steps.each do |s|
+              Textus::Application::Write::Mv.call(
+                s["from"], s["to"],
+                session: @session, ctx: @ctx, caps: @session.write_caps,
+                dry_run: false
+              )
+            end
+            plan
+          end
+
+          private
+
+          def list_leaves_under(prefix)
+            Read::List::Impl.new(caps: @caps)
+                            .call(prefix: prefix)
+                            .map { |row| row.is_a?(Hash) ? (row["key"] || row[:key]) : row }
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:key_mv_prefix, Textus::Application::Maintenance::KeyMvPrefix, caps: :write)

data/lib/textus/application/maintenance/migrate.rb

@@ -0,0 +1,59 @@
+require "yaml"
+
+module Textus
+  module Application
+    module Maintenance
+      # Loads a YAML migration plan and dispatches each op to the
+      # appropriate Maintenance use case. Concatenates resulting Plans.
+      module Migrate
+        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
+            @session = session
+          end
+
+          def call(plan_yaml:, dry_run: false)
+            raw = YAML.safe_load(plan_yaml, permitted_classes: [Symbol], aliases: false)
+            raise UsageError.new("migration plan must be a YAML mapping") unless raw.is_a?(Hash)
+
+            ops = Array(raw["operations"])
+            all_steps = []
+            warnings = []
+
+            ops.each do |op_hash|
+              op_name = op_hash["op"]
+              sub_plan = invoke_op(op_name, op_hash, dry_run: dry_run)
+              all_steps.concat(sub_plan.steps)
+              warnings.concat(sub_plan.warnings)
+            end
+
+            Plan.new(steps: all_steps, warnings: warnings)
+          end
+
+          private
+
+          def invoke_op(op_name, op_hash, dry_run:)
+            kwargs = op_hash.except("op").transform_keys(&:to_sym).merge(dry_run: dry_run)
+            case op_name
+            when "key_mv_prefix"
+              KeyMvPrefix.call(session: @session, ctx: @ctx, caps: @caps, **kwargs)
+            when "key_delete_prefix"
+              KeyDeletePrefix.call(session: @session, ctx: @ctx, caps: @caps, **kwargs)
+            when "zone_mv"
+              ZoneMv.call(session: @session, ctx: @ctx, caps: @caps, **kwargs)
+            else
+              raise UsageError.new("unknown op: #{op_name}")
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:migrate, Textus::Application::Maintenance::Migrate, caps: :write)

data/lib/textus/application/maintenance/rule_lint.rb

@@ -0,0 +1,65 @@
+require "yaml"
+
+module Textus
+  module Application
+    module Maintenance
+      # Compare the live manifest's `rules:` block against a candidate
+      # YAML string. Returns a Plan describing rule additions/removals/
+      # changes. Does NOT write anything.
+      module RuleLint
+        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
+            @root = caps.root
+          end
+
+          def call(candidate_yaml:)
+            live_rules      = current_rules
+            candidate_rules = parse_candidate(candidate_yaml)
+
+            live_by_match      = live_rules.to_h { |r| [r["match"], r] }
+            candidate_by_match = candidate_rules.to_h { |r| [r["match"], r] }
+
+            steps = (candidate_by_match.keys - live_by_match.keys).map do |m|
+              { "op" => "add_rule", "match" => m, "rule" => candidate_by_match[m] }
+            end
+            (live_by_match.keys - candidate_by_match.keys).each do |m|
+              steps << { "op" => "remove_rule", "match" => m }
+            end
+            (live_by_match.keys & candidate_by_match.keys).each do |m|
+              next if live_by_match[m] == candidate_by_match[m]
+
+              steps << { "op" => "change_rule", "match" => m,
+                         "from" => live_by_match[m], "to" => candidate_by_match[m] }
+            end
+
+            Plan.new(steps: steps, warnings: [])
+          end
+
+          private
+
+          def current_rules
+            raw = YAML.safe_load_file(File.join(@root, "manifest.yaml"),
+                                      permitted_classes: [Symbol], aliases: false)
+            Array(raw["rules"])
+          end
+
+          def parse_candidate(yaml_text)
+            raw = YAML.safe_load(yaml_text, permitted_classes: [Symbol], aliases: false)
+            raise UsageError.new("candidate is not a YAML mapping") unless raw.is_a?(Hash)
+
+            Array(raw["rules"])
+          rescue Psych::Exception => e
+            raise UsageError.new("candidate YAML parse error: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:rule_lint, Textus::Application::Maintenance::RuleLint, caps: :read)

data/lib/textus/application/maintenance/zone_mv.rb

@@ -0,0 +1,60 @@
+require "yaml"
+
+module Textus
+  module Application
+    module Maintenance
+      # Rename a zone — rewrites the manifest's zones[] entry, rewrites
+      # the `zone:` field on every entry under the old zone, and moves
+      # every file from zones/<old>/ to zones/<new>/.
+      module ZoneMv
+        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
+            @manifest = caps.manifest
+            @root     = caps.root
+          end
+
+          def call(from:, to:, dry_run: false)
+            raise UsageError.new("from and to required") if from.nil? || to.nil? || from.empty? || to.empty?
+            raise UsageError.new("zone '#{from}' not declared") unless @manifest.data.zones.key?(from)
+
+            dest_dir = File.join(@root, "zones", to)
+            raise UsageError.new("destination 'zones/#{to}' already exists") if File.exist?(dest_dir)
+
+            affected_keys = @manifest.data.entries.select { |e| e.zone == from }.map(&:key)
+
+            steps  = [{ "op" => "rename_zone", "from" => from, "to" => to }]
+            steps += affected_keys.map { |k| { "op" => "mv", "from" => k, "to" => "#{to}#{k[from.length..]}" } }
+
+            plan = Plan.new(steps: steps, warnings: [])
+            return plan if dry_run
+
+            rewrite_manifest!(from, to)
+            FileUtils.mv(File.join(@root, "zones", from), dest_dir)
+            plan
+          end
+
+          private
+
+          def rewrite_manifest!(from, to)
+            path = File.join(@root, "manifest.yaml")
+            raw = YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: false)
+            raw["zones"].each { |z| z["name"] = to if z["name"] == from }
+            raw["entries"].each do |e|
+              e["zone"] = to if e["zone"] == from
+              e["key"]  = e["key"].sub(/\A#{Regexp.escape(from)}(\.|\z)/, "#{to}\\1")
+              e["path"] = e["path"].sub(%r{\A#{Regexp.escape(from)}(/|\z)}, "#{to}\\1")
+            end
+            File.write(path, YAML.dump(raw))
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:zone_mv, Textus::Application::Maintenance::ZoneMv, caps: :write)

data/lib/textus/application/maintenance.rb

@@ -0,0 +1,17 @@
+module Textus
+  module Application
+    # Bulk and structural changes to a textus store. Each use case returns
+    # a Plan when called with dry_run: true, and applies the plan when
+    # called with dry_run: false.
+    module Maintenance
+      # A Plan is a JSON-shaped preview. Steps are op-tagged hashes the
+      # use case knows how to apply. Warnings are strings surfaced to
+      # the operator (skipped keys, ambiguities).
+      Plan = Data.define(:steps, :warnings) do
+        def to_h
+          { "steps" => steps, "warnings" => warnings }
+        end
+      end
+    end
+  end
+end

data/lib/textus/application/projection.rb

@@ -11,14 +11,14 @@ module Textus
       #   semantics: pure read (`ops.get`) for materialization paths;
       #   `ops.get_or_refresh` if you want refresh-on-stale.
       # `lister` — a callable `->(prefix:) { [ { "key" => ... }, ... ] }`.
-      # `transform_resolver` — a callable `->(name) { callable_or_raise }`.
-      # `transform_context` — `Application::Context` handed to the transform reducer.
-      def initialize(reader:, spec:, lister:, transform_resolver:, transform_context:)
-        @reader             = reader
-        @spec               = spec || {}
-        @lister             = lister
-        @transform_resolver = transform_resolver
-        @transform_context  = transform_context
+      # `rpc` — a `Hooks::RpcRegistry` used to dispatch `transform_rows` callables.
+      # `transform_context` — capability object handed to transform reducers as `caps:`.
+      def initialize(reader:, spec:, lister:, rpc:, transform_context:)
+        @reader            = reader
+        @spec              = spec || {}
+        @lister            = lister
+        @rpc               = rpc
+        @transform_context = transform_context
         @limit = (@spec["limit"] || MAX_LIMIT).to_i
         raise InvalidProjection.new("limit #{@limit} exceeds max #{MAX_LIMIT}") if @limit > MAX_LIMIT
       end
@@ -49,9 +49,11 @@ module Textus
 
       def apply_reducer(rows)
         name = @spec["transform"] or return rows
-        callable = @transform_resolver.call(name)
         Timeout.timeout(REDUCER_TIMEOUT_SECONDS) do
-          callable.call(store: @transform_context, rows: rows, config: @spec["transform_config"] || {})
+          @rpc.invoke(:transform_rows, name,
+                      caps: @transform_context,
+                      rows: rows,
+                      config: @spec["transform_config"] || {})
         end
       rescue Timeout::Error
         raise UsageError.new("transform_rows '#{name}' exceeded #{REDUCER_TIMEOUT_SECONDS}s timeout")

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

@@ -0,0 +1,106 @@
+require "json"
+require "time"
+
+module Textus
+  module Application
+    module Read
+      # Queries .textus/audit.log. Filters: key, zone, role, verb, since,
+      # correlation_id, limit. Reads the log file as JSON-Lines (legacy TSV
+      # rows produce nil and are skipped).
+      module Audit
+        def self.call(*, session:, ctx:, caps:, **) # rubocop:disable Lint/UnusedMethodArgument
+          Impl.new(caps: caps).call(*, **)
+        end
+
+        def self.parse_since(str, now: Time.now.utc)
+          Impl.parse_since(str, now: now)
+        end
+
+        class Impl
+          def initialize(caps:)
+            @manifest  = caps.manifest
+            @root      = caps.root
+            @log_path  = File.join(caps.root, "audit.log")
+            @audit_log = caps.audit_log
+          end
+
+          # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+          def call(key: nil, zone: nil, role: nil, verb: nil, since: nil, seq_since: nil, correlation_id: nil, limit: nil)
+            check_cursor_expiry!(seq_since)
+
+            files = all_log_files
+            return [] if files.empty?
+
+            rows = []
+            files.each do |file|
+              File.foreach(file) do |line|
+                parsed = parse_row(line.chomp)
+                next unless parsed
+                next if key && parsed["key"] != key
+                next if role && parsed["role"] != role
+                next if verb && parsed["verb"] != verb
+                next if zone && !key_in_zone?(parsed["key"], zone)
+                next if since && (parsed["ts"].nil? || Time.parse(parsed["ts"]) < since)
+                next if seq_since && (parsed["seq"].nil? || parsed["seq"] <= seq_since)
+                next if correlation_id && parsed.dig("extras", "correlation_id") != correlation_id
+
+                rows << parsed
+                break if limit && rows.length >= limit
+              end
+              break if limit && rows.length >= limit
+            end
+            rows
+          end
+          # rubocop:enable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+          # Accepts ISO8601 ("2026-01-15", "2026-01-15T10:00:00Z") or a relative
+          # offset matching /\A(\d+)([smhd])\z/. Returns nil for unparseable input.
+          def self.parse_since(str, now: Time.now.utc)
+            return nil if str.nil? || str.empty?
+            return Time.parse(str) if str =~ /\A\d{4}-\d{2}-\d{2}/
+
+            m = str.match(/\A(\d+)([smhd])\z/) or return nil
+            mult = { "s" => 1, "m" => 60, "h" => 3600, "d" => 86_400 }[m[2]]
+            now - (m[1].to_i * mult)
+          end
+
+          private
+
+          def check_cursor_expiry!(seq_since)
+            return unless seq_since
+
+            log = @audit_log || Textus::Infra::AuditLog.new(@root)
+            min = log.min_available_seq
+            raise Textus::CursorExpired.new(requested: seq_since, min_available: min) if min && seq_since < min - 1
+          end
+
+          def all_log_files
+            rotated = Dir.glob(File.join(@root, "audit.log.*"))
+                         .reject { |p| p.end_with?(".meta.json") }
+                         .sort_by { |p| -p.scan(/\d+$/).first.to_i } # .5 .4 .3 .2 .1 → oldest first
+            active = File.exist?(@log_path) ? [@log_path] : []
+            rotated + active
+          end
+
+          def parse_row(line)
+            return nil if line.empty?
+            return nil unless line.start_with?("{")
+
+            JSON.parse(line)
+          rescue JSON::ParserError
+            nil
+          end
+
+          def key_in_zone?(key, zone)
+            mentry = @manifest.resolver.resolve(key).entry
+            mentry && mentry.zone == zone
+          rescue Textus::Error
+            false
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:audit, Textus::Application::Read::Audit, caps: :read)

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

@@ -0,0 +1,91 @@
+require "open3"
+
+module Textus
+  module Application
+    module Read
+      # For one key, joins every audit-log row with the git commit (sha,
+      # author, date, subject) that introduced the file state at that audit
+      # row. Falls back to `git => nil` when not in a git repo or when the
+      # file is untracked.
+      module Blame
+        def self.call(*, session:, ctx:, caps:, **) # rubocop:disable Lint/UnusedMethodArgument
+          Impl.new(caps: caps).call(*, **)
+        end
+
+        class Impl
+          def initialize(caps:)
+            @caps = caps
+            @manifest = caps.manifest
+            @root     = caps.root
+          end
+
+          def call(key:, limit: nil)
+            audit_rows = Textus::Application::Read::Audit::Impl.new(caps: @caps).call(key: key, limit: limit)
+            path = resolve_path(key)
+            return audit_rows.map { |r| r.merge("git" => nil) } unless git_tracked?(path)
+
+            audit_rows.map { |r| r.merge("git" => git_commit_at(path, timestamp: r["ts"])) }
+          end
+
+          private
+
+          def resolve_path(key)
+            res = @manifest.resolver.resolve(key)
+            mentry = res.entry
+            path = res.path
+            # Nested entries resolve to a file under the entry path; leaf entries
+            # already have a fully-resolved path. Either way `path` is what git
+            # needs to know about.
+            path || Textus::Key::Path.resolve(@manifest.data, mentry)
+          rescue Textus::Error
+            nil
+          end
+
+          def git_tracked?(path)
+            return false if path.nil?
+            return false unless File.exist?(path)
+            return false unless git_repo?
+
+            _out, _err, status = Open3.capture3(
+              "git", "ls-files", "--error-unmatch", path,
+              chdir: @root
+            )
+            status.success?
+          rescue Errno::ENOENT
+            false
+          end
+
+          def git_repo?
+            # Walk up from store root to find a .git directory.
+            dir = @root
+            loop do
+              return true if File.directory?(File.join(dir, ".git"))
+
+              parent = File.dirname(dir)
+              return false if parent == dir
+
+              dir = parent
+            end
+          end
+
+          def git_commit_at(path, timestamp:)
+            args = ["git", "log", "-1"]
+            args << "--before=#{timestamp}" if timestamp
+            args += ["--format=%H%x09%an%x09%aI%x09%s", "--", path]
+            out, _err, status = Open3.capture3(*args, chdir: @root)
+            return nil unless status.success?
+
+            sha, author, date, subject = out.strip.split("\t", 4)
+            return nil if sha.nil? || sha.empty?
+
+            { "sha" => sha, "author" => author, "date" => date, "subject" => subject }
+          rescue Errno::ENOENT
+            nil
+          end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:blame, Textus::Application::Read::Blame, caps: :read)