textus 0.35.1 → 0.38.0

data/lib/textus/layout.rb

@@ -0,0 +1,41 @@
+module Textus
+  # Single source of truth for every path textus owns under a store root.
+  # All disposable runtime state nests under <root>/.run/ so the
+  # tracked/disposable boundary is a directory boundary. ADR 0038.
+  module Layout
+    RUN = ".run"
+
+    def self.run(root)
+      File.join(root, RUN)
+    end
+
+    def self.state(root)
+      File.join(run(root), "state")
+    end
+
+    def self.cursor(root, role)
+      File.join(state(root), "cursor.#{role}")
+    end
+
+    def self.locks(root)
+      File.join(run(root), "locks")
+    end
+
+    def self.build_lock(root)
+      File.join(run(root), "build.lock")
+    end
+
+    def self.audit_dir(root)
+      File.join(run(root), "audit")
+    end
+
+    def self.audit_log(root)
+      File.join(audit_dir(root), "audit.log")
+    end
+
+    GITIGNORE = <<~GITIGNORE
+      # textus runtime artifacts — safe to delete, never commit
+      #{RUN}/
+    GITIGNORE
+  end
+end

data/lib/textus/maintenance/key_delete_prefix.rb

@@ -2,6 +2,15 @@ module Textus
   module Maintenance
     # Bulk-delete every leaf key under `prefix`.
     class KeyDeletePrefix
+      extend Textus::Contract::DSL
+
+      verb     :key_delete_prefix
+      summary  "Bulk-delete every leaf key under prefix."
+      surfaces :cli, :ruby, :mcp
+      arg :prefix,  String, required: true
+      arg :dry_run, :boolean
+      response(&:to_h)
+
       def initialize(container:, call:)
         @container    = container
         @call         = call

data/lib/textus/maintenance/key_mv_prefix.rb

@@ -3,6 +3,16 @@ module Textus
     # Bulk-rename every leaf key under `from_prefix` to `to_prefix`.
     # Calls Write::Mv directly for each entry — emits one audit row per file moved.
     class KeyMvPrefix
+      extend Textus::Contract::DSL
+
+      verb     :key_mv_prefix
+      summary  "Bulk-rename every leaf key under from_prefix to to_prefix. Dry-run returns a Plan; apply with dry_run: false."
+      surfaces :cli, :ruby, :mcp
+      arg :from_prefix, String, required: true
+      arg :to_prefix,   String, required: true
+      arg :dry_run,     :boolean
+      response(&:to_h)
+
       def initialize(container:, call:)
         @container    = container
         @call         = call

data/lib/textus/maintenance/migrate.rb

@@ -5,6 +5,15 @@ module Textus
     # Loads a YAML migration plan and dispatches each op to the
     # appropriate Maintenance use case. Concatenates resulting Plans.
     class Migrate
+      extend Textus::Contract::DSL
+
+      verb     :migrate
+      summary  "Run a YAML migration plan (multi-op)."
+      surfaces :cli, :ruby, :mcp
+      arg :plan_yaml, String, required: true
+      arg :dry_run,   :boolean
+      response(&:to_h)
+
       def initialize(container:, call:)
         @container    = container
         @call         = call

data/lib/textus/maintenance/rule_lint.rb

@@ -6,6 +6,14 @@ module Textus
     # YAML string. Returns a Plan describing rule additions/removals/
     # changes. Does NOT write anything.
     class RuleLint
+      extend Textus::Contract::DSL
+
+      verb     :rule_lint
+      summary  "Diff candidate manifest YAML's rules against the live manifest. No writes."
+      surfaces :cli, :ruby, :mcp
+      arg :candidate_yaml, String, required: true
+      response(&:to_h)
+
       def initialize(container:, call:)
         @container = container
         @call      = call

data/lib/textus/maintenance/zone_mv.rb

@@ -6,6 +6,16 @@ module Textus
     # the `zone:` field on every entry under the old zone, and moves
     # every file from zones/<old>/ to zones/<new>/.
     class ZoneMv
+      extend Textus::Contract::DSL
+
+      verb     :zone_mv
+      summary  "Rename a zone — manifest + files. Refuses if destination exists."
+      surfaces :cli, :ruby, :mcp
+      arg :from,    String, required: true
+      arg :to,      String, required: true
+      arg :dry_run, :boolean
+      response(&:to_h)
+
       def initialize(container:, call:)
         @container = container
         @call      = call

data/lib/textus/mcp/catalog.rb

@@ -0,0 +1,72 @@
+module Textus
+  module MCP
+    # Derives the entire MCP tool surface from the per-verb contracts
+    # (ADR 0039). `tool_schemas` feeds tools/list; `call` is the generic
+    # tools/call dispatch: map JSON args -> (positional, keyword) per the
+    # contract, invoke the verb through the role scope, then shape the
+    # return value with the contract's response block. No per-tool code.
+    module Catalog
+      module_function
+
+      # Contracts of every MCP-surfaced verb, in Dispatcher order.
+      def specs
+        Textus::Dispatcher::VERBS.values
+                                 .select { |k| k.respond_to?(:contract?) && k.contract? && k.contract.mcp? }
+                                 .map(&:contract)
+      end
+
+      def tool_schemas
+        specs.map do |s|
+          { name: s.verb.to_s, description: s.summary, inputSchema: s.input_schema }
+        end.freeze
+      end
+
+      def names
+        specs.map { |s| s.verb.to_s }
+      end
+
+      def call(name, session:, store:, args:)
+        klass = Textus::Dispatcher::VERBS[name.to_sym]
+        raise ToolError.new("unknown tool: #{name}") unless klass.respond_to?(:contract?) && klass.contract? && klass.contract.mcp?
+
+        spec = klass.contract
+        pos, kw = map_args(spec, args || {}, session)
+        result = store.as(session.role).public_send(spec.verb, *pos, **kw)
+        spec.response.call(result)
+      rescue ContractDrift, CursorExpired
+        raise
+      rescue Textus::Error => e
+        raise ToolError.new("#{name}: #{e.message}")
+      end
+
+      # Splits the raw JSON arg hash into the positional list and keyword hash
+      # the use-case expects, validating required presence first.
+      # Session-default args (session_default: :method_name) are injected from
+      # the session when absent from the wire; they are never treated as missing.
+      # Positional args are emitted in contract declaration order; use-case signatures must match.
+      def map_args(spec, raw, session = nil)
+        missing = spec.required_args.map { |a| a.name.to_s } - raw.keys
+        raise ToolError.new("#{spec.verb}: missing #{missing.join(", ")}") unless missing.empty?
+
+        positional = []
+        keyword = {}
+        spec.args.each do |a|
+          if raw.key?(a.name.to_s)
+            value = raw[a.name.to_s]
+          elsif a.session_default && session
+            value = session.public_send(a.session_default)
+          else
+            next
+          end
+
+          if a.positional
+            positional << value
+          else
+            keyword[a.name] = value
+          end
+        end
+        [positional, keyword]
+      end
+    end
+  end
+end

data/lib/textus/mcp/server.rb

@@ -49,8 +49,11 @@ module Textus
       end
 
       def handle_initialize(rid, _params)
-        proposer = @store.manifest.policy.proposer_role
-        propose_zone = @store.manifest.policy.propose_zone_for(proposer)
+        # The acting role IS the resolved connection role (ADR 0040): the MCP
+        # transport defaults to `agent`, which can write the queue, so its
+        # propose_zone resolves directly. If a connection's role cannot propose,
+        # propose_zone is nil and the `propose` tool reports that honestly.
+        propose_zone = @store.manifest.policy.propose_zone_for(@role)
 
         @session = Session.new(
           role: @role,
@@ -67,7 +70,7 @@ module Textus
       end
 
       def handle_tools_list(rid)
-        emit_result(rid, { "tools" => ToolSchemas.all })
+        emit_result(rid, { "tools" => Catalog.tool_schemas })
       end
 
       def handle_tools_call(rid, params)
@@ -80,8 +83,8 @@ module Textus
 
         name = params["name"]
         args = params["arguments"] || {}
-        result = Tools.call(name, session: @session, store: @store, args: args)
-        @session = @session.advance_cursor(@store.audit_log.latest_seq) if name == "tick"
+        result = Catalog.call(name, session: @session, store: @store, args: args)
+        @session = @session.advance_cursor(@store.audit_log.latest_seq) if name == "pulse"
 
         emit_result(rid, {
                       "content" => [{ "type" => "text", "text" => JSON.dump(result) }],

data/lib/textus/mcp/session.rb

@@ -1,24 +1,7 @@
 module Textus
   module MCP
-    # Per-connection state held by the server. Immutable Data value;
-    # advance_cursor returns a new instance via #with.
-    Session = Data.define(:role, :cursor, :propose_zone, :manifest_etag) do
-      def advance_cursor(new_cursor) = with(cursor: new_cursor)
-
-      def check_etag!(observed_etag)
-        return if observed_etag == manifest_etag
-
-        raise ContractDrift.new(
-          "manifest changed (was #{short_etag(manifest_etag)}, now #{short_etag(observed_etag)}); re-run boot",
-        )
-      end
-
-      private
-
-      # First 8 hex chars after the "sha256:" prefix — a stable short id for
-      # the drift diagnostic. Tolerates non-prefixed values (delete_prefix is
-      # a no-op when the prefix is absent).
-      def short_etag(etag) = etag.to_s.delete_prefix("sha256:")[0, 8]
-    end
+    # The session value now lives in core (ADR 0036); retained here as an
+    # alias so existing MCP references keep resolving.
+    Session = Textus::Session
   end
 end

data/lib/textus/mcp/tool_schemas.rb

@@ -1,70 +1,14 @@
 module Textus
   module MCP
-    # JSON-Schema definitions for every MCP tool's inputSchema. Returned by
-    # the server in tools/list. Static today — a follow-up will enrich with
-    # manifest-derived enums for `zone`, `key`, etc.
+    # Kept for name stability (ADR 0039). The JSON schemas are DERIVED from
+    # per-verb contracts; this delegates to MCP::Catalog. The hand-written
+    # array is gone — a kwarg rename now updates the schema automatically (and
+    # the signature guard fails if the contract lags the use-case).
     module ToolSchemas
       module_function
 
-      def all # rubocop:disable Metrics/MethodLength
-        [
-          tool("boot", "Return the orientation contract: zones, entries, schemas, write_flows, agent_quickstart.", {}, []),
-          tool("tick", "Delta since cursor. Returns {cursor, changed, stale, pending_review, doctor}.",
-               { "since" => { "type" => "integer", "minimum" => 0 } }, []),
-          tool("find", "List keys filtered by zone and/or prefix.",
-               { "zone" => { "type" => "string" }, "prefix" => { "type" => "string" } }, []),
-          tool("read", "Read one entry. Returns the envelope (uid, etag, _meta, body, freshness).",
-               { "key" => { "type" => "string" } }, ["key"]),
-          tool("write", "Create or update an entry. Schema-validated. Returns {uid, etag}.",
-               {
-                 "key" => { "type" => "string" },
-                 "meta" => { "type" => "object" },
-                 "body" => { "type" => "string" },
-                 "content" => { "type" => "object" },
-                 "if_etag" => { "type" => "string" },
-               }, %w[key meta]),
-          tool("propose", "Write a proposal to the session's propose_zone. Auto-prefixes the key.",
-               {
-                 "key" => { "type" => "string", "description" => "Key relative to propose_zone, e.g. 'proposal.feature-x'" },
-                 "meta" => { "type" => "object" },
-                 "body" => { "type" => "string" },
-               }, %w[key meta]),
-          tool("fetch", "Run an intake fetch for one key. Returns the fetch Outcome.",
-               { "key" => { "type" => "string" } }, ["key"]),
-          tool("fetch_stale", "Fetch all stale intake entries, optionally scoped by zone/prefix.",
-               {
-                 "zone" => { "type" => "string" },
-                 "prefix" => { "type" => "string" },
-               }, []),
-          tool("schema", "Return the schema (field shape) for an entry family.",
-               { "family" => { "type" => "string" } }, ["family"]),
-          tool("rules", "Return effective rules for a key (fetch, promote, ...).",
-               { "key" => { "type" => "string" } }, ["key"]),
-          tool("key_mv_prefix",
-               "Bulk-rename every leaf key under from_prefix to to_prefix. Dry-run returns a Plan; apply with dry_run: false.",
-               { "from_prefix" => { "type" => "string" }, "to_prefix" => { "type" => "string" }, "dry_run" => { "type" => "boolean" } },
-               %w[from_prefix to_prefix]),
-          tool("key_delete_prefix", "Bulk-delete every leaf key under prefix.",
-               { "prefix" => { "type" => "string" }, "dry_run" => { "type" => "boolean" } },
-               ["prefix"]),
-          tool("zone_mv", "Rename a zone — manifest + files. Refuses if destination exists.",
-               { "from" => { "type" => "string" }, "to" => { "type" => "string" }, "dry_run" => { "type" => "boolean" } },
-               %w[from to]),
-          tool("rule_lint", "Diff candidate manifest YAML's rules against the live manifest. No writes.",
-               { "candidate_yaml" => { "type" => "string" } },
-               ["candidate_yaml"]),
-          tool("migrate", "Run a YAML migration plan (multi-op).",
-               { "plan_yaml" => { "type" => "string" }, "dry_run" => { "type" => "boolean" } },
-               ["plan_yaml"]),
-        ].freeze
-      end
-
-      def tool(name, description, properties, required)
-        {
-          name: name,
-          description: description,
-          inputSchema: { type: "object", properties: properties, required: required },
-        }
+      def all
+        Catalog.tool_schemas
       end
     end
   end

data/lib/textus/mcp/tools.rb

@@ -1,129 +1,14 @@
 module Textus
   module MCP
-    # Dispatch table for MCP tool names → implementations. Each implementation
-    # receives (session:, store:, args:) and returns a JSON-encodable value.
-    # Tool errors are wrapped in ToolError; ContractDrift / CursorExpired
-    # propagate verbatim so the server can map them to JSON-RPC codes.
+    # Thin delegator kept for name stability (ADR 0039). The dispatch table
+    # and JSON schemas are now DERIVED from per-verb contracts by MCP::Catalog;
+    # this module only forwards.
     module Tools
       module_function
 
       def call(name, session:, store:, args:)
-        impl = REGISTRY[name] or raise ToolError.new("unknown tool: #{name}")
-        impl.call(session, store, args || {})
-      rescue ContractDrift, CursorExpired
-        raise
-      rescue Textus::Error => e
-        raise ToolError.new("#{name}: #{e.message}")
+        Catalog.call(name, session: session, store: store, args: args || {})
       end
-
-      def ops_for(session, store)
-        store.as(session.role)
-      end
-
-      REGISTRY = {
-        "boot" => ->(_s, store, _a) { store.boot },
-
-        "find" => lambda do |s, store, args|
-          ops_for(s, store).list(zone: args["zone"], prefix: args["prefix"])
-        end,
-
-        "read" => lambda do |s, store, args|
-          key = args.fetch("key") { raise ToolError.new("read: missing key") }
-          env = ops_for(s, store).get(key)
-          env.to_h_for_wire
-        end,
-
-        "tick" => lambda do |s, store, args|
-          since = (args["since"] || s.cursor).to_i
-          ops_for(s, store).pulse(since: since)
-        end,
-
-        "write" => lambda do |s, store, args|
-          key = args.fetch("key") { raise ToolError.new("write: missing key") }
-          env = ops_for(s, store).put(
-            key,
-            meta: args["meta"] || {},
-            body: args["body"],
-            content: args["content"],
-            if_etag: args["if_etag"],
-          )
-          { "uid" => env.uid, "etag" => env.etag }
-        end,
-
-        "propose" => lambda do |s, store, args|
-          raise ToolError.new("propose: session has no propose_zone") unless s.propose_zone
-
-          rel = args.fetch("key") { raise ToolError.new("propose: missing key") }
-          target = "#{s.propose_zone}.#{rel}"
-          env = ops_for(s, store).put(
-            target,
-            meta: args["meta"] || {},
-            body: args["body"],
-            content: args["content"],
-          )
-          { "uid" => env.uid, "etag" => env.etag, "key" => target }
-        end,
-
-        "fetch" => lambda do |s, store, args|
-          key = args.fetch("key") { raise ToolError.new("fetch: missing key") }
-          outcome = ops_for(s, store).fetch(key)
-          { "outcome" => outcome.class.name.split("::").last.downcase }
-        end,
-
-        "fetch_stale" => lambda do |s, store, args|
-          ops_for(s, store).fetch_all(zone: args["zone"], prefix: args["prefix"])
-        end,
-
-        "schema" => lambda do |_s, store, args|
-          family = args.fetch("family") { raise ToolError.new("schema: missing family") }
-          store.schemas.fetch(family)
-        end,
-
-        "rules" => lambda do |_s, store, args|
-          key = args.fetch("key") { raise ToolError.new("rules: missing key") }
-          set = store.manifest.rules.for(key)
-          {
-            "fetch" => set.fetch&.to_h,
-            "guard" => set.guard,
-          }.compact
-        end,
-
-        "key_mv_prefix" => lambda do |s, store, args|
-          ops_for(s, store).key_mv_prefix(
-            from_prefix: args.fetch("from_prefix") { raise ToolError.new("key_mv_prefix: missing from_prefix") },
-            to_prefix: args.fetch("to_prefix") { raise ToolError.new("key_mv_prefix: missing to_prefix") },
-            dry_run: args["dry_run"] || false,
-          ).to_h
-        end,
-
-        "key_delete_prefix" => lambda do |s, store, args|
-          ops_for(s, store).key_delete_prefix(
-            prefix: args.fetch("prefix") { raise ToolError.new("key_delete_prefix: missing prefix") },
-            dry_run: args["dry_run"] || false,
-          ).to_h
-        end,
-
-        "zone_mv" => lambda do |s, store, args|
-          ops_for(s, store).zone_mv(
-            from: args.fetch("from") { raise ToolError.new("zone_mv: missing from") },
-            to: args.fetch("to") { raise ToolError.new("zone_mv: missing to") },
-            dry_run: args["dry_run"] || false,
-          ).to_h
-        end,
-
-        "rule_lint" => lambda do |s, store, args|
-          ops_for(s, store).rule_lint(
-            candidate_yaml: args.fetch("candidate_yaml") { raise ToolError.new("rule_lint: missing candidate_yaml") },
-          ).to_h
-        end,
-
-        "migrate" => lambda do |s, store, args|
-          ops_for(s, store).migrate(
-            plan_yaml: args.fetch("plan_yaml") { raise ToolError.new("migrate: missing plan_yaml") },
-            dry_run: args["dry_run"] || false,
-          ).to_h
-        end,
-      }.freeze
     end
   end
 end

data/lib/textus/ports/audit_log.rb

@@ -10,7 +10,7 @@ module Textus
 
       def initialize(root, max_size: DEFAULT_MAX_SIZE, keep: DEFAULT_KEEP)
         @root     = root
-        @path     = File.join(root, "audit.log")
+        @path     = Textus::Layout.audit_log(root)
         @max_size = max_size
         @keep     = keep
       end
@@ -54,6 +54,7 @@ module Textus
       end
 
       def append(role:, verb:, key:, etag_before:, etag_after:, extras: nil)
+        FileUtils.mkdir_p(File.dirname(@path))
         File.open(@path, File::WRONLY | File::APPEND | File::CREAT, 0o644) do |f|
           f.flock(File::LOCK_EX)
           next_seq = current_max_seq_unlocked + 1
@@ -81,6 +82,14 @@ module Textus
 
       private
 
+      def rotated(n)
+        File.join(Textus::Layout.audit_dir(@root), "audit.log.#{n}")
+      end
+
+      def rotated_meta(n)
+        File.join(Textus::Layout.audit_dir(@root), "audit.log.#{n}.meta.json")
+      end
+
       # Caller holds the flock. Returns the highest seq across the active log,
       # OR the most-recent rotated file's max_seq if the active log is empty.
       def current_max_seq_unlocked
@@ -113,7 +122,7 @@ module Textus
       end
 
       def read_meta(n)
-        path = File.join(@root, "audit.log.#{n}.meta.json")
+        path = rotated_meta(n)
         return nil unless File.exist?(path)
 
         JSON.parse(File.read(path))
@@ -151,25 +160,18 @@ module Textus
         meta = { "min_seq" => min_seq, "max_seq" => max_seq, "rotated_at" => Time.now.utc.iso8601 }
 
         # Drop the file that would be shifted past @keep.
-        oldest      = File.join(@root, "audit.log.#{@keep}")
-        oldest_meta = File.join(@root, "audit.log.#{@keep}.meta.json")
-        FileUtils.rm_f(oldest)
-        FileUtils.rm_f(oldest_meta)
+        FileUtils.rm_f(rotated(@keep))
+        FileUtils.rm_f(rotated_meta(@keep))
 
         # Shift .N → .(N+1) for N = keep-1 down to 1.
         (@keep - 1).downto(1) do |n|
-          src      = File.join(@root, "audit.log.#{n}")
-          dst      = File.join(@root, "audit.log.#{n + 1}")
-          File.rename(src, dst) if File.exist?(src)
-
-          src_meta = File.join(@root, "audit.log.#{n}.meta.json")
-          dst_meta = File.join(@root, "audit.log.#{n + 1}.meta.json")
-          File.rename(src_meta, dst_meta) if File.exist?(src_meta)
+          File.rename(rotated(n), rotated(n + 1)) if File.exist?(rotated(n))
+          File.rename(rotated_meta(n), rotated_meta(n + 1)) if File.exist?(rotated_meta(n))
         end
 
         # Active log → .1
-        File.rename(@path, File.join(@root, "audit.log.1"))
-        File.write(File.join(@root, "audit.log.1.meta.json"), JSON.generate(meta) + "\n")
+        File.rename(@path, rotated(1))
+        File.write(rotated_meta(1), JSON.generate(meta) + "\n")
         # Next append will create a fresh audit.log via File::CREAT.
       end
 

data/lib/textus/ports/build_lock.rb

@@ -5,7 +5,6 @@ require "time"
 module Textus
   module Ports
     class BuildLock
-      LOCK_FILENAME = ".build.lock"
       MAX_HOLDER_BYTES = 512
 
       def self.with(root:, &)
@@ -13,7 +12,7 @@ module Textus
       end
 
       def initialize(root:)
-        @path = File.join(root, LOCK_FILENAME)
+        @path = Textus::Layout.build_lock(root)
         @file = nil
       end
 

data/lib/textus/ports/fetch/lock.rb

@@ -7,7 +7,7 @@ module Textus
         def initialize(root:, key:)
           @root = root
           @key  = key
-          @path = File.join(root, ".locks", "#{safe_key}.lock")
+          @path = File.join(Textus::Layout.locks(root), "#{safe_key}.lock")
           @file = nil
         end
 

data/lib/textus/read/audit.rb

@@ -3,7 +3,7 @@ require "time"
 
 module Textus
   module Read
-    # Queries .textus/audit.log. Filters: key, zone, role, verb, since,
+    # Queries .textus/.run/audit/audit.log. Filters: key, zone, role, verb, since,
     # correlation_id, limit. Reads the log file as JSON-Lines (legacy TSV
     # rows produce nil and are skipped).
     class Audit
@@ -33,7 +33,7 @@ module Textus
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest  = container.manifest
         @root      = container.root
-        @log_path  = File.join(container.root, "audit.log")
+        @log_path  = Textus::Layout.audit_log(container.root)
         @audit_log = container.audit_log
       end
 
@@ -84,7 +84,7 @@ module Textus
       end
 
       def all_log_files
-        rotated = Dir.glob(File.join(@root, "audit.log.*"))
+        rotated = Dir.glob(File.join(Textus::Layout.audit_dir(@root), "audit.log.*"))
                      .reject { |p| p.end_with?(".meta.json") }
                      .sort_by { |p| -p.scan(/\d+$/).first.to_i } # .5 .4 .3 .2 .1 → oldest first
         active = File.exist?(@log_path) ? [@log_path] : []

data/lib/textus/read/boot.rb

@@ -5,6 +5,12 @@ module Textus
     # (container:, call:) entry point that Dispatcher::VERBS resolves to.
     # Boot is role-independent, so `call` is not consulted.
     class Boot
+      extend Textus::Contract::DSL
+
+      verb     :boot
+      summary  "Return the orientation contract: zones, entries, schemas, write_flows, agent_quickstart."
+      surfaces :cli, :ruby, :mcp
+
       def initialize(container:, call:)
         @container = container
         @call      = call

data/lib/textus/read/get.rb

@@ -6,6 +6,14 @@ module Textus
     # For interactive reads that want fetch-on-stale, use
     # `Read::GetOrFetch`, which composes this with the orchestrator.
     class Get
+      extend Textus::Contract::DSL
+
+      verb     :get
+      summary  "Read one entry. Returns the envelope (uid, etag, _meta, body, freshness)."
+      surfaces :cli, :ruby, :mcp
+      arg :key, String, required: true, positional: true
+      response(&:to_h_for_wire)
+
       def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator)
         @container  = container
         @call       = call

data/lib/textus/read/list.rb

@@ -1,6 +1,14 @@
 module Textus
   module Read
     class List
+      extend Textus::Contract::DSL
+
+      verb     :list
+      summary  "List keys filtered by zone and/or prefix."
+      surfaces :cli, :ruby, :mcp
+      arg :prefix, String
+      arg :zone,   String
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest
       end

data/lib/textus/read/pulse.rb

@@ -7,6 +7,13 @@ module Textus
     # APIs; pulse is sugar with a stable envelope shape and a monotonic
     # cursor (seq).
     class Pulse
+      extend Textus::Contract::DSL
+
+      verb     :pulse
+      summary  "Delta since cursor — changed entries, stale, pending proposals, doctor summary."
+      surfaces :cli, :ruby, :mcp
+      arg :since, Integer, session_default: :cursor, description: "audit seq to diff from; defaults to the session cursor"
+
       def initialize(container:, call:)
         @container  = container
         @call       = call