textus 0.54.2 → 0.55.2

data/lib/textus/boot.rb

@@ -57,12 +57,8 @@ module Textus
       { "name" => "pulse" },
     ].freeze
 
-    # verb token => contract.summary, for every Dispatcher verb that carries a
-    # contract. The single source for a verb's one-line summary (ADR 0039).
     def self.contract_summaries
-      Textus::Action::VERBS.values
-                           .select { |k| k.respond_to?(:contract?) && k.contract? }
-                           .to_h { |k| [k.contract.verb.to_s, k.contract.summary] }
+      Textus::VerbRegistry.registered.to_h { |s| [s.verb.to_s, s.summary] }
     end
 
     # Build the CLI verb catalog: each summary is derived from its contract when
@@ -76,69 +72,70 @@ module Textus
       end
     end
 
-    def self.agent_quickstart(manifest, audit_log)
-      agent_role = manifest.policy.proposer_role
+    def self.build(container:)
+      etag       = Textus::Value::Etag.for_contract(container.root)
+      latest_seq = container.audit_log.latest_seq
+      artifact   = read_artifact_content(container, "artifacts.boot")
+      context    = read_boot_context(container)
+
+      # Prefer pre-computed artifact (drain computes, boot reads).
+      # Fall back to inline manifest projection for stores that have not yet
+      # run drain (test fixtures, fresh inits).
+      stable = artifact || inline_boot_content(container.manifest, latest_seq)
+
+      if stable["agent_quickstart"]
+        stable = stable.merge(
+          "agent_quickstart" => stable["agent_quickstart"].merge("latest_seq" => latest_seq),
+        )
+      end
+
+      payload = {
+        "protocol" => PROTOCOL_ID,
+        "store_root" => container.root,
+        "contract_etag" => etag,
+      }.merge(stable)
+      payload["context"] = context if context
+      payload
+    end
 
-      writable_lanes = manifest.data.declared_lane_kinds.keys.each_with_object([]) do |lane_name, acc|
+    def self.inline_boot_content(manifest, _latest_seq)
+      agent_role     = manifest.policy.proposer_role
+      writable_lanes = manifest.data.declared_lane_kinds.keys.each_with_object([]) do |ln, acc|
         next unless agent_role
 
-        verb = manifest.policy.verb_for_lane(lane_name)
+        verb    = manifest.policy.verb_for_lane(ln)
         writers = manifest.policy.roles_with_capability(verb)
-        acc << lane_name if writers.include?(agent_role)
+        acc << ln if writers.include?(agent_role)
       end
 
-      propose_lane = manifest.policy.propose_lane_for(agent_role)
-
-      {
-        "read_verbs" => Textus::Surfaces::MCP::Catalog.read_verbs,
-        "write_verbs" => agent_role ? Textus::Surfaces::MCP::Catalog.write_verbs : [],
-        "writable_lanes" => writable_lanes,
-        "propose_lane" => propose_lane,
-        "latest_seq" => audit_log.latest_seq,
-      }
-    end
-
-    def self.recipes(manifest)
-      queue = manifest.policy.queue_lane
-      feeds = lane_label(manifest, :machine, "the machine lane")
       {
-        "read" => {
-          "purpose" => "find and read an entry",
-          "steps" => [
-            "list (lane:, prefix:) — discover keys without reading bodies",
-            "get KEY — returns the entry envelope",
-          ],
-        },
-        "write" => {
-          "purpose" => "create or update an entry",
-          "steps" => [
-            "schema KEY — learn the _meta field shape (required, optional, field types) before writing",
-            "assemble an envelope: { _meta: {…}, body: \"…\" }",
-            "put KEY — persist it (role-gated); pass if_etag to guard a concurrent edit",
-          ],
-        },
-        "propose" => {
-          "purpose" => "agent suggests a change for human review",
-          "agent_steps" => [
-            "propose KEY — writes the change into the #{queue} lane for review",
-          ],
-          "human_steps" => [
-            "accept #{queue}.KEY — promotes the proposal into its target lane",
-          ],
-        },
-        "drain" => {
-          "purpose" => "keep the machine-maintained lanes fresh — re-pull stale intake entries from their declared source",
-          "steps" => [
-            "pulse — its `stale` list names entries past their ttl",
-            "drain (lane: #{feeds}) — re-pull the stale entries",
-          ],
+        "lanes" => lanes_for(manifest),
+        "agent_quickstart" => {
+          "read_verbs" => Textus::Surface::MCP::Catalog.read_verbs,
+          "write_verbs" => agent_role ? Textus::Surface::MCP::Catalog.write_verbs : [],
+          "writable_lanes" => writable_lanes,
+          "propose_lane" => manifest.policy.propose_lane_for(agent_role),
         },
+        "agent_protocol" => agent_protocol(manifest),
       }
     end
 
     def self.agent_protocol(manifest)
+      queue = manifest.policy.queue_lane
+      feeds = lane_label(manifest, :machine, "the machine lane")
       AGENT_PROTOCOL_TEMPLATE.merge(
-        "recipes" => recipes(manifest),
+        "recipes" => {
+          "read" => { "purpose" => "find and read an entry",
+                      "steps" => ["list (lane:, prefix:) — discover keys", "get KEY — returns the entry envelope"] },
+          "write" => { "purpose" => "create or update an entry",
+                       "steps" => ["schema KEY — learn field shape", "put KEY — persist it (role-gated)"] },
+          "propose" => { "purpose" => "agent suggests a change for human review",
+                         "agent_steps" => ["propose KEY — writes to #{queue} lane"],
+                         "human_steps" => ["accept #{queue}.KEY — promotes to target lane"] },
+          "drain" => { "purpose" => "keep machine lanes fresh",
+                       "steps" => ["pulse — stale list names overdue entries",
+                                   "drain (lane: #{feeds}) — re-pull stale entries"] },
+        },
         "role_resolution" => {
           "summary" => "write role is resolved in order: --as flag, TEXTUS_ROLE env var, .textus/role file, " \
                        "then a transport default ('human' for CLI, 'agent' for MCP)",
@@ -148,29 +145,23 @@ module Textus
       )
     end
 
-    def self.build(container:)
-      manifest = container.manifest
-      etag = Textus::Etag.for_contract(container.root)
-
-      {
-        "protocol" => PROTOCOL_ID,
-        "store_root" => container.root,
-        "contract_etag" => etag,
-        "lanes" => lanes_for(manifest),
-        "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
-        "orientation" => read_artifact_content(container, "artifacts.config.orientation"),
-        "context" => read_boot_context(container),
-        "index_key" => index_key_if_present(container),
-        "agent_protocol" => agent_protocol(manifest),
-      }.compact
+    def self.lanes_for(manifest)
+      manifest.data.declared_lane_kinds.keys.map do |name|
+        verb = manifest.policy.verb_for_lane(name)
+        row  = { "name" => name, "writers" => manifest.policy.roles_with_capability(verb) }
+        kind = manifest.policy.declared_kind(name)
+        row["kind"] = kind.to_s if kind
+        purpose = manifest.data.lane_descs[name]
+        row["purpose"] = purpose if purpose && !purpose.empty?
+        row
+      end
     end
 
     def self.read_artifact_content(container, key)
       res = container.manifest.resolver.resolve(key)
       return nil unless res.path && File.exist?(res.path)
 
-      call = Textus::Call.build(role: Textus::Role::DEFAULT)
-      env  = Textus::Action::Get.new(key: key).call(container: container, call: call)
+      env = Textus::Store::Entry::Reader.from(container: container).read(key)
       env&.content
     rescue Textus::Error
       nil
@@ -180,31 +171,11 @@ module Textus
       res = container.manifest.resolver.resolve("knowledge.boot")
       return nil unless res.path && File.exist?(res.path)
 
-      call = Textus::Call.build(role: Textus::Role::DEFAULT)
-      env  = Textus::Action::Get.new(key: "knowledge.boot").call(container: container, call: call)
+      env = Textus::Store::Entry::Reader.from(container: container).read("knowledge.boot")
       body = env&.body&.strip
       body.nil? || body.empty? ? nil : body
     rescue Textus::Error
       nil
     end
-
-    def self.index_key_if_present(container)
-      res = container.manifest.resolver.resolve("artifacts.system.index")
-      res.path && File.exist?(res.path) ? "artifacts.system.index" : nil
-    rescue Textus::Error
-      nil
-    end
-
-    def self.lanes_for(manifest)
-      manifest.data.declared_lane_kinds.keys.map do |name|
-        verb = manifest.policy.verb_for_lane(name)
-        row = { "name" => name, "writers" => manifest.policy.roles_with_capability(verb) }
-        kind = manifest.policy.declared_kind(name)
-        row["kind"] = kind.to_s if kind
-        purpose = manifest.data.lane_descs[name]
-        row["purpose"] = purpose if purpose && !purpose.empty?
-        row
-      end
-    end
   end
 end

data/lib/textus/dispatch/binder.rb

@@ -0,0 +1,48 @@
+module Textus
+  module Dispatch
+    class MissingArgs < Textus::Error
+      attr_reader :spec, :missing
+
+      def initialize(spec, missing)
+        @spec = spec
+        @missing = missing
+        super("missing_args", "#{spec.verb}: missing #{missing.map(&:wire).join(", ")}")
+      end
+    end
+
+    module Binder
+      Pending = Data.define(:spec, :inputs)
+
+      module_function
+
+      def command(spec, inputs)
+        Pending.new(spec: spec, inputs: inputs)
+      end
+
+      def bind(spec, inputs)
+        missing = spec.required_args.reject { |a| inputs.key?(a.name) }
+        raise MissingArgs.new(spec, missing) unless missing.empty?
+
+        spec.args.each_with_object({}) do |a, h|
+          if inputs.key?(a.name)
+            h[a.name] = inputs[a.name]
+          elsif !a.default.nil?
+            h[a.name] = a.default
+          end
+        end
+      end
+
+      def inputs_from_ordered(spec, ordered_positionals, by_name_keywords)
+        names = spec.args.select(&:positional).map(&:name)
+        names.zip(ordered_positionals).to_h.compact.merge(by_name_keywords)
+      end
+
+      def inputs_from_wire(spec, raw)
+        raw ||= {}
+        spec.args.each_with_object({}) do |a, h|
+          h[a.name] = raw[a.wire.to_s] if raw.key?(a.wire.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/textus/dispatch/contracts.rb

@@ -0,0 +1,63 @@
+module Textus
+  module Dispatch
+    module Contracts
+      GetEntry = Data.define(:key)
+
+      PutEntry = Data.define(:key, :meta, :body, :content, :if_etag)
+
+      ListKeys = Data.define(:prefix, :lane, :q, :schema)
+
+      DeleteKey = Data.define(:key, :if_etag)
+
+      MoveKey = Data.define(:old_key, :new_key, :if_etag, :dry_run)
+
+      ProposeEntry = Data.define(:key, :meta, :body, :content)
+
+      AcceptProposal = Data.define(:pending_key)
+
+      RejectProposal = Data.define(:pending_key)
+
+      EnqueueJob = Data.define(:type, :args)
+
+      AuditEntries = Data.define(:key, :lane, :role, :verb, :since, :seq_since, :correlation_id, :limit)
+
+      PulseEntries = Data.define(:since)
+
+      BlameEntry = Data.define(:key, :limit)
+
+      WhereEntry = Data.define(:key)
+
+      UidEntry = Data.define(:key)
+
+      DepsEntry = Data.define(:key)
+
+      RdepsEntry = Data.define(:key)
+
+      BootStore = Data.define
+
+      DoctorStore = Data.define(:checks)
+
+      PublishedEntries = Data.define
+
+      RuleExplain = Data.define(:key, :detail)
+
+      RuleList = Data.define
+
+      SchemaEnvelope = Data.define(:key)
+
+      DrainStore = Data.define(:prefix, :lane)
+
+      IngestEntry = Data.define(:kind, :slug, :url, :path, :lane, :label)
+
+      JobsAction = Data.define(:state, :action, :job_id)
+
+      RuleLint = Data.define(:candidate_yaml)
+
+      DataMv = Data.define(:from, :to, :dry_run)
+
+      KeyMvPrefix = Data.define(:from_prefix, :to_prefix, :dry_run)
+
+      KeyDeletePrefix = Data.define(:prefix, :dry_run)
+    end
+  end
+end

data/lib/textus/dispatch/handler_registry.rb

@@ -0,0 +1,21 @@
+module Textus
+  module Dispatch
+    class HandlerRegistry
+      def initialize
+        @handlers = {}
+      end
+
+      def register(command_class, handler)
+        @handlers[command_class] = handler
+      end
+
+      def for(command_class)
+        @handlers[command_class] || raise("no handler registered for #{command_class}")
+      end
+
+      def registered?(command_class)
+        @handlers.key?(command_class)
+      end
+    end
+  end
+end

data/lib/textus/dispatch/middleware/audit_index.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Textus
+  module Dispatch
+    module Middleware
+      # Shadows successful write operations into the SQLite audit_events table
+      # synchronously after dispatch, without the command knowing. Read verbs
+      # and failed writes pass through unchanged.
+      class AuditIndex < Base
+        middleware_name :audit_index
+
+        INDEXED_CONTRACTS = [
+          Contracts::PutEntry,
+          Contracts::DeleteKey,
+          Contracts::MoveKey,
+        ].freeze
+
+        def initialize(job_store:, audit_log:)
+          super()
+          @job_store = job_store
+          @audit_log = audit_log
+        end
+
+        def call(container:, command:, call:, next_handler:) # rubocop:disable Lint/UnusedMethodArgument
+          result = next_handler.call(command, call)
+          return result unless result.success? && INDEXED_CONTRACTS.include?(command.class)
+
+          key = command.respond_to?(:key) ? command.key : nil
+          return result unless key
+
+          seq = @audit_log.latest_seq
+          verb = command.class.name.split("::").last
+                        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                        .downcase
+
+          @job_store.insert_audit_event(
+            seq: seq,
+            ts: Time.now.utc.iso8601,
+            role: call.role,
+            verb: verb,
+            key: key,
+            etag_before: nil,
+            etag_after: result.value.is_a?(Hash) ? result.value["etag"] : nil,
+          )
+          result
+        end
+      end
+    end
+  end
+end

data/lib/textus/dispatch/middleware/auth.rb

@@ -0,0 +1,40 @@
+module Textus
+  module Dispatch
+    module Middleware
+      class Auth < Base
+        middleware_name :auth
+
+        def call(container:, command:, call:, next_handler:)
+          verb = VerbRegistry.contract_to_verb!(command.class).to_sym
+          key = key_for(command)
+
+          rule_preds = key ? rule_declared_predicates(verb, container.manifest, key) : []
+
+          Manifest::Policy::Predicates.evaluate(
+            manifest: container.manifest, schemas: container.schemas,
+            action: verb, actor: call.role, key: key,
+            rule_predicates: rule_preds
+          )
+
+          next_handler.call(command, call)
+        end
+
+        private
+
+        def rule_declared_predicates(verb, manifest, key)
+          guard_map = manifest.rules.for(key).guard
+          return [] if guard_map.nil?
+
+          Array(guard_map[verb.to_s])
+        end
+
+        def key_for(command)
+          if command.respond_to?(:key) then command.key
+          elsif command.respond_to?(:old_key) then command.old_key
+          elsif command.respond_to?(:pending_key) then command.pending_key
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/dispatch/middleware/base.rb

@@ -0,0 +1,26 @@
+module Textus
+  module Dispatch
+    module Middleware
+      class Base
+        def self.inherited(subclass)
+          super
+          subclass.instance_variable_set(:@middleware_name, nil)
+        end
+
+        class << self
+          def middleware_name(name = nil)
+            if name
+              @middleware_name = name.to_s
+            else
+              @middleware_name || name.split("::").last.downcase
+            end
+          end
+        end
+
+        def call(container:, command:, call:, next_handler:)
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/textus/dispatch/middleware/binder.rb

@@ -0,0 +1,20 @@
+module Textus
+  module Dispatch
+    module Middleware
+      class Binder < Base
+        middleware_name :binder
+
+        def call(container:, command:, call:, next_handler:) # rubocop:disable Lint/UnusedMethodArgument
+          return next_handler.call(command, call) unless command.is_a?(Dispatch::Binder::Pending)
+
+          spec = command.spec
+          contract_class = VerbRegistry.contract_class_for(spec.verb) or
+            raise Textus::UsageError.new("unknown command verb: #{spec.verb}")
+          resolved = Dispatch::Binder.bind(spec, command.inputs)
+          built = Dispatch::Pipeline.build_command(contract_class, resolved)
+          next_handler.call(built, call)
+        end
+      end
+    end
+  end
+end

data/lib/textus/dispatch/middleware/cascade.rb

@@ -0,0 +1,53 @@
+module Textus
+  module Dispatch
+    module Middleware
+      class Cascade < Base
+        middleware_name :cascade
+
+        CASCADE_VERBS = %i[put propose accept reject key_mv key_delete].freeze
+
+        TRIGGER_TYPE_MAP = {
+          Contracts::PutEntry => "entry.written",
+          Contracts::ProposeEntry => "entry.written",
+          Contracts::DeleteKey => "entry.deleted",
+          Contracts::MoveKey => "entry.moved",
+          Contracts::AcceptProposal => "proposal.accepted",
+          Contracts::RejectProposal => "proposal.rejected",
+        }.freeze
+
+        def call(container:, command:, call:, next_handler:)
+          result = next_handler.call(command, call)
+          return result unless result.success? && cascadable?(command)
+
+          key = cascade_key(command)
+          return result unless key
+
+          trigger_type = TRIGGER_TYPE_MAP[command.class]
+          jobs = Textus::Store::Jobs::Planner.new(container: container).plan(
+            trigger: { "type" => trigger_type, "target" => key },
+            role: call.role,
+          )
+          queue = Textus::Store::Jobs::Queue.new(store: container.job_store)
+          jobs.each { |j| queue.enqueue(j) }
+          result
+        end
+
+        private
+
+        def cascadable?(command)
+          CASCADE_VERBS.include?(VerbRegistry.contract_to_verb!(command.class).to_sym)
+        end
+
+        def cascade_key(command)
+          case command
+          when Contracts::PutEntry, Contracts::DeleteKey then command.key
+          when Contracts::MoveKey                        then command.new_key
+          when Contracts::AcceptProposal,
+               Contracts::RejectProposal                 then command.pending_key
+          when Contracts::ProposeEntry                   then command.key
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/dispatch/pipeline.rb

@@ -0,0 +1,35 @@
+module Textus
+  module Dispatch
+    class Pipeline
+      attr_reader :container
+
+      def initialize(registry:, container:, middleware: [])
+        @registry = registry
+        @middleware = middleware
+        @container = container
+      end
+
+      def dispatch(command, call:)
+        stack = @middleware.reverse.reduce(->(cmd, c) { execute(cmd, c) }) do |next_mw, mw|
+          ->(cmd, c) { mw.call(container: @container, command: cmd, call: c, next_handler: next_mw) }
+        end
+        stack.call(command, call)
+      end
+
+      def self.build_command(contract_class, inputs)
+        members = contract_class.members
+        kwargs = members.to_h do |member|
+          [member, inputs[member]]
+        end
+        contract_class.new(**kwargs)
+      end
+
+      private
+
+      def execute(command, call)
+        handler = @registry.for(command.class)
+        handler.call(command, call)
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/audit_log.rb

@@ -3,8 +3,8 @@ module Textus
     class Check
       class AuditLog < Check
         def call
-          path = Textus::Layout.audit_log(root)
-          Textus::Ports::AuditLog.new(root).verify_integrity.map do |v|
+          path = Textus::Store::Layout.new(root).audit_log_path
+          Textus::Port::AuditLog.new(root).verify_integrity.map do |v|
             {
               "code" => "audit.parse_error",
               "level" => "warning",

data/lib/textus/doctor/check/generator_drift.rb

@@ -8,12 +8,12 @@ module Textus
       # verb reported.
       class GeneratorDrift < Check
         def call
-          gen = Textus::Core::Freshness::Evaluator.new(
+          detector = Textus::Store::Freshness::DriftDetector.new(
             manifest: manifest,
-            file_stat: Textus::Ports::Storage::FileStat.new,
-            clock: Textus::Ports::Clock.new,
+            file_stat: Textus::Port::Storage::FileStat.new,
+            clock: Textus::Port::Clock.new,
           )
-          manifest.data.entries.flat_map { |m| gen.drift_rows(m) }.map do |row|
+          manifest.data.entries.flat_map { |m| detector.drift_rows(m) }.map do |row|
             {
               "code" => "generator_drift",
               "level" => "warning",

data/lib/textus/doctor/check/orphaned_publish_targets.rb

@@ -8,12 +8,12 @@ module Textus
       # that drift without making `build` scan globally.
       class OrphanedPublishTargets < Check
         def call
-          sdir = Textus::Layout.sentinels(root)
+          sdir = Textus::Store::Layout.new(root).sentinels_root
           return [] unless File.directory?(sdir)
 
           repo_root = File.dirname(root)
-          store = Textus::Ports::SentinelStore.new
-          glob = File.join(sdir, "**", "*#{Textus::Ports::SentinelStore::SUFFIX}")
+          store = Textus::Port::SentinelStore.new
+          glob = File.join(sdir, "**", "*#{Textus::Port::SentinelStore::SUFFIX}")
           Dir.glob(glob).filter_map do |spath|
             sentinel = store.load(spath, repo_root)
             next nil if sentinel.nil? || sentinel.source.nil?

data/lib/textus/doctor/check/protocol_version.rb

@@ -8,7 +8,7 @@ module Textus
       class ProtocolVersion < Check
         # Standalone interface: root is the project root (parent of .textus/).
         def self.run(root:)
-          path = File.join(root, ".textus/manifest.yaml")
+          path = File.join(root, ".textus", "manifest.yaml")
           return [] unless File.exist?(path)
 
           doc = YAML.safe_load_file(path, aliases: false) || {}
@@ -26,7 +26,7 @@ module Textus
         # Doctor check interface: root is the .textus/ directory itself,
         # so manifest.yaml lives directly inside it.
         def call
-          path = File.join(root, "manifest.yaml")
+          path = geometry.manifest_path
           return [] unless File.exist?(path)
 
           doc = YAML.safe_load_file(path, aliases: false) || {}

data/lib/textus/doctor/check/raw_asset_paths.rb

@@ -42,7 +42,7 @@ module Textus
         end
 
         def find_asset_path(asset_rel)
-          File.join(root, "assets", asset_rel)
+          File.join(geometry.root, "assets", asset_rel)
         end
       end
     end

data/lib/textus/doctor/check/schema_parse_error.rb

@@ -7,7 +7,7 @@ module Textus
       # leaving the operator with no signal that a schema is broken.
       class SchemaParseError < Check
         def call
-          dir = File.join(root, "schemas")
+          dir = geometry.schemas_dir
           return [] unless File.directory?(dir)
 
           Dir.glob(File.join(dir, "*.yaml")).each_with_object([]) do |path, out|

data/lib/textus/doctor/check/schema_violations.rb

@@ -4,11 +4,11 @@ module Textus
       class SchemaViolations < Check
         def call
           result = Textus::Doctor::Validator.new(
-            reader: ->(key, ctnr, c) { Textus::Action::Get.new(key: key).call(container: ctnr, call: c) },
+            reader: ->(key, ctnr, _c) { Textus::Store::Entry::Reader.from(container: ctnr).read(key) },
             manifest: @container.manifest,
             audit_log: @container.audit_log,
             schema_for: ->(name) { @container.schemas.fetch_or_nil(name) },
-          ).call(container: @container, call: Textus::Call.build(role: Textus::Role::DEFAULT))
+          ).call(container: @container, call: Textus::Value::Call.build(role: Textus::Value::Role::DEFAULT))
 
           result["violations"].map do |v|
             fix = v["expected"] &&