textus 0.54.2 → 0.55.2

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

@@ -0,0 +1,8 @@
+module Textus
+  class Store
+    module Jobs
+      module Retention
+      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 = Retention::Sweep.new(
+            manifest: container.manifest,
+            file_stat: Textus::Port::Storage::FileStat.new,
+            clock: Textus::Port::Clock.new,
+          ).call(prefix: prefix, lane: lane)
+          Retention::Base.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/layout.rb

@@ -0,0 +1,97 @@
+module Textus
+  class Store
+    class Layout
+      RUN    = ".state"
+      DATA   = "data"
+      ASSETS = "assets"
+
+      def initialize(root)
+        @root = root
+        freeze
+      end
+
+      attr_reader :root
+
+      # -- data paths --
+      def data_root = File.join(@root, DATA)
+      def lane_path(lane_name) = File.join(data_root, lane_name.to_s)
+
+      def entry_path(mentry)
+        primary_ext = Format.for(mentry.format).extensions.first
+        rel = normalize_relative_path(mentry.path)
+        if File.extname(mentry.path) == ""
+          File.join(@root, rel + primary_ext)
+        else
+          File.join(@root, rel)
+        end
+      end
+
+      # -- runtime paths --
+      def run_root           = File.join(@root, RUN)
+      def cursor_path(role)  = File.join(run_root, "ephemeral", "cursors", role.to_s)
+      def lock_path(name)    = File.join(run_root, "ephemeral", "locks", "#{name}.lock")
+      def audit_dir_path     = File.join(run_root, "audit")
+      def audit_log_path     = File.join(audit_dir_path, "audit.log")
+      def audit_rotated_log_path(n) = File.join(audit_dir_path, "audit.log.#{n}")
+      def audit_rotated_meta_path(n) = File.join(audit_dir_path, "audit.log.#{n}.meta.json")
+      def audit_log_glob = File.join(audit_dir_path, "audit.log.*")
+      def sentinels_root = File.join(run_root, "tracking", "sentinels")
+      def store_db_path = File.join(run_root, "store.db")
+
+      # -- asset paths --
+      def asset_raw_dir(date_path, zone)
+        File.join(@root, ASSETS, "raw", date_path, zone.to_s)
+      end
+
+      def asset_sentinel_path
+        File.join(@root, ASSETS, ".gitignore")
+      end
+
+      def asset_resolve(rel_path)
+        File.join(@root, ASSETS, rel_path)
+      end
+
+      def archive_path(source_path)
+        rel = source_path.delete_prefix("#{@root}/")
+        File.join(@root, "archive", rel)
+      end
+
+      # -- config paths --
+      def manifest_path = File.join(@root, "manifest.yaml")
+      def schemas_dir = File.join(@root, "schemas")
+      def schema_path(name) = File.join(schemas_dir, "#{name}.yaml")
+      def template_path(name) = File.join(@root, "templates", name)
+      def workflow_dir     = File.join(@root, "workflows")
+      def hooks_dir        = File.join(@root, "hooks")
+      def schemas_glob     = File.join(schemas_dir, "**", "*")
+
+      # -- gitignore --
+      def gitignore_body(untracked_entries: [])
+        lines = ["# textus runtime artifacts — safe to delete, never commit",
+                 "#{RUN}/"]
+        unless untracked_entries.empty?
+          lines << "# tracked:false entries — protocol-readable, not committed"
+          lines.concat(untracked_entries)
+        end
+        "#{lines.join("\n")}\n"
+      end
+
+      # -- lane boundary (replaces Writer#zone_floor) --
+      def lane_floor(path)
+        prefix = "#{data_root}/"
+        return nil unless path.start_with?(prefix)
+
+        seg = path.delete_prefix(prefix).split("/").first
+        seg && File.join(data_root, seg)
+      end
+
+      private
+
+      def normalize_relative_path(path)
+        return path if path.start_with?("data/")
+
+        File.join("data", path)
+      end
+    end
+  end
+end

data/lib/textus/store.rb

@@ -2,12 +2,9 @@ require "fileutils"
 
 module Textus
   class Store
-    attr_reader :container
+    attr_reader :container, :role, :correlation_id, :cursor, :propose_lane, :contract_etag
 
-    # 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
 
@@ -42,50 +39,84 @@ module Textus
       File.directory?(dir) && File.exist?(File.join(dir, "manifest.yaml"))
     end
 
-    def initialize(root)
-      @container = build_container(File.expand_path(root))
+    def initialize(root, role: Value::Role::DEFAULT, correlation_id: nil, dry_run: false, container: nil)
+      @root = File.expand_path(root)
+      @container = container || build_container(@root)
+      @role = role.to_s
+      @correlation_id = correlation_id || SecureRandom.uuid
+      @dry_run = dry_run
+      build_session!
     end
 
-    # 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(
-        role: role.to_s,
-        cursor: audit_log.latest_seq,
-        propose_lane: manifest.policy.propose_lane_for(role),
-        contract_etag: Textus::Etag.for_contract(root),
-      )
+    def dry_run? = @dry_run
+
+    def with_role(new_role)
+      _rebuild(role: new_role)
+    end
+
+    def with_correlation_id(cid)
+      _rebuild(correlation_id: cid)
     end
 
-    def gate
-      @container.gate
+    def advance_cursor(new_cursor)
+      dup.tap do |s|
+        s.instance_variable_set(:@cursor, new_cursor)
+      end
     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)
+    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
 
+    def _rebuild(role: @role, correlation_id: @correlation_id, dry_run: @dry_run)
+      self.class.allocate.tap do |s|
+        s.instance_variable_set(:@root, @root)
+        s.instance_variable_set(:@container, @container)
+        s.instance_variable_set(:@role, role.to_s)
+        s.instance_variable_set(:@correlation_id, correlation_id || SecureRandom.uuid)
+        s.instance_variable_set(:@dry_run, dry_run)
+        s.send(:build_session!)
+      end
+    end
+
+    def build_session!
+      @cursor = @container.audit_log.latest_seq
+      @propose_lane = @container.manifest.policy.propose_lane_for(@role)
+      @contract_etag = Value::Etag.for_contract(@root)
+    end
+
+    def short_etag(etag) = etag.to_s.delete_prefix("sha256:")[0, 8]
+
     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(
-          root,
+      job_store = Port::Store.new(root: root).setup!
+      layout = Store::Layout.new(root)
+      infra = Container::Infrastructure.new(
+        file_store: Port::Storage::FileStore.new,
+        schemas: Schema::Registry.new(layout.schemas_dir),
+        audit_log: Port::AuditLog.new(
+          layout: layout,
           max_size: manifest.data.audit_config[:max_size],
           keep: manifest.data.audit_config[:keep],
         ),
+        job_store:,
+        layout:,
+      )
+
+      coord_seed = Container::Coordination.new(
+        manifest:,
         workflows: Workflow::Loader.load_all(root),
-        gate: nil,
+        pipeline: nil,
       )
-      gate = Textus::Gate.new(container)
-      container = container.with(gate: gate)
-      gate.instance_variable_set(:@container, container)
-      container
+
+      Container.build(infra, coord_seed)
     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,23 @@ 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::Dispatch::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
+          s = store.with_role(role)
+          result = s.public_send(spec.verb, **inputs)
+          result = spec.view(:cli).call(result, inputs) if spec.view(:cli)
+          verb_instance.emit(result)
+        rescue Textus::Dispatch::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
@@ -113,27 +73,19 @@ module Textus
         # contract, not hidden in a hand class.
         def apply_cli_defaults(spec, inputs)
           spec.args.each_with_object(inputs.dup) do |a, h|
-            next if a.cli_default == :__unset || h.key?(a.name)
+            next if a.cli_default.nil? || h.key?(a.name)
 
             h[a.name] = a.cli_default
           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
         # polarity so a verb that applies-by-default on the CLI but plans-by-default
         # for agents (migrate, data_mv) gets a `--dry-run` flag, not `--no-dry-run`.
         def effective_default(arg)
-          arg.cli_default == :__unset ? arg.default : arg.cli_default
+          arg.cli_default.nil? ? arg.default : arg.cli_default
         end
 
         def flagspec_for(arg)
@@ -151,6 +103,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,14 +146,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
-            next unless action_class.respond_to?(:contract?) && action_class.contract?
-
-            spec = action_class.contract
+          Textus::VerbRegistry.registered.each do |spec|
             next unless spec.cli?
             next if hand_authored?(spec.verb)
             next if @installed[spec.verb]
@@ -224,7 +170,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,10 @@ 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)
+            Textus::VerbRegistry.for(:doctor)
+            inputs = { checks: checks&.split(",")&.map(&:strip) }
+            s = store.with_role(resolved_role(store))
+            res = s.doctor(**inputs)
             emit(res, exit_code: res["ok"] ? 0 : 1)
           end
         end

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

@@ -1,18 +1,20 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Verb
         class Get < Runner::Base
-          self.spec = Textus::Action::Get.contract
+          self.spec = Textus::VerbRegistry.for(:get)
           option :as_flag, "--as=ROLE"
 
           def invoke(store)
             key = positional.shift or raise UsageError.new("get requires a key")
-            cmd = Textus::Command::Get.new(key: key, role: resolved_role(store))
-            result = store.gate.dispatch(cmd)
+            spec = Textus::VerbRegistry.for(:get)
+            s = store.with_role(resolved_role(store))
+            result = s.get(key: key)
+            result = spec.view(:cli).call(result, { key: key }) if spec.view(:cli)
             raise Textus::UnknownKey.new(key, suggestions: store.manifest.resolver.suggestions_for(key)) if result.nil?
 
-            emit(result.to_h_for_wire)
+            emit(result)
           end
         end
       end

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

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Verb
         class Init < Verb

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

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Verb
         # Launches the MCP stdio server in the current process. Blocks on stdin;
@@ -13,8 +13,8 @@ module Textus
           option :as_flag, "--as=ROLE"
 
           def call(store)
-            role = resolved_role(store, default: Textus::Role::AGENT)
-            Textus::Surfaces::MCP::Server.new(store: store, stdin: @stdin, stdout: @stdout, role: role).run
+            role = resolved_role(store, default: Textus::Value::Role::AGENT)
+            Textus::Surface::MCP::Server.new(store: store, stdin: @stdin, stdout: @stdout, role: role).run
             0
           end
         end

data/lib/textus/surface/cli/verb/put.rb

@@ -0,0 +1,27 @@
+module Textus
+  module Surface
+    class CLI
+      class Verb
+        class Put < Runner::Base
+          self.spec = Textus::VerbRegistry.for(:put)
+          option :as_flag, "--as=ROLE"
+          option :use_stdin, "--stdin"
+
+          def invoke(store)
+            key = positional.shift or raise UsageError.new("put requires a key")
+            raise UsageError.new("put requires --stdin in v1") unless use_stdin
+
+            payload = JSON.parse(@stdin.read)
+            spec = Textus::VerbRegistry.for(:put)
+            inputs = { key: key, meta: payload["_meta"] || {}, body: payload["body"] || "",
+                       content: nil, if_etag: payload["if_etag"] }
+            s = store.with_role(resolved_role(store))
+            result = s.put(**inputs)
+            result = spec.view(:cli).call(result, inputs) if spec.view(:cli)
+            emit(result)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,5 +1,5 @@
 module Textus
-  module Surfaces
+  module Surface
     class CLI
       class Verb
         class SchemaDiff < Verb