textus 0.54.2 → 0.55.1

data/lib/textus/store/jobs/queue.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "securerandom"
+require "time"
+
+module Textus
+  class Store
+    module Jobs
+      class Queue
+        VALID_STATES = %w[ready leased done failed].freeze
+
+        Leased = Data.define(:job)
+
+        class Job
+          DIGEST_BYTES = 16
+
+          attr_reader :type, :args, :role, :attempts, :max_attempts, :errors
+
+          def initialize(type:, args:, role:, attempts: 0, max_attempts: 3, errors: [])
+            @type = type.to_s
+            @args = stringify(args)
+            @role = role.to_s
+            @attempts = attempts.to_i
+            @max_attempts = max_attempts.to_i
+            @errors = Array(errors)
+          end
+
+          def id
+            "#{type}:#{Digest::SHA256.hexdigest(JSON.dump(args.sort.to_h))[0, DIGEST_BYTES]}"
+          end
+
+          private
+
+          def stringify(hash)
+            hash.to_h.transform_keys(&:to_s)
+          end
+        end
+
+        def initialize(store:)
+          @store = store
+        end
+
+        def enqueue(job)
+          now = iso_now
+          @store.execute(
+            "INSERT OR IGNORE INTO jobs (id, type, args, state, role, attempts, max_attempts, errors, lease, created_at, updated_at)
+           VALUES (?, ?, ?, 'ready', ?, ?, ?, ?, NULL, ?, ?)",
+            [job.id, job.type, JSON.dump(job.args), job.role, job.attempts, job.max_attempts, JSON.dump(job.errors), now, now],
+          )
+        end
+
+        def ready_ids
+          list(:ready)
+        end
+
+        def lease(worker_id:, lease_ttl:)
+          now = Time.now.utc
+          expires_at = now + lease_ttl
+          token = SecureRandom.hex(8)
+          marked_lease = JSON.dump({ "worker_id" => worker_id, "expires_at" => expires_at.iso8601, "token" => token })
+
+          @store.execute(
+            "UPDATE jobs
+              SET state = 'leased', lease = ?, updated_at = ?
+            WHERE id = (
+              SELECT id FROM jobs WHERE state = 'ready' ORDER BY created_at, id LIMIT 1
+            )",
+            [marked_lease, now.iso8601],
+          )
+          row = @store.execute("SELECT * FROM jobs WHERE state = 'leased' AND lease = ? LIMIT 1", [marked_lease]).first
+          return nil unless row
+
+          Leased.new(job_from_row(row))
+        end
+
+        def ack(leased)
+          @store.execute(
+            "UPDATE jobs SET state = 'done', lease = NULL, updated_at = ? WHERE id = ? AND state = 'leased'",
+            [iso_now, leased.job.id],
+          )
+        end
+
+        def fail(leased, error:)
+          job = leased.job
+          attempts = job.attempts + 1
+          errors = job.errors + [{ "attempt" => attempts, "error" => error, "at" => iso_now }]
+          dead = attempts >= job.max_attempts
+          state = dead ? "failed" : "ready"
+          @store.execute(
+            "UPDATE jobs SET state = ?, attempts = ?, errors = ?, lease = NULL, updated_at = ? WHERE id = ?",
+            [state, attempts, JSON.dump(errors), iso_now, job.id],
+          )
+          dead ? :dead_lettered : :requeued
+        end
+
+        def reclaim(now:)
+          rows = @store.execute("SELECT id, lease FROM jobs WHERE state = 'leased'")
+          expired = rows.select do |row|
+            lease = JSON.parse(row["lease"] || "{}")
+            expires_at = lease["expires_at"]
+            expires_at.nil? || Time.parse(expires_at) <= now
+          end
+          expired.each do |row|
+            @store.execute(
+              "UPDATE jobs SET state = 'ready', lease = NULL, updated_at = ? WHERE id = ?",
+              [now.utc.iso8601, row["id"]],
+            )
+          end
+          expired.size
+        end
+
+        def list(state)
+          state = state.to_s
+          raise Textus::UsageError.new("unknown job state: #{state}") unless VALID_STATES.include?(state)
+
+          @store.execute("SELECT id FROM jobs WHERE state = ? ORDER BY created_at, id", [state]).map { |row| row["id"] }
+        end
+
+        def retry_failed(job_id)
+          @store.execute(
+            "UPDATE jobs SET state = 'ready', attempts = 0, errors = ?, lease = NULL, updated_at = ? WHERE id = ? AND state = 'failed'",
+            [JSON.dump([]), iso_now, job_id],
+          )
+        end
+
+        def purge(state)
+          state = state.to_s
+          raise Textus::UsageError.new("unknown job state: #{state}") unless VALID_STATES.include?(state)
+
+          @store.execute("DELETE FROM jobs WHERE state = ?", [state])
+        end
+
+        private
+
+        def job_from_row(row)
+          Job.new(
+            type: row["type"],
+            args: JSON.parse(row["args"] || "{}"),
+            role: row["role"],
+            attempts: row["attempts"],
+            max_attempts: row["max_attempts"],
+            errors: JSON.parse(row["errors"] || "[]"),
+          )
+        end
+
+        def iso_now
+          Time.now.utc.iso8601
+        end
+      end
+    end
+  end
+end

data/lib/textus/store/jobs/registry.rb

@@ -0,0 +1,19 @@
+module Textus
+  class Store
+    module Jobs
+      module Registry
+        class UnknownJob < KeyError; end
+
+        JOBS = {
+          "index" => Store::Jobs::Index,
+          "materialize" => Store::Jobs::Materialize,
+          "sweep" => Store::Jobs::Sweep,
+        }.freeze
+
+        def self.fetch(type)
+          JOBS.fetch(type.to_s) { raise UnknownJob.new("Unknown job type: #{type}") }
+        end
+      end
+    end
+  end
+end

data/lib/textus/store/jobs/retention.rb

@@ -0,0 +1,50 @@
+require "fileutils"
+
+module Textus
+  class Store
+    module Jobs
+      class Retention
+        def initialize(container:, call:)
+          @container = container
+          @call = call
+        end
+
+        def call(rows)
+          out = { dropped: [], archived: [], failed: [] }
+          rows.each do |row|
+            key = row["key"]
+            begin
+              case row["action"]
+              when "drop"
+                delete(key)
+                out[:dropped] << key
+              when "archive"
+                archive_leaf(row)
+                delete(key)
+                out[:archived] << key
+              end
+            rescue Textus::Error => e
+              out[:failed] << { "key" => key, "error" => e.message }
+            end
+          end
+          out
+        end
+
+        private
+
+        def archive_leaf(row)
+          src  = row["path"]
+          root = @container.root.to_s
+          rel  = src.delete_prefix("#{root}/")
+          dest = File.join(root, "archive", rel)
+          FileUtils.mkdir_p(File.dirname(dest))
+          FileUtils.cp(src, dest)
+        end
+
+        def delete(key)
+          Textus::Action::KeyDelete.call(container: @container, call: @call, key: key)
+        end
+      end
+    end
+  end
+end

data/lib/textus/store/jobs/sweep.rb

@@ -0,0 +1,21 @@
+module Textus
+  class Store
+    module Jobs
+      class Sweep < Base
+        REQUIRED_ROLE = Textus::Value::Role::AUTOMATION
+        TYPE = "sweep"
+
+        def self.call(container:, call:, scope: {}, key: nil)
+          prefix = key || (scope.is_a?(Hash) ? scope["prefix"] : nil)
+          lane   = scope.is_a?(Hash) ? scope["lane"] : nil
+          rows = Textus::Core::Retention::Sweep.new(
+            manifest: container.manifest,
+            file_stat: Textus::Port::Storage::FileStat.new,
+            clock: Textus::Port::Clock.new,
+          ).call(prefix: prefix, lane: lane)
+          Textus::Store::Jobs::Retention.new(container: container, call: call).call(rows)
+        end
+      end
+    end
+  end
+end

data/lib/textus/store/jobs/worker.rb

@@ -0,0 +1,64 @@
+module Textus
+  class Store
+    module Jobs
+      class Worker
+        Summary = Struct.new(:completed, :failed, keyword_init: true)
+
+        def self.for(container:, queue:)
+          new(queue: queue, container: container,
+              lease_ttl: container.manifest.data.worker_config[:lease_ttl])
+        end
+
+        def initialize(queue:, container:, lease_ttl: 60)
+          @queue     = queue
+          @container = container
+          @lease_ttl = lease_ttl
+        end
+
+        def drain(worker_id: "drain-#{Process.pid}")
+          completed = 0
+          failed    = 0
+          loop do
+            leased = @queue.lease(worker_id: worker_id, lease_ttl: @lease_ttl)
+            break unless leased
+
+            case run_one(leased)
+            when :completed     then completed += 1
+            when :dead_lettered then failed += 1
+            end
+          end
+          Summary.new(completed: completed, failed: failed)
+        end
+
+        def drain_pool(pool: 4)
+          summaries = []
+          mutex     = Mutex.new
+          threads   = Array.new(pool) do |i|
+            Thread.new do
+              s = drain(worker_id: "pool-#{Process.pid}-#{i}")
+              mutex.synchronize { summaries << s }
+            end
+          end
+          threads.each(&:join)
+          Summary.new(completed: summaries.sum(&:completed), failed: summaries.sum(&:failed))
+        end
+
+        private
+
+        def run_one(leased)
+          job    = leased.job
+          klass  = Textus::Jobs.fetch(job.type)
+          call   = Textus::Value::Call.build(
+            role: job.role || Textus::Value::Role::AUTOMATION,
+            correlation_id: SecureRandom.uuid,
+          )
+          klass.call(container: @container, call: call, **job.args.transform_keys(&:to_sym))
+          @queue.ack(leased)
+          :completed
+        rescue StandardError => e
+          @queue.fail(leased, error: e.message)
+        end
+      end
+    end
+  end
+end

data/lib/textus/store/session.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+module Textus
+  # The agent session: per-connection (MCP), per-process (CLI), or per-loop
+  # (Ruby) orientation state — the audit cursor plus the contract etag and
+  # propose_lane captured at boot. Immutable Dry::Struct::Value; advance_cursor
+  # and with return new instances. ADR 0036; contract_etag widened in ADR 0074.
+  class Store
+    class Session < Dry::Struct
+      attribute :role,          Value::Types::RoleName
+      attribute :cursor,        Value::Types::Cursor
+      attribute :propose_lane,  Value::Types::String.optional
+      attribute :contract_etag, Value::Types::String
+
+      def with(**attrs) = self.class.new(to_h.merge(attrs))
+
+      def advance_cursor(new_cursor) = with(cursor: new_cursor)
+
+      def check_etag!(observed_etag)
+        return if observed_etag == contract_etag
+
+        raise Textus::ContractDrift.new(
+          "contract changed (manifest/hooks/schemas were #{short_etag(contract_etag)}, " \
+          "now #{short_etag(observed_etag)}); re-run boot",
+        )
+      end
+
+      private
+
+      # First 8 hex chars after the "sha256:" prefix — a stable short id for
+      # the drift diagnostic.
+      def short_etag(etag) = etag.to_s.delete_prefix("sha256:")[0, 8]
+    end
+  end
+end

data/lib/textus/store.rb

@@ -7,7 +7,7 @@ module Textus
     # Readers are derived from the Container's schema, so the field set lives
     # in exactly one place (Container). A new capability added there is
     # automatically exposed on the Store.
-    Textus::Container.attribute_names.each do |field|
+    Textus::Store::Container.attribute_names.each do |field|
       define_method(field) { @container.public_send(field) }
     end
 
@@ -49,11 +49,11 @@ module Textus
     # Build an agent Session oriented at the current cursor/manifest — the
     # Ruby equivalent of an MCP `initialize`. ADR 0036.
     def session(role:)
-      Textus::Session.new(
+      Textus::Store::Session.new(
         role: role.to_s,
         cursor: audit_log.latest_seq,
         propose_lane: manifest.policy.propose_lane_for(role),
-        contract_etag: Textus::Etag.for_contract(root),
+        contract_etag: Textus::Value::Etag.for_contract(root),
       )
     end
 
@@ -62,30 +62,38 @@ module Textus
     end
 
     def as(role, dry_run: false, correlation_id: nil)
-      Textus::Surfaces::RoleScope.new(container: container, role: role, dry_run: dry_run, correlation_id: correlation_id)
+      Textus::Surface::RoleScope.new(container: container, role: role, dry_run: dry_run, correlation_id: correlation_id)
     end
 
     private
 
     def build_container(root)
       manifest = Manifest.load(root)
-      container = Container.new(
-        root: root,
-        manifest: manifest,
-        schemas: Schemas.new(File.join(root, "schemas")),
-        file_store: Ports::Storage::FileStore.new,
-        audit_log: Ports::AuditLog.new(
+      job_store = Port::Store.new(root: root).setup!
+      geometry = Store::Geometry.new(root)
+      infra = Container::Infrastructure.new(
+        file_store: Port::Storage::FileStore.new,
+        schemas: Schemas.new(geometry.schemas_dir),
+        audit_log: Port::AuditLog.new(
           root,
           max_size: manifest.data.audit_config[:max_size],
           keep: manifest.data.audit_config[:keep],
         ),
+        job_store:,
+        geometry:,
+      )
+
+      coord = Container::Coordination.new(
+        manifest:,
         workflows: Workflow::Loader.load_all(root),
         gate: nil,
+        compositor: nil,
       )
+
+      container = Container.new(infra, coord)
+      compositor = Store::Compositor.new(container)
       gate = Textus::Gate.new(container)
-      container = container.with(gate: gate)
-      gate.instance_variable_set(:@container, container)
-      container
+      container.wire_gate!(gate, compositor)
     end
   end
 end

data/lib/textus/{surfaces → surface}/cli/group/data.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Group
         class Data < Group

data/lib/textus/{surfaces → surface}/cli/group/key.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Group
         class Key < Group

data/lib/textus/{surfaces → surface}/cli/group/mcp.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Group
         class MCP < Group

data/lib/textus/{surfaces → surface}/cli/group/rule.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Group
         class Rule < Group

data/lib/textus/{surfaces → surface}/cli/group/schema.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Group
         class Schema < Group

data/lib/textus/{surfaces → surface}/cli/group.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Group < Verb
         class << self
@@ -7,7 +7,7 @@ module Textus
           # `parent_group` is this group counts as a subcommand. Sorted
           # alphabetically by command_name for stable help output.
           def subcommands
-            Textus::Surfaces::CLI::Runner.install!
+            Textus::Surface::CLI::Runner.install!
             Verb.descendants
                 .select { |k| k.parent_group == self && k.command_name }
                 .sort_by(&:command_name)

data/lib/textus/{surfaces → surface}/cli/runner.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       # Generates CLI::Verb (and CLI::Group) subclasses from per-verb contracts,
       # so the CLI surface is a projection of the contract — the operator-facing
@@ -49,63 +49,21 @@ module Textus
 
         module_function
 
-        # Build a Command from the spec + parsed inputs, dispatch through Gate.
         def dispatch(verb_instance, store, spec)
-          inputs = Textus::Contract::Binder.inputs_from_ordered(
+          inputs = Textus::Gate::Binder.inputs_from_ordered(
             spec, verb_instance.positional, verb_instance.flag_values(spec)
           )
-          inputs = inputs.merge(Textus::Contract::Sources.from_stdin(spec, verb_instance.stdin)) if spec.cli_stdin
-          inputs = Textus::Contract::Sources.acquire(spec, inputs)
+          inputs = inputs.merge(Surface::CLI::Sources.from_stdin(spec, verb_instance.stdin)) if spec.cli_stdin
+          inputs = Surface::CLI::Sources.acquire(spec, inputs)
           inputs = apply_cli_defaults(spec, inputs)
           role = verb_instance.resolved_role(store)
 
-          invoke = lambda do |effective_inputs|
-            cmd = build_command(spec, effective_inputs, role)
-            store.gate.dispatch(cmd)
-          end
-
-          result = if spec.around
-                     scope = store.as(role)
-                     Textus::Contract::Around.with(spec.around, scope: scope, inputs: inputs, session: nil, &invoke)
-                   else
-                     invoke.call(inputs)
-                   end
-          verb_instance.emit(shape(spec, result, inputs))
-        rescue Textus::Contract::MissingArgs => e
+          result = store.gate.dispatch(spec:, inputs:, role:, surface: :cli)
+          verb_instance.emit(result)
+        rescue Textus::Gate::MissingArgs => e
           raise UsageError.new("#{spec.cli_path} requires #{e.missing.first.wire}")
         end
 
-        def build_command(spec, inputs, role)
-          cmd_class = Textus::Gate::VERB_COMMAND.fetch(spec.verb) do
-            raise Textus::UsageError.new("no Command for verb: #{spec.verb}")
-          end
-          defaults = {}
-          spec.args.each do |a|
-            next if a.default == :__unset || inputs.key?(a.name)
-            next if a.default.nil? && a.required
-
-            defaults[a.name] = a.default
-          end
-          kwargs = defaults.merge(inputs)
-          kwargs[:role] = role if cmd_class.members.include?(:role) && !inputs.key?(:role) && spec.verb != :audit
-          check_missing_args!(spec, cmd_class, kwargs)
-
-          cmd_class.new(**kwargs.slice(*cmd_class.members))
-        end
-
-        def check_missing_args!(spec, cmd_class, kwargs)
-          params = cmd_class.instance_method(:initialize).parameters
-          required = if params == [[:rest]]
-                       cmd_class.members
-                     else
-                       params.select { |t,| t == :keyreq }.map(&:last)
-                     end
-          missing = required - kwargs.keys
-          return if missing.empty?
-
-          raise Textus::Contract::MissingArgs.new(spec, missing.map { |m| Struct.new(:wire, :name).new(m.to_s, m) })
-        end
-
         # Fill CLI-specific defaults (cli_default:) for args the operator did not
         # pass, where the CLI default diverges from the contract default the agent
         # surfaces use — e.g. migrate/data_mv apply by default on the CLI but plan
@@ -119,14 +77,6 @@ module Textus
           end
         end
 
-        # Shape the use-case result for the CLI wire via the verb's :cli view
-        # (falling back to the default view). The view is called uniformly as
-        # (result, inputs); an inputs-aware view echoes an input such as the key
-        # (ADR 0067).
-        def shape(spec, result, inputs)
-          Textus::Contract::View.render(spec, :cli, result, inputs)
-        end
-
         # The default the CLI flag is generated against — `cli_default:` when the
         # operator-facing default diverges from the contract default the agent
         # surfaces use, else the contract `default`. This drives boolean flag
@@ -151,6 +101,7 @@ module Textus
         def coerce(arg, raw)
           return effective_default(arg) != true if arg.type == :boolean
           return Integer(raw) if arg.type == Integer
+          return JSON.parse(raw) if arg.type == Hash
 
           raw
         end
@@ -193,11 +144,7 @@ module Textus
 
         def install!
           @installed ||= {}
-          Textus::Gate::ROUTES.each_key do |cmd_class|
-            verb = Textus::Gate::VERB_COMMAND.key(cmd_class)
-            next unless verb
-
-            action_class = Textus::Gate::ROUTES[cmd_class].first
+          Textus::Action::VERBS.each_value do |action_class|
             next unless action_class.respond_to?(:contract?) && action_class.contract?
 
             spec = action_class.contract
@@ -224,7 +171,7 @@ module Textus
           non_positional.each { |a| klass.option a.name, Runner.flagspec_for(a) }
 
           # Anchor the anonymous class to a constant so descendants discovery is
-          # stable. Name it after the verb under a Generated namespace.
+          # stable. Name it under a Generated namespace.
           const_name = spec.verb.to_s.split("_").map(&:capitalize).join
           gen = "Gen#{const_name}"
           Verb.const_set(gen, klass) unless Verb.const_defined?(gen, false)

data/lib/textus/surface/cli/sources.rb

@@ -0,0 +1,41 @@
+require "json"
+
+module Textus
+  module Surface
+    class CLI
+      # CLI-only input acquisition. Transforms entries of the uniform `inputs`
+      # hash that declare a `source:`/`coerce:`, and builds `inputs` from a
+      # `cli_stdin` envelope — so put/propose/migrate/rule_lint/audit need no
+      # hand-authored CLI class (ADR 0068). MCP receives typed JSON, so these
+      # never run there.
+      module Sources
+        module_function
+
+        # Apply per-arg :file sources (value is a path -> file contents) and
+        # :coerce callables to a by-name inputs hash. Returns a new hash.
+        def acquire(spec, inputs)
+          spec.args.each_with_object(inputs.dup) do |a, h|
+            next unless h.key?(a.name)
+
+            h[a.name] = File.read(h[a.name]) if a.source == :file
+            h[a.name] = a.coerce.call(h[a.name]) if a.coerce
+          end
+        end
+
+        # Parse a cli_stdin :json envelope into a by-name inputs hash, mapping
+        # envelope keys (wire-names) to arg names.
+        def from_stdin(spec, stream)
+          return {} unless spec.cli_stdin == :json
+
+          raw = stream.read.to_s
+          return {} if raw.strip.empty? # no envelope piped -> required args surface as missing
+
+          envelope = JSON.parse(raw)
+          spec.args.each_with_object({}) do |a, h|
+            h[a.name] = envelope[a.wire.to_s] if envelope.key?(a.wire.to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/{surfaces → surface}/cli/verb/doctor.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Verb
         class Doctor < Verb
@@ -7,11 +7,9 @@ module Textus
           option :checks, "--check=NAME"
 
           def call(store)
-            cmd = Textus::Command::Doctor.new(
-              checks: checks&.split(",")&.map(&:strip),
-              role: resolved_role(store),
-            )
-            res = store.gate.dispatch(cmd)
+            spec = Textus::Action::Doctor.contract
+            inputs = { checks: checks&.split(",")&.map(&:strip) }
+            res = store.gate.dispatch(spec: spec, inputs: inputs, role: resolved_role(store))
             emit(res, exit_code: res["ok"] ? 0 : 1)
           end
         end