textus 0.54.1 → 0.55.1

data/lib/textus/action/deps.rb

@@ -3,31 +3,16 @@
 module Textus
   module Action
     class Deps < Base
-      extend Textus::Contract::DSL
-
       verb :deps
       summary "List the keys a derived entry depends on (its projection/external sources)."
       surfaces :cli, :mcp
       arg :key, String, required: true, positional: true,
                         description: "dotted key of the derived entry whose source keys you want"
 
-      def initialize(key:)
-        super()
-        @key = key
-      end
-
-      def call(container:, **)
-        entry = container.manifest.data.entries.find { |e| e.key == @key }
+      def self.call(container:, key:, **)
+        entry = container.manifest.data.entries.find { |e| e.key == key }
         deps = entry&.external? ? Array(entry.source&.sources).compact : []
-        { "key" => @key, "deps" => deps.uniq }
-      end
-
-      def self.new(*args, **kwargs)
-        return super(**kwargs) unless args.any?
-
-        positional = instance_method(:initialize).parameters.slice(:keyreq, :key).map(&:last)
-        mapped = positional.zip(args).to_h
-        super(**mapped.merge(kwargs))
+        Success({ "key" => key, "deps" => deps.uniq })
       end
     end
   end

data/lib/textus/action/doctor.rb

@@ -3,21 +3,14 @@
 module Textus
   module Action
     class Doctor < Base
-      extend Textus::Contract::DSL
-
       verb :doctor
       summary "Run health checks on the textus store and report any issues."
       surfaces :cli
       cli "doctor"
       arg :checks, Array, required: false, description: "subset of check names to run (default: all)"
 
-      def initialize(checks: nil)
-        super()
-        @checks = checks
-      end
-
-      def call(container:, call:, **)
-        Textus::Doctor.build(container: container, checks: @checks, role: call.role)
+      def self.call(container:, call:, checks: nil, **)
+        Success(Textus::Doctor.build(container: container, checks: checks, role: call.role))
       end
     end
   end

data/lib/textus/action/drain.rb

@@ -3,8 +3,6 @@
 module Textus
   module Action
     class Drain < Base
-      extend Textus::Contract::DSL
-
       verb :drain
       summary "Seed materialize + sweep jobs then drain the queue to empty. " \
               "Identical to one Watcher tick. Use when no watcher is running."
@@ -12,27 +10,21 @@ module Textus
       arg :prefix, String, description: "restrict to keys under this dotted prefix"
       arg :lane,   String, description: "restrict to entries in this lane"
 
-      def initialize(prefix: nil, lane: nil)
-        super()
-        @prefix = prefix
-        @lane   = lane
-      end
-
-      def call(container:, call:)
-        queue = Textus::Ports::JobStore.new(root: container.root)
-        Textus::Jobs::Planner.seed(
+      def self.call(container:, call:, prefix: nil, lane: nil) # rubocop:disable Lint/UnusedMethodArgument
+        queue = Textus::Store::Jobs::Queue.new(store: container.job_store)
+        Textus::Store::Jobs::Planner.seed(
           container: container,
           queue: queue,
           role: call.role,
         )
-        queue.reclaim(now: Textus::Ports::Clock.new.now)
-        summary = Textus::Jobs::Worker.for(container:, queue:).drain
-        {
-          "protocol" => Textus::PROTOCOL,
-          "ok" => summary.failed.zero?,
-          "completed" => summary.completed,
-          "failed" => summary.failed,
-        }
+        queue.reclaim(now: Textus::Port::Clock.new.now)
+        summary = Textus::Store::Jobs::Worker.for(container:, queue:).drain
+        Success({
+                  "protocol" => Textus::PROTOCOL,
+                  "ok" => summary.failed.zero?,
+                  "completed" => summary.completed,
+                  "failed" => summary.failed,
+                })
       end
     end
   end

data/lib/textus/action/enqueue.rb

@@ -2,9 +2,7 @@
 
 module Textus
   module Action
-    class Enqueue < WriteVerb
-      extend Textus::Contract::DSL
-
+    class Enqueue < Base
       verb :enqueue
       summary "Push a registered job type onto the convergence queue, to be run by drain/serve."
       surfaces :cli, :mcp
@@ -14,39 +12,25 @@ module Textus
       arg :args, Hash, default: {},
                        description: "type-specific arguments (e.g. { key: ... } or { scope: ... })"
 
-      def initialize(type:, args: {})
-        super()
-        @type = type
-        @job_args = args
-      end
+      def self.call(container:, call:, type:, args: {})
+        action_class = Textus::Jobs.fetch(type.to_s)
 
-      def args
-        { type: @type, args: @job_args }
-      end
-
-      def call(container:, call:)
-        action_class = begin
-          Textus::Jobs.fetch(@type.to_s)
-        rescue Textus::UsageError
-          raise Textus::UsageError.new("unregistered job type '#{@type}'")
-        end
         if action_class.const_defined?(:REQUIRED_ROLE) && call.role != action_class::REQUIRED_ROLE
-          raise Textus::Error.new(
-            "forbidden",
-            "role '#{call.role}' is not authorized to enqueue this job type (requires '#{action_class::REQUIRED_ROLE}')",
-            details: { "role" => call.role, "required_role" => action_class::REQUIRED_ROLE },
-            exit_code: 77,
-          )
+          return Failure(code: :forbidden,
+                         message: "role '#{call.role}' is not authorized to enqueue this job type",
+                         details: { "role" => call.role, "required_role" => action_class::REQUIRED_ROLE })
         end
 
-        job = Textus::Ports::JobStore::Job.new(
-          type: @type,
-          args: @job_args,
-          enqueued_by: call.role,
+        job = Textus::Store::Jobs::Queue::Job.new(
+          type: type,
+          args: args,
+          role: call.role,
           max_attempts: 3,
         )
-        Textus::Ports::JobStore.new(root: container.root).enqueue(job)
-        { "protocol" => Textus::PROTOCOL, "ok" => true, "id" => job.id }
+        Textus::Store::Jobs::Queue.new(store: container.job_store).enqueue(job)
+        Success({ "protocol" => Textus::PROTOCOL, "ok" => true, "id" => job.id })
+      rescue Textus::UsageError
+        Failure(code: :usage_error, message: "unregistered job type '#{type}'")
       end
     end
   end

data/lib/textus/action/get.rb

@@ -3,8 +3,6 @@
 module Textus
   module Action
     class Get < Base
-      extend Textus::Contract::DSL
-
       verb :get
       summary "Read one entry - a pure on-disk read annotated with a freshness " \
               "verdict; never ingests (quarantine freshness is drain + hook " \
@@ -13,64 +11,22 @@ module Textus
       surfaces :cli, :mcp
       arg :key, String, required: true, positional: true,
                         description: "dotted entry key to read, e.g. 'knowledge.project'"
-      view { |v, _i| v.to_h_for_wire }
+      view(:default) { |v, _i| v&.to_h_for_wire }
 
-      def initialize(key:)
-        super()
-        @key = key
-      end
+      def self.call(container:, call:, key:)
+        envelope = container.compositor.read(key)
+        return Failure(code: :not_found, message: "no entry at #{key}") unless envelope
 
-      def call(container:, call:, file_stat: Textus::Ports::Storage::FileStat.new)
-        @container = container
-        @call = call
-        @manifest = container.manifest
-        @file_store = container.file_store
-        @file_stat = file_stat
-        annotated_envelope(@key)
+        entry = container.manifest.resolver.resolve(key).entry
+        file_stat = Textus::Port::Storage::FileStat.new
+        Success(envelope.with(freshness: freshness_evaluator(container, call, file_stat).verdict(entry)))
       end
 
-      def self.new(*args, **kwargs)
-        return super(**kwargs) unless args.any?
-
-        positional = instance_method(:initialize).parameters.slice(:keyreq, :key).map(&:last)
-        mapped = positional.zip(args).to_h
-        super(**mapped.merge(kwargs))
-      end
-
-      private
-
-      def annotated_envelope(key)
-        envelope = read_raw_envelope(key)
-        return nil if envelope.nil?
-
-        entry = @manifest.resolver.resolve(key).entry
-        envelope.with(freshness: evaluator.verdict(entry))
-      end
-
-      def evaluator
-        @evaluator ||= Textus::Core::Freshness::Evaluator.new(
-          manifest: @manifest,
-          file_stat: @file_stat,
-          clock: @call,
-        )
-      end
-
-      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 = Textus::Format.for(mentry.format).parse(raw, path: path)
-        Textus::Envelope.build(
-          key: key,
-          mentry: mentry,
-          path: path,
-          meta: parsed["_meta"],
-          body: parsed["body"],
-          etag: Textus::Etag.for_bytes(raw),
-          content: parsed["content"],
+      def self.freshness_evaluator(container, call, file_stat)
+        Textus::Core::Freshness::Evaluator.new(
+          manifest: container.manifest,
+          file_stat: file_stat,
+          clock: call,
         )
       end
     end

data/lib/textus/action/ingest.rb

@@ -2,12 +2,11 @@
 
 require "fileutils"
 require "date"
+require "digest"
 
 module Textus
   module Action
     class Ingest < Base
-      extend Textus::Contract::DSL
-
       verb :ingest
       summary "Capture external source material into the raw lane. Write-once, agent-owned."
       surfaces :cli, :mcp
@@ -22,109 +21,174 @@ module Textus
       view { |env| { "key" => env.key, "uid" => env.uid, "etag" => env.etag } }
 
       SOURCE_KINDS = %w[url file asset].freeze
+      CONTENT_HASH_ALGO = "sha256"
+      TOMBSTONE_RETAIN = %w[ingested_at].freeze
 
-      def initialize(kind:, slug:, url: nil, path: nil, zone: nil, label: nil)
-        super()
-        @kind  = kind
-        @slug  = slug
-        @url   = url
-        @path  = path
-        @zone  = zone
-        @label = label
-      end
-
-      def call(container:, call:)
-        validate_inputs!
+      def self.call(container:, call:, kind:, slug:, url: nil, path: nil, zone: nil, label: nil, **) # rubocop:disable Metrics/ParameterLists
+        validation = validate_inputs(kind:, url:, path:, zone:)
+        return validation if validation.is_a?(Dry::Monads::Result::Failure)
 
         now = Time.now.utc
-        key = derive_key(now)
+        key = derive_key(now, kind:, slug:)
 
-        Textus::Gate::Auth.new(container).check_action!(
-          action: :ingest, actor: call.role, key: key,
-        )
-
-        write_raw_entry(key, now, container, call)
+        content_hash = compute_content_hash(kind:, url:, path:)
+        writer = Textus::Store::Envelope::Writer.from(container: container, call: call)
+        mentry = container.manifest.resolver.resolve(key).entry
+        ts = now.iso8601
+        structured = build_structured(ts, container, now, content_hash, kind:, url:, path:, label:, zone:)
+
+        store = container.job_store
+        index = Textus::Store::Index::Lookup.new(store: store)
+        duplicate_key = find_duplicate(index, content_hash, kind:, url:)
+
+        result = if duplicate_key && duplicate_key != key
+                   supersede_entry(duplicate_key, key, structured, container, call, store: store, kind:, zone:)
+                 else
+                   env = write_raw_entry(key, structured, mentry, writer)
+                   rebuild_index(container, store)
+                   env
+                 end
+        Success(result)
       end
 
-      private
-
-      def validate_inputs!
-        unless SOURCE_KINDS.include?(@kind)
-          raise Textus::UsageError.new(
-            "ingest kind must be one of #{SOURCE_KINDS.join("|")}, got #{@kind.inspect}",
-          )
+      def self.validate_inputs(kind:, url:, path:, zone:)
+        unless SOURCE_KINDS.include?(kind)
+          return Failure(code: :usage_error,
+                         message: "ingest kind must be one of #{SOURCE_KINDS.join("|")}, got #{kind.inspect}")
         end
-        case @kind
+        case kind
         when "url"
-          raise Textus::UsageError.new("ingest url requires --url") unless @url
+          return Failure(code: :usage_error, message: "ingest url requires --url") unless url
         when "file"
-          raise Textus::UsageError.new("ingest file requires --path") unless @path
+          return Failure(code: :usage_error, message: "ingest file requires --path") unless path
         when "asset"
-          raise Textus::UsageError.new("ingest asset requires --path") unless @path
-          raise Textus::UsageError.new("ingest asset requires --zone") unless @zone
+          return Failure(code: :usage_error, message: "ingest asset requires --path") unless path
+          return Failure(code: :usage_error, message: "ingest asset requires --zone") unless zone
         end
+        nil
+      end
+
+      # Key derivation for Gate pre-dispatch auth. Must match the runtime
+      # derivation in #call so the same key is checked by auth and used by
+      # the action body.
+      def self.dispatch_key(kind:, slug:, **)
+        derive_key(Time.now.utc, kind:, slug:)
       end
 
-      def derive_key(now)
+      def self.derive_key(now, kind:, slug:)
         date = now.strftime("%Y.%m.%d")
-        "raw.#{date}.#{@kind}-#{@slug}"
+        "raw.#{date}.#{kind}-#{slug}"
       end
 
-      def write_raw_entry(key, now, container, call)
-        ts     = now.iso8601
-        mentry = container.manifest.resolver.resolve(key).entry
-        writer = Textus::Envelope::Writer.from(container: container, call: call)
+      def self.compute_content_hash(kind:, url:, path:)
+        digest = Digest::SHA256.new
+        case kind
+        when "url"
+          digest.update(url)
+        when "file", "asset"
+          digest.file(path)
+        end
+        "#{CONTENT_HASH_ALGO}:#{digest.hexdigest}"
+      end
 
-        case @kind
+      def self.build_structured(timestamp, container, now, content_hash, kind:, url:, path:, label:, zone:) # rubocop:disable Metrics/ParameterLists
+        base = { "ingested_at" => timestamp, "content_hash" => content_hash }
+        case kind
         when "url"
-          structured = {
-            "ingested_at" => ts,
-            "source" => { "kind" => "url", "url" => @url, "label" => @label || @url },
-            "body" => nil,
-          }
-          writer.put(key, mentry: mentry,
-                          payload: Textus::Envelope::Writer::Payload.new(
-                            meta: nil, body: nil, content: structured,
-                          ))
+          base.merge("source" => { "kind" => "url", "url" => url, "label" => label || url },
+                     "body" => nil)
         when "file"
-          body_content = File.read(@path)
-          structured = {
-            "ingested_at" => ts,
-            "source" => { "kind" => "file", "path" => @path,
-                          "label" => @label || File.basename(@path) },
-            "body" => body_content,
-          }
-          writer.put(key, mentry: mentry,
-                          payload: Textus::Envelope::Writer::Payload.new(
-                            meta: nil, body: nil, content: structured,
-                          ))
+          body_content = File.read(path)
+          base.merge("source" => { "kind" => "file", "path" => path,
+                                   "label" => label || File.basename(path) },
+                     "body" => body_content)
         when "asset"
-          asset_rel = copy_asset_file(container, now)
-          structured = {
-            "ingested_at" => ts,
-            "source" => { "kind" => "asset",
-                          "label" => @label || File.basename(@path) },
-            "asset" => asset_rel,
-            "body" => nil,
-          }
-          writer.put(key, mentry: mentry,
-                          payload: Textus::Envelope::Writer::Payload.new(
-                            meta: nil, body: nil, content: structured,
-                          ))
+          asset_rel = copy_asset_file(container, now, path:, zone:)
+          base.merge("source" => { "kind" => "asset",
+                                   "label" => label || File.basename(path) },
+                     "asset" => asset_rel,
+                     "body" => nil)
         end
       end
 
-      def copy_asset_file(container, now)
+      def self.write_raw_entry(key, structured, mentry, writer)
+        writer.put(key, mentry: mentry,
+                        payload: Textus::Store::Envelope::Writer::Payload.new(
+                          meta: nil, body: nil, content: structured,
+                        ))
+      end
+
+      def self.find_duplicate(index, content_hash, kind:, url:)
+        dup = index.find_by_hash(content_hash)
+        return dup if dup
+
+        return unless kind == "url"
+
+        index.find_by_url(url)
+      end
+
+      def self.rebuild_index(container, store)
+        Textus::Store::Index::Builder.new(store: store).rebuild!(resolver: container.manifest.resolver)
+      end
+
+      def self.supersede_entry(old_key, new_key, structured, container, call, store:, kind:, zone:) # rubocop:disable Metrics/ParameterLists
+        old_mentry = container.manifest.resolver.resolve(old_key).entry
+        writer = Textus::Store::Envelope::Writer.from(container: container, call: call)
+
+        reader = Textus::Store::Envelope::Reader.from(container: container)
+        old_env = reader.read(old_key)
+        old_content = old_env&.content || {}
+        tombstone = {}
+        TOMBSTONE_RETAIN.each do |k|
+          tombstone[k] = old_content[k] if old_content.key?(k)
+        end
+        source_kind = old_content.dig("source", "kind")
+        tombstone["source"] = { "kind" => source_kind } if source_kind
+        tombstone["superseded_by"] = new_key
+
+        writer.put(old_key, mentry: old_mentry,
+                            payload: Textus::Store::Envelope::Writer::Payload.new(
+                              meta: nil, body: nil, content: tombstone,
+                            ))
+
+        structured["supersedes"] = old_key
+        env = write_raw_entry(new_key, structured, container.manifest.resolver.resolve(new_key).entry, writer)
+
+        move_asset_file(container, old_content["asset"], zone:) if kind == "asset" && old_content["asset"]
+
+        rebuild_index(container, store)
+        env
+      end
+
+      def self.move_asset_file(container, old_asset_rel, zone:)
+        old_path = File.join(container.root, "assets", old_asset_rel)
+        return unless File.exist?(old_path)
+
+        now = Time.now.utc
+        date_path = now.strftime("%Y/%m/%d")
+        filename = File.basename(old_path)
+        new_dir = File.join(container.root, "assets", "raw", date_path, zone)
+        new_path = File.join(new_dir, filename)
+
+        return if old_path == new_path
+
+        FileUtils.mkdir_p(new_dir)
+        FileUtils.mv(old_path, new_path)
+      rescue Errno::ENOENT, Errno::EACCES => e
+        warn "[textus ingest] could not move asset #{old_asset_rel}: #{e.message}"
+      end
+
+      def self.copy_asset_file(container, now, path:, zone:)
         date_path = now.strftime("%Y/%m/%d")
-        filename  = File.basename(@path)
-        assets_dir = File.join(container.root, "assets", "raw", date_path, @zone)
+        filename  = File.basename(path)
+        assets_dir = File.join(container.root, "assets", "raw", date_path, zone)
         FileUtils.mkdir_p(assets_dir)
-        FileUtils.cp(@path, File.join(assets_dir, filename))
+        FileUtils.cp(path, File.join(assets_dir, filename))
         create_gitignore_sentinel(container)
-        "raw/#{date_path}/#{@zone}/#{filename}"
+        "raw/#{date_path}/#{zone}/#{filename}"
       end
 
-      def create_gitignore_sentinel(container)
+      def self.create_gitignore_sentinel(container)
         assets_root = File.join(container.root, "assets")
         FileUtils.mkdir_p(assets_root)
         sentinel = File.join(assets_root, ".gitignore")

data/lib/textus/action/jobs.rb

@@ -3,8 +3,6 @@
 module Textus
   module Action
     class Jobs < Base
-      extend Textus::Contract::DSL
-
       verb :jobs
       summary "List queued jobs by state; retry a dead-lettered job or purge a state."
       surfaces :cli, :mcp
@@ -13,23 +11,16 @@ module Textus
       arg :action, String, default: nil, description: "retry|purge (optional)"
       arg :job_id, String, default: nil, description: "job id (required for action=retry)"
 
-      def initialize(state: "ready", action: nil, job_id: nil)
-        super()
-        @state = state
-        @action = action
-        @job_id = job_id
-      end
-
-      def call(container:, **)
-        queue = Textus::Ports::JobStore.new(root: container.root)
-        case @action
+      def self.call(container:, call:, state: "ready", action: nil, job_id: nil) # rubocop:disable Lint/UnusedMethodArgument
+        queue = Textus::Store::Jobs::Queue.new(store: container.job_store)
+        case action
         when "retry"
-          queue.retry_failed(@job_id)
+          queue.retry_failed(job_id)
         when "purge"
-          queue.purge(@state)
+          queue.purge(state)
         end
 
-        { "protocol" => Textus::PROTOCOL, "ok" => true, "state" => @state, "jobs" => queue.list(@state) }
+        Success({ "protocol" => Textus::PROTOCOL, "ok" => true, "state" => state, "jobs" => queue.list(state) })
       end
     end
   end

data/lib/textus/action/key_delete.rb

@@ -2,9 +2,7 @@
 
 module Textus
   module Action
-    class KeyDelete < WriteVerb
-      extend Textus::Contract::DSL
-
+    class KeyDelete < Base
       verb :key_delete
       summary "Delete one entry by key. Single-key, lower blast radius than key_delete_prefix; " \
               "guarded by an optional optimistic-concurrency etag. Returns {ok, key, deleted}."
@@ -15,21 +13,13 @@ module Textus
       arg :if_etag, String,
           description: "optimistic-concurrency guard: the etag you last read; the delete is rejected if the entry changed since"
 
-      def initialize(key:, if_etag: nil)
-        super()
-        @key = key
-        @if_etag = if_etag
-      end
-
-      def call(container:, call:)
-        run_with_cascade(@key, container:, call:) do
-          Textus::Manifest::Data.validate_key!(@key)
-          mentry = container.manifest.resolver.resolve(@key).entry
+      def self.call(container:, call:, key:, if_etag: nil)
+        Textus::Manifest::Data.validate_key!(key)
+        mentry = container.manifest.resolver.resolve(key).entry
 
-          writer(container, call).delete(@key, mentry:, if_etag: @if_etag)
+        container.compositor.delete(key, mentry: mentry, if_etag: if_etag, call: call)
 
-          { "protocol" => Textus::PROTOCOL, "ok" => true, "key" => @key, "deleted" => true }
-        end
+        Success({ "protocol" => Textus::PROTOCOL, "ok" => true, "key" => key, "deleted" => true })
       end
     end
   end

data/lib/textus/action/key_delete_prefix.rb

@@ -3,8 +3,6 @@
 module Textus
   module Action
     class KeyDeletePrefix < Base
-      extend Textus::Contract::DSL
-
       verb :key_delete_prefix
       summary "Bulk-delete every leaf key under prefix."
       surfaces :cli, :mcp
@@ -16,28 +14,21 @@ module Textus
                                            "defaults to false, so omitting it deletes immediately"
       view { |v, _i| v.to_h }
 
-      def initialize(prefix:, dry_run: false)
-        super()
-        @prefix = prefix
-        @dry_run = dry_run
-      end
-
-      def call(container:, call:)
-        raise UsageError.new("prefix required") if @prefix.nil? || @prefix.empty?
+      def self.call(container:, call:, prefix:, dry_run: false)
+        return Failure(code: :usage_error, message: "prefix required") if prefix.nil? || prefix.empty?
 
-        leaves = Textus::Action::List.new(prefix: @prefix).call(container: container)
-                                     .map { |row| row.is_a?(Hash) ? (row["key"] || row[:key]) : row }
+        leaves = Textus::Action::List.leaf_keys(container: container, prefix: prefix)
 
-        warnings = leaves.empty? ? ["no keys under #{@prefix}"] : []
+        warnings = leaves.empty? ? ["no keys under #{prefix}"] : []
         steps = leaves.map { |key| { "op" => "delete", "key" => key } }
 
-        plan = Textus::Jobs::Plan.new(steps: steps, warnings: warnings)
-        return plan if @dry_run
+        plan = Textus::Store::Jobs::Plan.new(steps: steps, warnings: warnings)
+        return Success(plan) if dry_run
 
         steps.each do |step|
-          Textus::Action::KeyDelete.new(key: step["key"]).call(container: container, call: call)
+          Value::Result.unwrap(Textus::Action::KeyDelete.call(container: container, call: call, key: step["key"]))
         end
-        plan
+        Success(plan)
       end
     end
   end