textus 0.55.1 → 0.55.2

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

@@ -13,6 +13,11 @@ module Textus
           "proposal.rejected" => %w[materialize],
         }.freeze
 
+        ENTRY_LEVEL_TRIGGERS = %w[
+          entry.written entry.deleted entry.moved
+          proposal.accepted proposal.rejected
+        ].freeze
+
         SCOPE_RESOLVERS = {
           "materialize" => :producible_keys,
           "sweep" => :lane_keys,
@@ -37,21 +42,21 @@ module Textus
         end
 
         def plan(trigger:, role:)
-          type = trigger["type"] || trigger[:type]
-          trigger["target"] || trigger[:target]
+          type   = trigger["type"] || trigger[:type]
+          target = trigger["target"] || trigger[:target]
           return [] if type.nil?
 
           blocks_with_react = @manifest.rules.blocks.select(&:react)
           if blocks_with_react.any?
-            plan_from_rules(blocks_with_react, type, role)
+            plan_from_rules(blocks_with_react, type, role, target: target)
           else
-            plan_from_defaults(type, role)
+            plan_from_defaults(type, role, target: target)
           end
         end
 
         private
 
-        def plan_from_rules(blocks, type, role)
+        def plan_from_rules(blocks, type, role, target: nil) # rubocop:disable Lint/UnusedMethodArgument
           jobs = []
           blocks
             .select { |b| matches_trigger?(b.react, type) }
@@ -70,10 +75,13 @@ module Textus
           jobs
         end
 
-        def plan_from_defaults(type, role)
+        def plan_from_defaults(type, role, target: nil)
           actions = ACTIONS_BY_TRIGGER.fetch(type, [])
           jobs = []
-          producible_keys(nil).each { |k| jobs << job("materialize", k, role) } if actions.include?("materialize")
+          if actions.include?("materialize")
+            keys = target && ENTRY_LEVEL_TRIGGERS.include?(type) ? dependent_keys(target) : producible_keys(nil)
+            keys.each { |k| jobs << job("materialize", k, role) }
+          end
           GLOBAL_ACTIONS.each do |action, args|
             jobs << Textus::Store::Jobs::Queue::Job.new(type: action, args: args, role: role) if actions.include?(action)
           end
@@ -98,6 +106,18 @@ module Textus
         def lane_keys(_target)
           @manifest.data.entries.map(&:key)
         end
+
+        def dependent_keys(target_key)
+          @manifest.data.entries
+                   .select(&:external?)
+                   .select do |e|
+                     Array(e.source&.sources).compact.any? do |s|
+                       target_key == s || target_key.start_with?("#{s}.")
+                     end
+                   end
+                   .select { |e| !e.publish_tree.nil? || !e.publish_to.empty? }
+                   .map(&:key)
+        end
       end
     end
   end

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

@@ -44,11 +44,19 @@ module Textus
 
         def enqueue(job)
           now = iso_now
-          @store.execute(
+          inserted = @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],
           )
+          return inserted if @store.query_value("SELECT changes()")&.to_i&.positive?
+
+          @store.execute(
+            "UPDATE jobs
+               SET state = 'ready', role = ?, args = ?, attempts = 0, errors = ?, lease = NULL, max_attempts = ?, updated_at = ?
+             WHERE id = ? AND state IN ('done', 'failed')",
+            [job.role, JSON.dump(job.args), JSON.dump([]), job.max_attempts, now, job.id],
+          )
         end
 
         def ready_ids

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

@@ -0,0 +1,52 @@
+require "fileutils"
+
+module Textus
+  class Store
+    module Jobs
+      module Retention
+        class Base
+          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"]
+            dest = @container.layout.archive_path(src)
+            FileUtils.mkdir_p(File.dirname(dest))
+            FileUtils.cp(src, dest)
+          end
+
+          def delete(key)
+            mentry = @container.manifest.resolver.resolve(key).entry
+            writer = Textus::Store::Entry::Writer.from(container: @container, call: @call)
+            writer.delete(key, mentry: mentry)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+require "time"
+
+module Textus
+  class Store
+    module Jobs
+      module Retention
+        class Sweep
+          def self.expired?(ttl_seconds:, mtime:, now:)
+            return false if ttl_seconds.nil? || mtime.nil?
+
+            (now - mtime).to_i > ttl_seconds
+          end
+
+          def initialize(manifest:, file_stat:, clock:)
+            @manifest = manifest
+            @file_stat = file_stat
+            @clock = clock
+          end
+
+          def call(prefix: nil, lane: nil)
+            @manifest.data.entries
+                     .select { |m| matches?(m, prefix: prefix, lane: lane) }
+                     .flat_map { |m| rows_for(m) }
+          end
+
+          private
+
+          def matches?(mentry, prefix:, lane:)
+            return false if lane && mentry.lane != lane
+            return false if prefix && !Textus::Key::Matching.matches_prefix?(
+              mentry.key, prefix, nested: mentry.is_a?(Textus::Manifest::Entry::Nested)
+            )
+
+            true
+          end
+
+          def rows_for(mentry)
+            policy = @manifest.rules.for(mentry.key).retention
+            return [] if policy.nil?
+
+            @manifest.resolver.enumerate(prefix: mentry.key).filter_map do |row|
+              path = row[:path]
+              next unless @file_stat.exists?(path)
+              next unless self.class.expired?(
+                ttl_seconds: policy.ttl_seconds, mtime: @file_stat.mtime(path), now: @clock.now,
+              )
+
+              { "key" => row[:key], "path" => path, "action" => policy.action.to_s }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,49 +1,7 @@
-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
+      module Retention
       end
     end
   end

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

@@ -8,12 +8,12 @@ module Textus
         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(
+          rows = 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)
+          Retention::Base.new(container: container, call: call).call(rows)
         end
       end
     end

data/lib/textus/store/{geometry.rb → layout.rb}

@@ -1,6 +1,6 @@
 module Textus
   class Store
-    class Geometry
+    class Layout
       RUN    = ".state"
       DATA   = "data"
       ASSETS = "assets"
@@ -32,12 +32,28 @@ module Textus
       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_path(kind, date_str, zone, filename)
-        File.join(@root, ASSETS, kind, date_str, zone.to_s, filename)
+      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 --

data/lib/textus/store.rb

@@ -2,11 +2,8 @@ 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::Store::Container.attribute_names.each do |field|
       define_method(field) { @container.public_send(field) }
     end
@@ -42,58 +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::Store::Session.new(
-        role: role.to_s,
-        cursor: audit_log.latest_seq,
-        propose_lane: manifest.policy.propose_lane_for(role),
-        contract_etag: Textus::Value::Etag.for_contract(root),
-      )
+    def dry_run? = @dry_run
+
+    def with_role(new_role)
+      _rebuild(role: new_role)
     end
 
-    def gate
-      @container.gate
+    def with_correlation_id(cid)
+      _rebuild(correlation_id: cid)
     end
 
-    def as(role, dry_run: false, correlation_id: nil)
-      Textus::Surface::RoleScope.new(container: container, role: role, dry_run: dry_run, correlation_id: correlation_id)
+    def advance_cursor(new_cursor)
+      dup.tap do |s|
+        s.instance_variable_set(:@cursor, new_cursor)
+      end
+    end
+
+    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)
       job_store = Port::Store.new(root: root).setup!
-      geometry = Store::Geometry.new(root)
+      layout = Store::Layout.new(root)
       infra = Container::Infrastructure.new(
         file_store: Port::Storage::FileStore.new,
-        schemas: Schemas.new(geometry.schemas_dir),
+        schemas: Schema::Registry.new(layout.schemas_dir),
         audit_log: Port::AuditLog.new(
-          root,
+          layout: layout,
           max_size: manifest.data.audit_config[:max_size],
           keep: manifest.data.audit_config[:keep],
         ),
         job_store:,
-        geometry:,
+        layout:,
       )
 
-      coord = Container::Coordination.new(
+      coord_seed = Container::Coordination.new(
         manifest:,
         workflows: Workflow::Loader.load_all(root),
-        gate: nil,
-        compositor: nil,
+        pipeline: nil,
       )
 
-      container = Container.new(infra, coord)
-      compositor = Store::Compositor.new(container)
-      gate = Textus::Gate.new(container)
-      container.wire_gate!(gate, compositor)
+      Container.build(infra, coord_seed)
     end
   end
 end

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

@@ -50,7 +50,7 @@ module Textus
         module_function
 
         def dispatch(verb_instance, store, spec)
-          inputs = Textus::Gate::Binder.inputs_from_ordered(
+          inputs = Textus::Dispatch::Binder.inputs_from_ordered(
             spec, verb_instance.positional, verb_instance.flag_values(spec)
           )
           inputs = inputs.merge(Surface::CLI::Sources.from_stdin(spec, verb_instance.stdin)) if spec.cli_stdin
@@ -58,9 +58,11 @@ module Textus
           inputs = apply_cli_defaults(spec, inputs)
           role = verb_instance.resolved_role(store)
 
-          result = store.gate.dispatch(spec:, inputs:, role:, surface: :cli)
+          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::Gate::MissingArgs => e
+        rescue Textus::Dispatch::MissingArgs => e
           raise UsageError.new("#{spec.cli_path} requires #{e.missing.first.wire}")
         end
 
@@ -71,7 +73,7 @@ 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
@@ -83,7 +85,7 @@ module Textus
         # 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)
@@ -144,10 +146,7 @@ module Textus
 
         def install!
           @installed ||= {}
-          Textus::Action::VERBS.each_value do |action_class|
-            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]

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

@@ -7,9 +7,10 @@ module Textus
           option :checks, "--check=NAME"
 
           def call(store)
-            spec = Textus::Action::Doctor.contract
+            Textus::VerbRegistry.for(:doctor)
             inputs = { checks: checks&.split(",")&.map(&:strip) }
-            res = store.gate.dispatch(spec: spec, inputs: inputs, role: resolved_role(store))
+            s = store.with_role(resolved_role(store))
+            res = s.doctor(**inputs)
             emit(res, exit_code: res["ok"] ? 0 : 1)
           end
         end

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

@@ -3,13 +3,15 @@ module Textus
     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")
-            spec = Textus::Action::Get.contract
-            result = store.gate.dispatch(spec: spec, inputs: { key: key }, role: resolved_role(store), surface: :cli)
+            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)

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

@@ -3,7 +3,7 @@ module Textus
     class CLI
       class Verb
         class Put < Runner::Base
-          self.spec = Textus::Action::Put.contract
+          self.spec = Textus::VerbRegistry.for(:put)
           option :as_flag, "--as=ROLE"
           option :use_stdin, "--stdin"
 
@@ -12,10 +12,12 @@ module Textus
             raise UsageError.new("put requires --stdin in v1") unless use_stdin
 
             payload = JSON.parse(@stdin.read)
-            spec = Textus::Action::Put.contract
+            spec = Textus::VerbRegistry.for(:put)
             inputs = { key: key, meta: payload["_meta"] || {}, body: payload["body"] || "",
                        content: nil, if_etag: payload["if_etag"] }
-            result = store.gate.dispatch(spec: spec, inputs: inputs, role: resolved_role(store), surface: :cli)
+            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

data/lib/textus/surface/mcp/catalog.rb

@@ -1,89 +1,53 @@
 module Textus
   module Surface
     module MCP
-      # Derives the entire MCP tool surface from the per-verb contracts (ADR 0039).
-      # `build_tools` builds MCP::Tool instances for the SDK; `call` is the generic
-      # dispatch: map JSON args -> (positional, keyword) per the contract, invoke
-      # the verb through the role scope, then shape the return value. No per-tool code.
       module Catalog
-        PROJECTOR = Projector.new(view_key: :default, binder_method: :inputs_from_wire).freeze
+        PROJECTOR = Projector.new(view_key: :default).freeze
 
         module_function
 
-        WRITE_VERBS = %i[
-          put propose key_delete key_mv accept reject enqueue
-        ].freeze
-
-        MAINTENANCE_VERBS = %i[
-          data_mv key_mv_prefix key_delete_prefix drain rule_lint
-        ].freeze
-
-        # Contracts of every MCP-surfaced verb, in Dispatcher order.
         def specs
-          Textus::Action::VERBS.values
-                               .select { |k| mcp_surfaced?(k) }
-                               .map(&:contract)
+          VerbRegistry.registered.select(&:mcp?)
         end
 
-        # Builds MCP::Tool instances for the SDK, bound to mcp_server.dispatch.
         def build_tools(mcp_server)
-          Textus::Action::VERBS
-            .select { |_, klass| mcp_surfaced?(klass) }
-            .map do |name, action|
-              schema = action.contract.input_schema
-              schema = schema.reject { |k, v| k == :required && Array(v).empty? }
-              ::MCP::Tool.define(
-                name: name.to_s,
-                description: action.contract.summary,
-                input_schema: schema,
-              ) do |server_context:, **args|
-                mcp_server.dispatch(name, args, server_context)
-              end
+          specs.map do |spec|
+            schema = spec.input_schema
+            schema = schema.reject { |k, v| k == :required && Array(v).empty? }
+            ::MCP::Tool.define(
+              name: spec.verb.to_s,
+              description: spec.summary,
+              input_schema: schema,
+            ) do |server_context:, **args|
+              mcp_server.dispatch(spec.verb, args, server_context)
             end
+          end
         end
 
         def names
-          PROJECTOR.names(
-            Textus::Action::VERBS.select { |_, klass| mcp_surfaced?(klass) },
-          )
+          specs.map(&:verb).map(&:to_s)
         end
 
-        # MCP-surfaced read verbs, by Dispatcher class namespace — the agent's
-        # real read/discovery surface. `boot.agent_quickstart.read_verbs` derives
-        # from this so it can never advertise a verb the agent cannot call, nor
-        # omit one it can (ADR 0056). Excludes write/maintenance verbs by verb
-        # identity (routing may be legacy UseCases or Dispatch::Actions).
         def read_verbs
-          Textus::Action::VERBS
-            .reject { |verb, _klass| WRITE_VERBS.include?(verb) || MAINTENANCE_VERBS.include?(verb) }
-            .select { |_verb, klass| mcp_surfaced?(klass) }
-            .keys.map(&:to_s)
+          VerbRegistry.registered
+                      .select { |s| s.read? && s.mcp? }
+                      .map { |s| s.verb.to_s }
         end
 
-        # MCP-surfaced write verbs, by Dispatcher class namespace — the mirror of
-        # read_verbs for the write side. `boot.agent_quickstart.write_verbs` derives
-        # from this so it advertises bare verb names the agent can call (no `--as`/
-        # `--stdin` CLI framing), finishing the de-CLI-ing of the agent surface
-        # (ADR 0056, ADR 0057).
         def write_verbs
-          Textus::Action::VERBS
-            .select { |verb, klass| WRITE_VERBS.include?(verb) && mcp_surfaced?(klass) }
-            .keys.map(&:to_s)
-        end
-
-        def mcp_surfaced?(klass)
-          klass.respond_to?(:contract?) && klass.contract? && klass.contract.mcp?
+          VerbRegistry.registered
+                      .select { |s| s.write? && s.mcp? }
+                      .map { |s| s.verb.to_s }
         end
 
-        def call(name, session:, store:, args:)
-          klass = Textus::Action::VERBS[name.to_sym]
-          raise ToolError.new("unknown tool: #{name}") unless klass && mcp_surfaced?(klass)
+        def call(name, store:, args:)
+          spec = VerbRegistry.for(name.to_sym)
+          raise ToolError.new("unknown tool: #{name}") unless spec&.mcp?
 
-          PROJECTOR.dispatch(name, inputs: args, store:, role: session.role, session:)
-        rescue Textus::Gate::MissingArgs => e
-          spec = klass.contract
-          raise ToolError.new("#{spec.verb}: missing #{e.missing.map { |a| a.wire.to_s }.join(", ")}")
-        rescue Textus::ContractDrift, CursorExpired
+          PROJECTOR.dispatch(name, inputs: args, store:)
+        rescue Textus::Dispatch::MissingArgs => e
+          raise ToolError.new("#{name}: missing #{e.missing.map { |a| a.wire.to_s }.join(", ")}")
+        rescue Textus::ContractDrift, Textus::CursorExpired
           raise
         rescue Textus::Error => e
           raise ToolError.new("#{name}: #{e.message}")