textus 0.53.0 → 0.54.0

data/lib/textus/action/deps.rb

@@ -11,8 +11,6 @@ module Textus
       arg :key, String, required: true, positional: true,
                         description: "dotted key of the derived entry whose source keys you want"
 
-      BURN = :sync
-
       def initialize(key:)
         super()
         @key = key
@@ -20,19 +18,7 @@ module Textus
 
       def call(container:, **)
         entry = container.manifest.data.entries.find { |e| e.key == @key }
-        deps =
-          if entry&.derived?
-            src = entry.source
-            if src.projection?
-              Array(src.select).compact
-            elsif src.external?
-              Array(src.sources).compact
-            else
-              []
-            end
-          else
-            []
-          end
+        deps = entry&.external? ? Array(entry.source&.sources).compact : []
         { "key" => @key, "deps" => deps.uniq }
       end
 

data/lib/textus/action/doctor.rb

@@ -11,8 +11,6 @@ module Textus
       cli "doctor"
       arg :checks, Array, required: false, description: "subset of check names to run (default: all)"
 
-      BURN = :sync
-
       def initialize(checks: nil)
         super()
         @checks = checks

data/lib/textus/action/drain.rb

@@ -6,14 +6,12 @@ module Textus
       extend Textus::Contract::DSL
 
       verb :drain
-      summary "Seed refresh + sweep jobs then drain the queue to empty. " \
+      summary "Seed materialize + sweep jobs then drain the queue to empty. " \
               "Identical to one Watcher tick. Use when no watcher is running."
       surfaces :cli, :mcp
       arg :prefix, String, description: "restrict to keys under this dotted prefix"
       arg :lane,   String, description: "restrict to entries in this lane"
 
-      BURN = :sync
-
       def initialize(prefix: nil, lane: nil)
         super()
         @prefix = prefix
@@ -21,14 +19,14 @@ module Textus
       end
 
       def call(container:, call:)
-        queue = Textus::Ports::Queue.new(root: container.root)
-        Textus::Background::Planner::Plan.seed(
+        queue = Textus::Ports::JobStore.new(root: container.root)
+        Textus::Jobs::Planner.seed(
           container: container,
           queue: queue,
           role: call.role,
         )
         queue.reclaim(now: Textus::Ports::Clock.new.now)
-        summary = Textus::Background::Worker.for(container:, queue:).drain
+        summary = Textus::Jobs::Worker.for(container:, queue:).drain
         {
           "protocol" => Textus::PROTOCOL,
           "ok" => summary.failed.zero?,

data/lib/textus/action/enqueue.rb

@@ -14,8 +14,6 @@ module Textus
       arg :args, Hash, default: {},
                        description: "type-specific arguments (e.g. { key: ... } or { scope: ... })"
 
-      BURN = :sync
-
       def initialize(type:, args: {})
         super()
         @type = type
@@ -28,7 +26,7 @@ module Textus
 
       def call(container:, call:)
         action_class = begin
-          Textus::Background::Job.fetch(@type.to_s)
+          Textus::Jobs.fetch(@type.to_s)
         rescue Textus::UsageError
           raise Textus::UsageError.new("unregistered job type '#{@type}'")
         end
@@ -41,13 +39,13 @@ module Textus
           )
         end
 
-        job = Textus::Ports::Queue::Job.new(
+        job = Textus::Ports::JobStore::Job.new(
           type: @type,
           args: @job_args,
           enqueued_by: call.role,
           max_attempts: 3,
         )
-        Textus::Ports::Queue.new(root: container.root).enqueue(job)
+        Textus::Ports::JobStore.new(root: container.root).enqueue(job)
         { "protocol" => Textus::PROTOCOL, "ok" => true, "id" => job.id }
       end
     end

data/lib/textus/action/get.rb

@@ -15,8 +15,6 @@ module Textus
                         description: "dotted entry key to read, e.g. 'knowledge.project'"
       view { |v, _i| v.to_h_for_wire }
 
-      BURN = :sync
-
       def initialize(key:)
         super()
         @key = key
@@ -64,7 +62,7 @@ module Textus
         return nil unless @file_store.exists?(path)
 
         raw = @file_store.read(path)
-        parsed = Textus::Entry.for_format(mentry.format).parse(raw, path: path)
+        parsed = Textus::Format.for(mentry.format).parse(raw, path: path)
         Textus::Envelope.build(
           key: key,
           mentry: mentry,

data/lib/textus/action/ingest.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "date"
+
+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
+      arg :kind,  String, required: true, positional: true,
+                          description: "source kind: url | file | asset"
+      arg :slug,  String, required: true,
+                          description: "human slug for the key suffix (kebab-case)"
+      arg :url,   String, description: "remote URL (required when kind=url)"
+      arg :path,  String, description: "local file path (required when kind=file or kind=asset)"
+      arg :zone,  String, description: "asset group subdirectory (required when kind=asset)"
+      arg :label, String, description: "human label stored in source.label"
+      view { |env| { "key" => env.key, "uid" => env.uid, "etag" => env.etag } }
+
+      SOURCE_KINDS = %w[url file asset].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!
+
+        now = Time.now.utc
+        key = derive_key(now)
+
+        Textus::Gate::Auth.new(container).check_action!(
+          action: :ingest, actor: call.role, key: key,
+        )
+
+        write_raw_entry(key, now, container, call)
+      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}",
+          )
+        end
+        case @kind
+        when "url"
+          raise Textus::UsageError.new("ingest url requires --url") unless @url
+        when "file"
+          raise Textus::UsageError.new("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
+        end
+      end
+
+      def derive_key(now)
+        date = now.strftime("%Y.%m.%d")
+        "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)
+
+        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,
+                          ))
+        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,
+                          ))
+        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,
+                          ))
+        end
+      end
+
+      def copy_asset_file(container, now)
+        date_path = now.strftime("%Y/%m/%d")
+        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))
+        create_gitignore_sentinel(container)
+        "raw/#{date_path}/#{@zone}/#{filename}"
+      end
+
+      def create_gitignore_sentinel(container)
+        assets_root = File.join(container.root, "assets")
+        FileUtils.mkdir_p(assets_root)
+        sentinel = File.join(assets_root, ".gitignore")
+        File.write(sentinel, "*\n") unless File.exist?(sentinel)
+      end
+    end
+  end
+end

data/lib/textus/action/jobs.rb

@@ -13,8 +13,6 @@ module Textus
       arg :action, String, default: nil, description: "retry|purge (optional)"
       arg :job_id, String, default: nil, description: "job id (required for action=retry)"
 
-      BURN = :sync
-
       def initialize(state: "ready", action: nil, job_id: nil)
         super()
         @state = state
@@ -23,7 +21,7 @@ module Textus
       end
 
       def call(container:, **)
-        queue = Textus::Ports::Queue.new(root: container.root)
+        queue = Textus::Ports::JobStore.new(root: container.root)
         case @action
         when "retry"
           queue.retry_failed(@job_id)

data/lib/textus/action/key_delete.rb

@@ -15,8 +15,6 @@ module Textus
       arg :if_etag, String,
           description: "optimistic-concurrency guard: the etag you last read; the delete is rejected if the entry changed since"
 
-      BURN = :sync
-
       def initialize(key:, if_etag: nil)
         super()
         @key = key
@@ -28,16 +26,8 @@ module Textus
           Textus::Manifest::Data.validate_key!(@key)
           mentry = container.manifest.resolver.resolve(@key).entry
 
-          auth(container).check_action!(action: :key_delete, actor: call.role, key: @key, extra: { if_etag: @if_etag })
-
           writer(container, call).delete(@key, mentry:, if_etag: @if_etag)
 
-          container.steps.publish(
-            :entry_deleted,
-            ctx: Textus::Step::Context.for(container: container, call: call),
-            key: @key,
-          )
-
           { "protocol" => Textus::PROTOCOL, "ok" => true, "key" => @key, "deleted" => true }
         end
       end

data/lib/textus/action/key_delete_prefix.rb

@@ -16,8 +16,6 @@ module Textus
                                            "defaults to false, so omitting it deletes immediately"
       view { |v, _i| v.to_h }
 
-      BURN = :sync
-
       def initialize(prefix:, dry_run: false)
         super()
         @prefix = prefix
@@ -33,7 +31,7 @@ module Textus
         warnings = leaves.empty? ? ["no keys under #{@prefix}"] : []
         steps = leaves.map { |key| { "op" => "delete", "key" => key } }
 
-        plan = Textus::Background::Plan.new(steps: steps, warnings: warnings)
+        plan = Textus::Jobs::Plan.new(steps: steps, warnings: warnings)
         return plan if @dry_run
 
         steps.each do |step|

data/lib/textus/action/key_mv.rb

@@ -18,8 +18,6 @@ module Textus
                        "defaults to false, so omitting it applies the move immediately " \
                        "(unlike the bulk key_mv_prefix, which defaults to a dry-run plan)"
 
-      BURN = :sync
-
       def initialize(old_key:, new_key:, dry_run: false)
         super()
         @old_key = old_key
@@ -44,7 +42,6 @@ module Textus
         return dry_run_result(container, old_res, new_res) if @dry_run
 
         envelope = apply_move(container, call, old_res, new_res)
-        publish_rename(container, call, envelope)
         success_result(old_res, new_res, envelope)
       end
 
@@ -57,17 +54,6 @@ module Textus
         )
       end
 
-      def publish_rename(container, call, envelope)
-        container.steps.publish(
-          :entry_renamed,
-          ctx: Textus::Step::Context.for(container: container, call: call),
-          key: @new_key,
-          from_key: @old_key,
-          to_key: @new_key,
-          envelope: envelope,
-        )
-      end
-
       def success_result(old_res, new_res, envelope)
         {
           "protocol" => PROTOCOL,
@@ -117,7 +103,7 @@ module Textus
         writer(container, call).put(
           @old_key,
           mentry: old_mentry,
-          payload: Textus::Envelope::IO::Writer::Payload.new(
+          payload: Textus::Envelope::Writer::Payload.new(
             meta: pre_env.meta,
             body: pre_env.body,
             content: pre_env.content,

data/lib/textus/action/key_mv_prefix.rb

@@ -18,8 +18,6 @@ module Textus
                                            "to false, so omitting it applies the rename immediately"
       view { |v, _i| v.to_h }
 
-      BURN = :sync
-
       def initialize(from_prefix:, to_prefix:, dry_run: false)
         super()
         @from_prefix = from_prefix
@@ -46,7 +44,7 @@ module Textus
           { "op" => "mv", "from" => old_key, "to" => new_key }
         end
 
-        plan = Textus::Background::Plan.new(steps: steps, warnings: warnings)
+        plan = Textus::Jobs::Plan.new(steps: steps, warnings: warnings)
         return plan if @dry_run
 
         steps.each do |step|

data/lib/textus/action/list.rb

@@ -14,8 +14,6 @@ module Textus
           description: "restrict to one lane by name (see `boot` lanes); combine with prefix to narrow further"
       view(:cli) { |rows| { "entries" => rows } }
 
-      BURN = :sync
-
       def initialize(prefix: nil, lane: nil)
         super()
         @prefix = prefix

data/lib/textus/action/propose.rb

@@ -19,8 +19,6 @@ module Textus
           description: "structured payload for json/yaml-format entries; omit (use `body`) for markdown entries. Do not send both"
       view { |env, _i| env.to_h_for_wire }
 
-      BURN = :sync
-
       def initialize(key:, meta: nil, body: nil, content: nil)
         super()
         @key = key

data/lib/textus/action/published.rb

@@ -10,8 +10,6 @@ module Textus
       surfaces :cli
       cli "published"
 
-      BURN = :sync
-
       def args
         {}
       end

data/lib/textus/action/pulse.rb

@@ -8,14 +8,12 @@ module Textus
       extend Textus::Contract::DSL
 
       verb :pulse
-      summary "Delta since cursor — changed entries, stale, pending proposals, doctor summary."
+      summary "Delta since cursor — changed entries, pending proposals, index freshness."
       surfaces :cli, :mcp
       around :cursor
       arg :since, Integer, session_default: :cursor,
                            description: "audit seq to diff from; defaults to the session cursor"
 
-      BURN = :sync
-
       def initialize(since: nil)
         super()
         @since = since
@@ -27,30 +25,18 @@ module Textus
         @manifest = container.manifest
         @audit_log = container.audit_log
         @root = container.root
-        @steps = container.steps
 
-        freshness_rows = Pulse::Scanner.new.call(container: container, call: call)
         {
           "cursor" => @audit_log.latest_seq,
           "changed" => Textus::Action::Audit.new(seq_since: @since).call(container: container),
-          "stale" => freshness_rows.select { |row| row[:status] == :expired }.map { |row| row[:key] },
           "pending_review" => review_keys,
-          "doctor" => doctor_summary,
           "contract_etag" => Textus::Etag.for_contract(@root),
-          "next_due_at" => soonest_due(freshness_rows),
-          "hook_errors" => hook_errors_since(@since || 0),
+          "index_etag" => index_etag(container),
         }
       end
 
       private
 
-      def soonest_due(rows)
-        times = rows.map { |row| row[:next_due_at] }.compact.map { |t| Time.parse(t) }
-        return nil if times.empty?
-
-        times.min.utc.iso8601
-      end
-
       def review_keys
         queue = @manifest.policy.queue_lane
         return [] unless queue
@@ -59,28 +45,11 @@ module Textus
         rows.map { |row| row.is_a?(Hash) ? (row["key"] || row[:key]) : row }
       end
 
-      def doctor_summary
-        result = Textus::Doctor.build(container: @container)
-        issues = result["issues"] || []
-        {
-          "ok" => result["ok"],
-          "warn" => issues.count { |i| i["level"] == "warning" },
-          "fail" => issues.count { |i| i["level"] == "error" },
-        }
-      end
-
-      def hook_errors_since(seq)
-        @steps.error_log.since(seq).map do |row|
-          {
-            "seq" => row[:seq],
-            "event" => row[:event].to_s,
-            "hook" => row[:hook].to_s,
-            "key" => row[:key],
-            "error_class" => row[:error_class],
-            "error_message" => row[:error_message],
-            "at" => row[:at],
-          }
-        end
+      def index_etag(container)
+        path = container.manifest.resolver.resolve("artifacts.index").path
+        File.exist?(path) ? container.file_store.etag(path) : nil
+      rescue Textus::Error
+        nil
       end
     end
   end

data/lib/textus/action/put.rb

@@ -20,8 +20,6 @@ module Textus
           description: "optimistic-concurrency guard: the etag you last read; the write is rejected if the entry changed since"
       view { |env| { "uid" => env.uid, "etag" => env.etag } }
 
-      BURN = :sync
-
       def initialize(key:, meta: nil, body: nil, content: nil, if_etag: nil)
         super()
         @key = key
@@ -35,12 +33,10 @@ module Textus
         run_with_cascade(@key, container:, call:) do
           Textus::Manifest::Data.validate_key!(@key)
           mentry = container.manifest.resolver.resolve(@key).entry
-          auth(container).check_action!(action: :put, actor: call.role, key: @key, extra: { if_etag: @if_etag })
-
           envelope = writer(container, call).put(
             @key,
             mentry: mentry,
-            payload: Textus::Envelope::IO::Writer::Payload.new(
+            payload: Textus::Envelope::Writer::Payload.new(
               meta: @meta,
               body: @body,
               content: @content,
@@ -48,13 +44,6 @@ module Textus
             if_etag: @if_etag,
           )
 
-          container.steps.publish(
-            :entry_written,
-            ctx: Textus::Step::Context.for(container: container, call: call),
-            key: @key,
-            envelope: envelope,
-          )
-
           envelope
         end
       end

data/lib/textus/action/rdeps.rb

@@ -11,8 +11,6 @@ module Textus
       arg :key, String, required: true, positional: true,
                         description: "dotted key whose dependents (what would be stranded if it moved) you want"
 
-      BURN = :sync
-
       def initialize(key:)
         super()
         @key = key
@@ -21,17 +19,9 @@ module Textus
       def call(container:, **)
         manifest = container.manifest
         rdeps = manifest.data.entries.each_with_object([]) do |entry, acc|
-          next unless entry.derived?
+          next unless entry.external?
 
-          src = entry.source
-          sources =
-            if src.projection?
-              Array(src.select).compact
-            elsif src.external?
-              Array(src.sources).compact
-            else
-              []
-            end
+          sources = Array(entry.source&.sources).compact
           acc << entry.key if sources.any? { |source| source == @key || @key.start_with?("#{source}.") }
         end
         { "key" => @key, "rdeps" => rdeps }

data/lib/textus/action/reject.rb

@@ -11,8 +11,6 @@ module Textus
       cli "reject"
       arg :pending_key, String, required: true, positional: true, description: "the queued proposal's key"
 
-      BURN = :sync
-
       def initialize(pending_key:)
         super()
         @pending_key = pending_key
@@ -20,9 +18,6 @@ module Textus
 
       def call(container:, call:)
         run_with_cascade(@pending_key, container:, call:) do
-          auth = Textus::Gate::Auth.new(container)
-          auth.check_action!(action: :reject, actor: call.role, key: @pending_key)
-
           mentry = container.manifest.resolver.resolve(@pending_key).entry
           unless mentry.in_proposal_lane?(container.manifest.policy)
             raise ProposalError.new("reject: '#{@pending_key}' is not in a proposal zone (zone=#{mentry.lane})")
@@ -34,13 +29,6 @@ module Textus
 
           writer(container, call).delete(@pending_key, mentry: mentry)
 
-          container.steps.publish(
-            :proposal_rejected,
-            ctx: Textus::Step::Context.for(container: container, call: call),
-            key: @pending_key,
-            target_key: target_key,
-          )
-
           { "protocol" => PROTOCOL, "rejected" => @pending_key, "target_key" => target_key }
         end
       end

data/lib/textus/action/rule_explain.rb

@@ -15,8 +15,6 @@ module Textus
           description: "defaults false: lean {lifecycle, guard}. detail: true adds matched blocks + guard predicates per transition."
       view(:cli) { |r| { "verb" => "rule_explain" }.merge(r.transform_keys(&:to_s)) }
 
-      BURN = :sync
-
       def initialize(key:, detail: nil)
         super()
         @key = key
@@ -79,8 +77,6 @@ module Textus
           retention_hash(value, string_keys: false)
         when :react
           value.to_h
-        when :handler_permit
-          value.handlers
         else
           value
         end

data/lib/textus/action/rule_lint.rb

@@ -15,8 +15,6 @@ module Textus
                                    description: "path to candidate manifest YAML; its `rules:` block is diffed against the live manifest"
       view { |v, _i| v.to_h }
 
-      BURN = :sync
-
       def initialize(candidate_yaml:)
         super()
         @candidate_yaml = candidate_yaml
@@ -47,7 +45,7 @@ module Textus
           }
         end
 
-        Textus::Background::Plan.new(steps: steps, warnings: [])
+        Textus::Jobs::Plan.new(steps: steps, warnings: [])
       end
 
       private

data/lib/textus/action/rule_list.rb

@@ -11,8 +11,6 @@ module Textus
       cli "rule list"
       view(:cli) { |policies| { "verb" => "rule_list", "policies" => policies } }
 
-      BURN = :sync
-
       def call(container:, **)
         manifest = container.manifest
         manifest.rules.blocks.map do |block|
@@ -35,8 +33,6 @@ module Textus
           { "ttl_seconds" => value.ttl_seconds, "action" => value.action.to_s }
         when :react
           value.to_h
-        when :handler_permit
-          value.handlers
         else
           value
         end

data/lib/textus/action/schema_envelope.rb

@@ -12,8 +12,6 @@ module Textus
       arg :key, String, required: true, positional: true,
                         description: "any key in the family whose schema you want; returns required/optional fields and their types"
 
-      BURN = :sync
-
       def initialize(key:)
         super()
         @key = key

data/lib/textus/action/uid.rb

@@ -12,8 +12,6 @@ module Textus
       arg :key, String, required: true, positional: true, description: "entry key"
       view(:cli) { |uid, inputs| { "key" => inputs[:key], "uid" => uid } }
 
-      BURN = :sync
-
       def initialize(key:)
         super()
         @key = key