textus 0.55.2 → 0.56.0

data/lib/textus/protocol/verb_registry/core_verbs.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Textus
+  module Protocol
+    module VerbRegistry
+      CoreVerbs = {
+        audit: VerbSpec.new(
+          :audit, "Query the audit log with optional filters.",
+          [ArgSpec.arg(name: :key, description: "filter to rows for this key"),
+           ArgSpec.arg(name: :lane, description: "filter to keys in this lane"),
+           ArgSpec.arg(name: :role, description: "filter to rows written under this role"),
+           ArgSpec.arg(name: :verb, description: "filter to rows for this verb"),
+           ArgSpec.arg(name: :since, description: "ISO-8601 timestamp or relative offset (e.g. 1h, 30m)"),
+           ArgSpec.arg(name: :seq_since, type: Integer, description: "return rows with seq > this cursor value"),
+           ArgSpec.arg(name: :correlation_id, description: "filter to rows with this correlation_id"),
+           ArgSpec.arg(name: :limit, type: Integer, description: "maximum number of rows to return")],
+          %i[cli mcp], :read
+        ),
+
+        blame: VerbSpec.new(
+          :blame, "Annotate audit rows with the git commit that introduced each file state.",
+          [ArgSpec.arg(name: :key, required: true, positional: true, description: "entry key to blame"),
+           ArgSpec.arg(name: :limit, type: Integer, description: "maximum number of audit rows to return")],
+          %i[cli mcp], :read
+        ),
+
+        boot: VerbSpec.new(
+          :boot, "Return the orientation contract: lanes, agent_quickstart, agent_protocol.",
+          [], %i[cli mcp], :read
+        ),
+
+        data_mv: VerbSpec.new(
+          :data_mv, "Rename a data lane — manifest + files. Refuses if destination exists.",
+          [ArgSpec.arg(name: :from, required: true, positional: true, description: "current data lane name"),
+           ArgSpec.arg(name: :to, required: true, positional: true, description: "new data lane name"),
+           ArgSpec.arg(name: :dry_run, type: :boolean, default: false,
+                       description: "when true, returns planned zone move without applying")],
+          %i[cli mcp], :write
+        ),
+
+        deps: VerbSpec.new(
+          :deps, "List the keys a derived entry depends on.",
+          [ArgSpec.arg(name: :key, required: true, positional: true, description: "dotted key of the derived entry whose source keys you want")],
+          %i[cli mcp], :read
+        ),
+
+        drain: VerbSpec.new(
+          :drain, "Seed materialize + sweep jobs then drain the queue to empty.",
+          [], %i[cli mcp], :maintenance
+        ),
+
+        get: VerbSpec.new(
+          :get, "Read one entry — on-disk read with freshness verdict.",
+          [ArgSpec.arg(name: :key, required: true, positional: true, description: "dotted entry key to read, e.g. 'knowledge.project'")],
+          %i[cli mcp], :read
+        ),
+
+        graph: VerbSpec.new(
+          :graph, "Query the link graph — neighbors (direct links) or reachable (transitive, with optional depth limit).",
+          [ArgSpec.arg(name: :key, required: true, positional: true, description: "entry key to query"),
+           ArgSpec.arg(name: :depth, type: Integer, description: "max traversal depth for reachable query (unlimited when omitted)")],
+          %i[cli mcp], :read
+        ),
+
+        ingest: VerbSpec.new(
+          verb: :ingest, summary: "Capture external source material into the raw lane. Write-once.",
+          args: [ArgSpec.arg(name: :kind, required: true, positional: true, description: "source kind: url | file | asset"),
+                 ArgSpec.arg(name: :slug, required: true, description: "human slug for the key suffix (kebab-case)"),
+                 ArgSpec.arg(name: :url, description: "remote URL (required when kind=url)"),
+                 ArgSpec.arg(name: :path, description: "local file path (required when kind=file or kind=asset)"),
+                 ArgSpec.arg(name: :lane, description: "asset group subdirectory (required when kind=asset)"),
+                 ArgSpec.arg(name: :label, description: "human label stored in source.label")],
+          surfaces: %i[cli mcp], category: :write, lane: :ingest
+        ),
+
+        key_delete: VerbSpec.new(
+          :key_delete, "Delete one entry by key. Returns {ok, key, deleted}.",
+          [ArgSpec.arg(name: :key, required: true, positional: true, description: "dotted entry key to delete"),
+           ArgSpec.arg(name: :if_etag, description: "optimistic-concurrency guard: etag you last read")],
+          %i[cli mcp], :write
+        ),
+
+        key_delete_prefix: VerbSpec.new(
+          :key_delete_prefix, "Bulk-delete every leaf key under prefix.",
+          [ArgSpec.arg(name: :prefix, required: true, positional: true, description: "every leaf key under this dotted prefix is deleted"),
+           ArgSpec.arg(name: :dry_run, type: :boolean, default: false,
+                       description: "when true, returns keys that would be deleted without deleting")],
+          %i[cli mcp], :write
+        ),
+
+        key_mv: VerbSpec.new(
+          :key_mv, "Rename one entry (same zone + format). Refuses if target exists.",
+          [ArgSpec.arg(name: :old_key, required: true, positional: true, description: "current dotted key"),
+           ArgSpec.arg(name: :new_key, required: true, positional: true, description: "new dotted key (same zone and format)"),
+           ArgSpec.arg(name: :dry_run, type: :boolean, description: "when true, returns planned move without applying")],
+          %i[cli mcp], :write
+        ),
+
+        key_mv_prefix: VerbSpec.new(
+          :key_mv_prefix, "Bulk-rename every leaf key under from_prefix to to_prefix.",
+          [ArgSpec.arg(name: :from_prefix, required: true, positional: true, description: "dotted prefix whose leaf keys are renamed"),
+           ArgSpec.arg(name: :to_prefix, required: true, positional: true, description: "dotted prefix the keys are renamed to"),
+           ArgSpec.arg(name: :dry_run, type: :boolean, default: false, description: "when true, returns planned moves without applying")],
+          %i[cli mcp], :write
+        ),
+
+        list: VerbSpec.new(
+          :list, "List keys filtered by lane and/or prefix.",
+          [ArgSpec.arg(name: :prefix, description: "restrict to keys starting with this dotted prefix, e.g. 'knowledge.execution'"),
+           ArgSpec.arg(name: :lane, description: "restrict to one lane by name (see `boot` lanes)"),
+           ArgSpec.arg(name: :q, description: "full-text search query over entry content (FTS5)"),
+           ArgSpec.arg(name: :schema, description: "filter to entries whose schema matches this name")],
+          %i[cli mcp], :read
+        ),
+
+        pulse: VerbSpec.new(
+          :pulse, "Delta since cursor — changed entries, pending proposals, index freshness.",
+          [ArgSpec.arg(name: :since, type: Integer, description: "audit seq to diff from; defaults to the session cursor")],
+          %i[cli mcp], :read
+        ),
+
+        put: VerbSpec.new(
+          :put, "Create or update an entry. Schema-validated. Returns {uid, etag}.",
+          [ArgSpec.arg(name: :key, required: true, positional: true, description: "dotted entry key, e.g. 'knowledge.project'; must resolve to a zone the role may write"),
+           ArgSpec.arg(name: :meta, type: Hash, wire_name: :_meta,
+                       description: "frontmatter; reads back as `_meta`. Schema-validated — call `schema KEY` first"),
+           ArgSpec.arg(name: :data, description: "unified payload — String for body (markdown/text), Hash for content (json/yaml)"),
+           ArgSpec.arg(name: :if_etag, description: "optimistic-concurrency guard; write rejected if entry changed since"),
+           ArgSpec.arg(name: :format, description: "override entry format for this write (e.g. script)")],
+          %i[cli mcp], :write
+        ),
+
+        rdeps: VerbSpec.new(
+          :rdeps, "List the derived entries that depend on a key (reverse deps).",
+          [ArgSpec.arg(name: :key, required: true, positional: true, description: "dotted key whose dependents you want")],
+          %i[cli mcp], :read
+        ),
+
+        schema_list: VerbSpec.new(
+          :schema_list, "List all registered schemas with their fields.",
+          [], %i[cli mcp], :read
+        ),
+
+        schema_show: VerbSpec.new(
+          :schema_show, "Return the schema (field shape) for an entry's family.",
+          [ArgSpec.arg(name: :key, required: true, positional: true, description: "any key in the family whose schema you want")],
+          %i[cli mcp], :read
+        ),
+
+        uid: VerbSpec.new(
+          :uid, "Return the stable UID of an entry without reading its body.",
+          [ArgSpec.arg(name: :key, required: true, positional: true, description: "entry key")],
+          %i[cli mcp], :read
+        ),
+
+        where: VerbSpec.new(
+          :where, "Resolve a key to its zone, owner, and path without reading the body.",
+          [ArgSpec.arg(name: :key, required: true, positional: true, description: "dotted key to locate")],
+          %i[cli mcp], :read
+        ),
+      }.freeze
+    end
+  end
+end

data/lib/textus/protocol/verb_registry/verb_spec.rb

@@ -0,0 +1,42 @@
+module Textus
+  module Protocol
+    module VerbRegistry
+      TYPE_MAP = {
+        String => "string", Integer => "integer", Hash => "object",
+        Array => "array", :boolean => "boolean"
+      }.freeze
+
+      SYSTEM_VERBS = %i[boot audit blame pulse drain workflow_spec].to_set.freeze
+
+      VerbSpec = Data.define(:verb, :summary, :args, :surfaces, :category) do
+        def initialize(verb:, summary:, args:, surfaces:, category:, lane: nil)
+          @lane = lane
+          super(verb:, summary:, args:, surfaces:, category:)
+        end
+
+        def lane = @lane
+        def system? = SYSTEM_VERBS.include?(verb)
+        def mcp? = surfaces.include?(:mcp)
+        def cli? = surfaces.include?(:cli)
+        def cli_path = verb.to_s.tr("_", " ")
+        def cli_words = cli_path.split
+        def cli_group = cli_words.size > 1 ? cli_words.first : nil
+        def cli_leaf  = cli_words.last
+        def required_args = args.select(&:required)
+        def read? = category == :read
+        def write? = category == :write
+        def maintenance? = category == :maintenance
+
+        def input_schema
+          props = args.to_h do |a|
+            json_type = VerbRegistry::TYPE_MAP[a.type] || "string"
+            h = { "type" => json_type }
+            h["description"] = a.description if a.description
+            [a.wire.to_s, h]
+          end
+          { type: "object", properties: props, required: required_args.map { |a| a.wire.to_s } }
+        end
+      end
+    end
+  end
+end

data/lib/textus/protocol/verb_registry.rb

@@ -0,0 +1,42 @@
+module Textus
+  module Protocol
+    module VerbRegistry
+      require_relative "verb_registry/arg_spec"
+      require_relative "verb_registry/verb_spec"
+
+      VERBS = {}
+      POSITIONAL = {}
+
+      def self.register(spec)
+        VERBS[spec.verb] = spec
+        POSITIONAL[spec.verb] = spec.args.select(&:positional).map(&:name)
+      end
+
+      def self.for(verb) = VERBS[verb]
+      def self.positional_for(verb) = POSITIONAL[verb] || []
+      def self.summary_for(verb) = VERBS[verb]&.summary
+      def self.registered = VERBS.values
+
+      ENTRY_VERBS = %i[
+        get put list key_delete key_mv propose accept reject
+        audit blame where uid deps rdeps graph diff ingest loop
+        session_open session_close
+      ].freeze
+
+      OPS_VERBS = %i[
+        boot drain pulse data_mv
+        key_mv_prefix key_delete_prefix
+      ].freeze
+
+      VERB_DOMAIN = ENTRY_VERBS.to_h { |v| [v, :entry] }
+                               .merge(OPS_VERBS.to_h { |v| [v, :ops] }).freeze
+
+      require_relative "verb_registry/core_verbs"
+      CoreVerbs.each_value { |spec| register(spec) }
+
+      require_relative "../lanes/knowledge/verbs"
+      require_relative "../lanes/scratchpad/verbs"
+      require_relative "../lanes/artifact/verbs"
+    end
+  end
+end

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

@@ -2,8 +2,8 @@ module Textus
   module Surface
     class CLI
       class Group
-        class Rule < Group
-          command_name "rule"
+        class Web < Group
+          command_name "web"
         end
       end
     end

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

@@ -13,7 +13,7 @@ module Textus
         # verb name — `spec.verb` remains the single source of dispatch.
         class Base < Verb
           class << self
-            attr_accessor :spec
+            attr_accessor :spec, :stdin_json
 
             # ADR 0064: derive the CLI command name from the contract's cli_leaf
             # when not set explicitly, so an escape-hatch class never restates its
@@ -50,19 +50,18 @@ module Textus
         module_function
 
         def dispatch(verb_instance, store, spec)
-          inputs = Textus::Dispatch::Binder.inputs_from_ordered(
+          inputs = Textus::Protocol::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
+          inputs = inputs.merge(Surface::CLI::Sources.from_stdin(spec, verb_instance.stdin)) if verb_instance.class.stdin_json
           inputs = Surface::CLI::Sources.acquire(spec, inputs)
           inputs = apply_cli_defaults(spec, inputs)
           role = verb_instance.resolved_role(store)
 
           s = store.with_role(role)
-          result = s.public_send(spec.verb, **inputs)
-          result = spec.view(:cli).call(result, inputs) if spec.view(:cli)
+          result = Textus::Surface::Dispatch.call(s, spec.verb, **inputs)
           verb_instance.emit(result)
-        rescue Textus::Dispatch::MissingArgs => e
+        rescue Textus::Protocol::MissingArgs => e
           raise UsageError.new("#{spec.cli_path} requires #{e.missing.first.wire}")
         end
 
@@ -93,7 +92,7 @@ module Textus
           if arg.type == :boolean
             effective_default(arg) == true ? "--no-#{wire}" : "--#{wire}"
           else
-            "--#{wire}=VALUE"
+            "--#{wire} VALUE"
           end
         end
 
@@ -128,16 +127,7 @@ module Textus
 
         # Contract verbs whose CLI is a plain `< Verb` command, not a projection at
         # all — composite reports assembled outside the contract.
-        # (boot removed: its contract carries surfaces :cli + the :lean arg, so the
-        # generic projection now generates it; the hand-authored CLI::Verb::Boot is
-        # deleted in ADR 0101.)
-        # (doctor retained: hand-authored to preserve --check=NAME flag spelling and
-        # the exit_code: res["ok"] ? 0 : 1 behavior — two things the generic
-        # projection cannot yet express; kept in ADR 0101 pending a future pass.)
-        # (fetch/fetch_all were removed in ADR 0079: Produce::Acquire::Intake is now internal,
-        # driven by the converge sweep (drain/serve) and hook run — ADR 0089 removed the
-        # read-through that once also drove it.)
-        NON_PROJECTED_CLI = %i[doctor].freeze
+        NON_PROJECTED_CLI = %i[].freeze
 
         # The installer skips generation for either category.
         HAND_AUTHORED_VERBS = (BEHAVIORAL_HATCHES + NON_PROJECTED_CLI).freeze
@@ -146,7 +136,7 @@ module Textus
 
         def install!
           @installed ||= {}
-          Textus::VerbRegistry.registered.each do |spec|
+          Textus::Protocol::VerbRegistry.registered.each do |spec|
             next unless spec.cli?
             next if hand_authored?(spec.verb)
             next if @installed[spec.verb]
@@ -156,17 +146,28 @@ module Textus
           end
         end
 
+        STDIN_VERBS = %i[propose].freeze
+        CLI_PATHS = {
+          uid: "key uid",
+          key_mv_prefix: "key mv-prefix",
+          key_delete_prefix: "key delete-prefix",
+        }.freeze
+
         def install_for(spec)
-          group = spec.cli_group ? ensure_group(spec.cli_group) : nil
-          leaf  = spec.cli_leaf
+          cli_path = CLI_PATHS[spec.verb] || spec.cli_path
+          cli_words = cli_path.split
+          group_name = cli_words.size > 1 ? cli_words.first : nil
+          group = group_name ? ensure_group(group_name) : nil
+          leaf = cli_words.last
           non_positional = spec.args.reject(&:positional)
 
           klass = Class.new(Base)
           klass.spec = spec
+          klass.stdin_json = STDIN_VERBS.include?(spec.verb)
           klass.command_name leaf
           klass.parent_group group if group
           klass.option :as_flag, "--as=ROLE"
-          klass.option :use_stdin, "--stdin" if spec.cli_stdin
+          klass.option :use_stdin, "--stdin" if klass.stdin_json
           non_positional.each { |a| klass.option a.name, Runner.flagspec_for(a) }
 
           # Anchor the anonymous class to a constant so descendants discovery is

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

@@ -25,10 +25,8 @@ module Textus
         # 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
+          return {} if raw.strip.empty?
 
           envelope = JSON.parse(raw)
           spec.args.each_with_object({}) do |a, h|

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

@@ -3,18 +3,13 @@ module Textus
     class CLI
       class Verb
         class Get < Runner::Base
-          self.spec = Textus::VerbRegistry.for(:get)
+          self.spec = Textus::Protocol::VerbRegistry.for(:get)
           option :as_flag, "--as=ROLE"
 
           def invoke(store)
             key = positional.shift or raise UsageError.new("get requires a key")
-            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)
+            emit(s.get(key: key))
           end
         end
       end

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

@@ -11,7 +11,7 @@ module Textus
 
           def call(_store)
             target = File.join(@cwd, ".textus")
-            emit(Textus::Init.run(target, with_agent: !!with_agent))
+            emit(Textus::Protocol::Init.run(target, with_agent: !!with_agent))
           end
         end
       end

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

@@ -3,22 +3,22 @@ module Textus
     class CLI
       class Verb
         class Put < Runner::Base
-          self.spec = Textus::VerbRegistry.for(:put)
+          self.spec = Textus::Protocol::VerbRegistry.for(:put)
           option :as_flag, "--as=ROLE"
           option :use_stdin, "--stdin"
+          option :as_format, "--as-format=FORMAT"
 
           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"] }
+            Textus::Protocol::VerbRegistry.for(:put)
+            inputs = { key: key, meta: payload["_meta"] || {}, data: payload["data"],
+                       if_etag: payload["if_etag"] }
+            inputs[:format] = as_format if as_format
             s = store.with_role(resolved_role(store))
-            result = s.put(**inputs)
-            result = spec.view(:cli).call(result, inputs) if spec.view(:cli)
-            emit(result)
+            emit(s.put(**inputs))
           end
         end
       end

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

@@ -0,0 +1,22 @@
+module Textus
+  module Surface
+    class CLI
+      class Verb
+        class WebServe < Verb
+          command_name "serve"
+          parent_group Group::Web
+          option :as_flag, "--as=ROLE"
+          option :port, "--port=N"
+
+          def call(store)
+            role = resolved_role(store, default: Textus::Value::Role::AGENT)
+            Textus::Surface::Web.set :textus_session, store.with_role(role)
+            Textus::Surface::Web.set :port, (port || 9292).to_i
+            Textus::Surface::Web.run!
+            0
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/surface/cli.rb

@@ -40,7 +40,7 @@ module Textus
         # `textus hook list --root=X`). Without this, `order!` below only sees
         # options before the first verb token, so a trailing `--root` reached the
         # verb's own parser and raised InvalidOption (#161 F5). TEXTUS_ROOT already
-        # works everywhere via Store.discover, so this brings the flag to parity.
+        # works everywhere via Session, so this brings the flag to parity.
         @root_arg = extract_root!(argv)
 
         # Define --version/--help ourselves so OptionParser doesn't intercept them
@@ -99,7 +99,29 @@ module Textus
       end
 
       def store
-        @store ||= Store.discover(@cwd, root: @root_arg)
+        @store ||= Textus::Protocol::Session.open(store_root)
+      end
+
+      def store_root
+        @store_root ||= explicit_root || discovered_root
+      end
+
+      def explicit_root
+        @root_arg || ENV.fetch("TEXTUS_ROOT", nil)
+      end
+
+      def discovered_root
+        dir = File.expand_path(@cwd)
+        loop do
+          if File.directory?(File.join(dir, ".textus")) && File.exist?(File.join(dir, ".textus", "manifest.yaml"))
+            return File.join(dir, ".textus")
+          end
+
+          parent = File.dirname(dir)
+          raise Textus::IoError.new("no .textus directory found from #{@cwd}") if parent == dir
+
+          dir = parent
+        end
       end
 
       def dispatch(klass, argv)
@@ -131,14 +153,11 @@ module Textus
             textus blame KEY [--limit=N]
             textus pulse [--since=N]
             textus boot
-            textus doctor
             textus drain [PREFIX] --as=ROLE
             textus watch
-            textus jobs
-
             textus key {delete,mv,mv-prefix,delete-prefix,uid}
             textus rule {explain,lint,list}
-            textus schema {diff,init,migrate,show}
+            textus schema {show}
             textus data {mv}
             textus mcp {serve}
         HELP

data/lib/textus/surface/dispatch.rb

@@ -0,0 +1,17 @@
+module Textus
+  module Surface
+    module Dispatch
+      module_function
+
+      def call(session, verb_name, raw_args = nil, **bound)
+        if raw_args
+          spec = Textus::Protocol::VerbRegistry.for(verb_name.to_sym)
+          raise Textus::UsageError.new("unknown verb: #{verb_name}") unless spec
+
+          bound = Textus::Protocol::Binder.inputs_from_wire(spec, raw_args)
+        end
+        session.public_send(verb_name.to_sym, **bound)
+      end
+    end
+  end
+end

data/lib/textus/surface/mcp/adapters/mcp_adapter.rb

@@ -0,0 +1,28 @@
+module Textus
+  module Surface
+    module MCP
+      module Adapters
+        class McpAdapter
+          def server(name:, version:, tools:, resources:, server_context:)
+            ::MCP::Server.new(
+              name: name,
+              version: version,
+              tools: tools,
+              resources: resources,
+              server_context: server_context,
+            )
+          end
+
+          def tool(name:, description:, input_schema:, &)
+            ::MCP::Tool.define(
+              name: name,
+              description: description,
+              input_schema: input_schema,
+              &
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -2,19 +2,19 @@ module Textus
   module Surface
     module MCP
       module Catalog
-        PROJECTOR = Projector.new(view_key: :default).freeze
+        MCP_ADAPTER = Textus::Surface::MCP::Adapters::McpAdapter.new
 
         module_function
 
         def specs
-          VerbRegistry.registered.select(&:mcp?)
+          Textus::Protocol::VerbRegistry.registered.select(&:mcp?)
         end
 
         def build_tools(mcp_server)
           specs.map do |spec|
             schema = spec.input_schema
             schema = schema.reject { |k, v| k == :required && Array(v).empty? }
-            ::MCP::Tool.define(
+            MCP_ADAPTER.tool(
               name: spec.verb.to_s,
               description: spec.summary,
               input_schema: schema,
@@ -29,23 +29,23 @@ module Textus
         end
 
         def read_verbs
-          VerbRegistry.registered
-                      .select { |s| s.read? && s.mcp? }
-                      .map { |s| s.verb.to_s }
+          Textus::Protocol::VerbRegistry.registered
+                                        .select { |s| s.read? && s.mcp? }
+                                        .map { |s| s.verb.to_s }
         end
 
         def write_verbs
-          VerbRegistry.registered
-                      .select { |s| s.write? && s.mcp? }
-                      .map { |s| s.verb.to_s }
+          Textus::Protocol::VerbRegistry.registered
+                                        .select { |s| s.write? && s.mcp? }
+                                        .map { |s| s.verb.to_s }
         end
 
         def call(name, store:, args:)
-          spec = VerbRegistry.for(name.to_sym)
+          spec = Textus::Protocol::VerbRegistry.for(name.to_sym)
           raise ToolError.new("unknown tool: #{name}") unless spec&.mcp?
 
-          PROJECTOR.dispatch(name, inputs: args, store:)
-        rescue Textus::Dispatch::MissingArgs => e
+          Textus::Surface::Dispatch.call(store, name.to_sym, args)
+        rescue Textus::Protocol::MissingArgs => e
           raise ToolError.new("#{name}: missing #{e.missing.map { |a| a.wire.to_s }.join(", ")}")
         rescue Textus::ContractDrift, Textus::CursorExpired
           raise

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

@@ -0,0 +1,22 @@
+module Textus
+  module Surface
+    module MCP
+      class CursorManager
+        def initialize(store:, role:)
+          @store = store
+          @role = role
+        end
+
+        def resume!
+          saved = @store.container.store.cursor_store.get(@role)[:seq]
+          latest = @store.container.store.audit_log.latest[:seq]
+          @store.advance_cursor(saved) if saved.positive? && saved <= latest
+        end
+
+        def advance!(seq:)
+          @store.advance_cursor(seq)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module Textus
+  module Surface
+    module MCP
+      module DriftAnnotation
+        module_function
+
+        def apply(result, verb_name:, drifted:, is_read:, current_etag:, previous_etag:)
+          result["contract_drifted"] = drifted if verb_name == :pulse
+
+          if drifted && !is_read && verb_name != :boot
+            result["_warning"] = "contract drifted (was #{previous_etag}, now #{current_etag}); call boot() to re-arm"
+          end
+
+          result
+        end
+      end
+    end
+  end
+end