textus 0.43.2 → 0.45.1

data/lib/textus/projection.rb

@@ -7,8 +7,8 @@ module Textus
     REDUCER_TIMEOUT_SECONDS = 2
 
     # `reader` — a callable `->(key) { envelope_or_nil }`. Caller picks
-    #   semantics: pure read (`ops.get`) for materialization paths;
-    #   `ops.get_or_fetch` if you want fetch-on-stale.
+    #   semantics: pure read (`Read::Get.new(...).call(key)`, fetch:false default) for
+    #   materialization paths; `ops.get` (read-through, fetch:true injected) for fetch-on-stale.
     # `lister` — a callable `->(prefix:) { [ { "key" => ... }, ... ] }`.
     # `rpc` — a `Hooks::RpcRegistry` used to dispatch `transform_rows` callables.
     # `transform_context` — capability object handed to transform reducers as `caps:`.

data/lib/textus/read/audit.rb

@@ -30,6 +30,25 @@ module Textus
         end
       end
 
+      extend Textus::Contract::DSL
+
+      verb     :audit
+      summary  "Query the audit log with optional filters."
+      surfaces :cli, :ruby
+      cli      "audit"
+      # #call(**filters) — args map to Query.build keyword params (ADR 0063)
+      arg :key,            String,  required: false, description: "filter to rows for this key"
+      arg :zone,           String,  required: false, description: "filter to keys in this zone"
+      arg :role,           String,  required: false, description: "filter to rows written under this role"
+      arg :verb,           String,  required: false, description: "filter to rows for this verb"
+      arg :since,          String,  required: false,
+                                    coerce: ->(s) { Textus::Read::Audit.parse_since(s, now: Time.now) },
+                                    description: "ISO-8601 timestamp or relative offset (e.g. 1h, 30m)"
+      arg :seq_since,      Integer, required: false, description: "return rows with seq > this cursor value"
+      arg :correlation_id, String,  required: false, description: "filter to rows with this correlation_id"
+      arg :limit,          Integer, required: false, description: "maximum number of rows to return"
+      view(:cli) { |rows, _i| { "verb" => "audit", "rows" => rows } }
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest  = container.manifest
         @root      = container.root

data/lib/textus/read/blame.rb

@@ -7,13 +7,23 @@ module Textus
     # row. Falls back to `git => nil` when not in a git repo or when the
     # file is untracked.
     class Blame
+      extend Textus::Contract::DSL
+
+      verb     :blame
+      summary  "Annotate audit rows for a key with the git commit that introduced each file state."
+      surfaces :cli, :ruby
+      cli      "blame"
+      arg :key,   String,  required: true, positional: true, description: "entry key to blame"
+      arg :limit, Integer, required: false, description: "maximum number of audit rows to return"
+      view(:cli) { |rows, inputs| { "verb" => "blame", "key" => inputs[:key], "rows" => rows } }
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @container = container
         @manifest  = container.manifest
         @root      = container.root
       end
 
-      def call(key:, limit: nil)
+      def call(key, limit: nil)
         audit_rows = Textus::Read::Audit.new(container: @container).call(key: key, limit: limit)
         path = resolve_path(key)
         return audit_rows.map { |r| r.merge("git" => nil) } unless git_tracked?(path)

data/lib/textus/read/deps.rb

@@ -1,12 +1,26 @@
 module Textus
   module Read
     class Deps
+      extend Textus::Contract::DSL
+
+      verb     :deps
+      summary  "List the keys a derived entry depends on (its projection/external sources)."
+      surfaces :cli, :ruby, :mcp
+      arg :key, String, required: true, positional: true,
+                        description: "dotted key of the derived entry whose source keys you want"
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest
       end
 
       def call(key)
-        entry = @manifest.data.entries.find { |e| e.key == key } or return []
+        { "key" => key, "deps" => sources_for(key) }
+      end
+
+      private
+
+      def sources_for(key)
+        entry = @manifest.data.entries.find { |e| e.key == key }
         return [] unless entry.is_a?(Textus::Manifest::Entry::Derived)
 
         src = entry.source

data/lib/textus/read/doctor.rb

@@ -6,6 +6,14 @@ module Textus
     # The acting role is irrelevant to a read-only health check, so `call`
     # is not consulted.
     class Doctor
+      extend Textus::Contract::DSL
+
+      verb     :doctor
+      summary  "Run health checks on the textus store and report any issues."
+      surfaces :cli, :ruby
+      cli      "doctor"
+      arg :checks, Array, required: false, description: "subset of check names to run (default: all)"
+
       def initialize(container:, call:)
         @container = container
         @call      = call

data/lib/textus/read/freshness.rb

@@ -7,6 +7,16 @@ module Textus
     # current status. Status is one of :fresh, :stale, :never_fetched, or
     # :no_policy.
     class Freshness
+      extend Textus::Contract::DSL
+
+      verb     :freshness
+      summary  "Report the fetch-freshness status of every entry with a fetch policy."
+      surfaces :cli, :ruby
+      cli      "freshness"
+      arg :prefix, String, required: false, description: "filter to keys with this prefix"
+      arg :zone,   String, required: false, description: "filter to entries in this zone"
+      view(:cli) { |rows| { "verb" => "freshness", "rows" => rows } }
+
       def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator)
         @container  = container
         @call       = call

data/lib/textus/read/get.rb

@@ -1,54 +1,103 @@
 module Textus
   module Read
-    # Pure read: returns the on-disk envelope annotated with a freshness
-    # verdict. Never triggers fetch; never invokes the orchestrator.
+    # The one read path. `fetch:` controls behavior:
+    #   fetch: false (default) — pure read: the on-disk envelope annotated with
+    #     a freshness verdict. NEVER builds the orchestrator (no threads/forks/
+    #     locks/events). This is the safe default for direct (in-process)
+    #     callers — accept/reject/publish, materializer, uid, validate_all/
+    #     validator, schema tooling, and the hook context — that must read
+    #     persisted truth without triggering a fetch.
+    #   fetch: true — read-through: after a stale verdict, hands off to the
+    #     fetch orchestrator per the entry's fetch rule (degrades to the pure
+    #     result when the key has no rule).
     #
-    # For interactive reads that want fetch-on-stale, use
-    # `Read::GetOrFetch`, which composes this with the orchestrator.
+    # The public `get` verb is read-through because the contract declares
+    # `arg :fetch, default: true`, injected on every verb surface (RoleScope +
+    # MCP map_args, ADR 0062 amendment). Direct construction bypasses that
+    # injection and so gets the safe `fetch: false` method default.
     class Get
       extend Textus::Contract::DSL
 
       verb     :get
-      summary  "Read one entry. Returns the envelope (uid, etag, _meta, body, freshness)."
+      summary  "Read one entry. Read-through by default — fetches on stale per " \
+               "the entry's fetch rule, degrading to a pure read when the key " \
+               "has no rule. Pass fetch:false for a guaranteed pure on-disk " \
+               "read. Returns the envelope (uid, etag, _meta, body, freshness)."
       surfaces :cli, :ruby, :mcp
       arg :key, String, required: true, positional: true,
                         description: "dotted entry key to read, e.g. 'knowledge.project'"
-      response(&:to_h_for_wire)
+      arg :fetch, :boolean, default: true,
+                            description: "read-through (fetch on stale per the " \
+                                         "entry's fetch rule) when true, the default; " \
+                                         "false returns the on-disk envelope without ever fetching"
+      view { |v, _i| v.to_h_for_wire }
 
-      def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator)
+      def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator, orchestrator: nil)
         @container  = container
         @call       = call
         @manifest   = container.manifest
         @file_store = container.file_store
         @evaluator  = evaluator
+        @orchestrator = orchestrator # nil → built lazily on first fetch only
       end
 
-      def call(key)
+      def call(key, fetch: false)
+        envelope = annotated_envelope(key)
+        return envelope if envelope.nil?
+        return envelope unless fetch && envelope.freshness&.stale
+
+        fetch_policy = fetch_policy_for(key)
+        return envelope if fetch_policy.nil?
+
+        policy  = fetch_policy.to_freshness_policy
+        verdict = Textus::Domain::Freshness::Verdict.stale(envelope.freshness.reason)
+        outcome = orchestrator.execute(policy.decide(verdict), key: key)
+        resolve(outcome, envelope)
+      end
+
+      # Strict variant: raises UnknownKey when the entry is missing.
+      # Used by consumers (e.g. uid, Validator) that distinguish absence.
+      def get(key, fetch: false)
+        call(key, fetch: fetch) ||
+          raise(UnknownKey.new(key, suggestions: @manifest.resolver.suggestions_for(key)))
+      end
+
+      private
+
+      # Pure read + freshness verdict; no orchestrator dependency.
+      def annotated_envelope(key)
         envelope = read_raw_envelope(key)
         return nil if envelope.nil?
 
-        policy_set = @manifest.rules.for(key)
-        fetch_policy = policy_set.fetch
+        fetch_policy = fetch_policy_for(key)
         return annotate_fresh(envelope) if fetch_policy.nil?
 
-        policy = fetch_policy.to_freshness_policy
+        policy  = fetch_policy.to_freshness_policy
         verdict = @evaluator.call(policy, envelope, now: @call.now)
-
         envelope.with(freshness: Textus::Domain::Freshness.build(
-          stale: verdict.stale?,
-          reason: verdict.reason,
-          fetching: false,
+          stale: verdict.stale?, reason: verdict.reason, fetching: false,
         ))
       end
 
-      # Strict variant: raises UnknownKey when the entry is missing.
-      # Used by consumers (e.g. Validator) that need to distinguish absence
-      # from emptiness.
-      def get(key)
-        call(key) || raise(UnknownKey.new(key, suggestions: @manifest.resolver.suggestions_for(key)))
+      def fetch_policy_for(key)
+        @manifest.rules.for(key).fetch
       end
 
-      private
+      def resolve(outcome, envelope)
+        case outcome
+        when Textus::Domain::Outcome::Skipped
+          envelope
+        when Textus::Domain::Outcome::Fetched
+          outcome.envelope.with(
+            freshness: Textus::Domain::Freshness.build(stale: false, reason: nil, fetching: false),
+          )
+        when Textus::Domain::Outcome::Detached
+          envelope.with(freshness: envelope.freshness.with(fetching: true))
+        when Textus::Domain::Outcome::Failed
+          envelope.with(freshness: envelope.freshness.with(fetch_error: outcome.error.message))
+        else raise "unexpected fetch outcome: #{outcome.class}"
+        end
+      end
 
       def read_raw_envelope(key)
         res = @manifest.resolver.resolve(key)
@@ -70,6 +119,22 @@ module Textus
           stale: false, reason: nil, fetching: false,
         ))
       end
+
+      def orchestrator
+        @orchestrator ||= build_orchestrator
+      end
+
+      def build_orchestrator
+        worker = Textus::Write::FetchWorker.new(container: @container, call: @call)
+        Textus::Write::FetchOrchestrator.new(
+          worker: worker, store_root: @container.root, events: @container.events,
+          hook_context: hook_context
+        )
+      end
+
+      def hook_context
+        @hook_context ||= Textus::Hooks::Context.for(container: @container, call: @call)
+      end
     end
   end
 end

data/lib/textus/read/list.rb

@@ -8,6 +8,7 @@ module Textus
       surfaces :cli, :ruby, :mcp
       arg :prefix, String, description: "restrict to keys starting with this dotted prefix, e.g. 'knowledge.runbooks'"
       arg :zone,   String, description: "restrict to one zone by name (see `boot` zones); combine with prefix to narrow further"
+      view(:cli) { |rows| { "entries" => rows } }
 
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest

data/lib/textus/read/published.rb

@@ -1,6 +1,13 @@
 module Textus
   module Read
     class Published
+      extend Textus::Contract::DSL
+
+      verb     :published
+      summary  "List all entries that declare a publish_to target."
+      surfaces :cli, :ruby
+      cli      "published"
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest
       end

data/lib/textus/read/pulse.rb

@@ -12,6 +12,7 @@ module Textus
       verb     :pulse
       summary  "Delta since cursor — changed entries, stale, pending proposals, doctor summary."
       surfaces :cli, :ruby, :mcp
+      around   :cursor
       arg :since, Integer, session_default: :cursor, description: "audit seq to diff from; defaults to the session cursor"
 
       def initialize(container:, call:)

data/lib/textus/read/rdeps.rb

@@ -1,11 +1,25 @@
 module Textus
   module Read
     class Rdeps
+      extend Textus::Contract::DSL
+
+      verb     :rdeps
+      summary  "List the derived entries that depend on a key (reverse deps / impact set)."
+      surfaces :cli, :ruby, :mcp
+      arg :key, String, required: true, positional: true,
+                        description: "dotted key whose dependents (what would be stranded if it moved) you want"
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest
       end
 
       def call(key)
+        { "key" => key, "rdeps" => dependents_of(key) }
+      end
+
+      private
+
+      def dependents_of(key)
         @manifest.data.entries.each_with_object([]) do |e, acc|
           next unless e.is_a?(Textus::Manifest::Entry::Derived)
 

data/lib/textus/read/rule_explain.rb

@@ -0,0 +1,84 @@
+module Textus
+  module Read
+    # Effective rules for a key, at two depths (ADR 0059). Lean by default —
+    # `{ fetch, guard }`, the agent-cheap read that was the `rules` verb. With
+    # `detail: true` it returns the verbose explanation — every matching policy
+    # block plus the per-transition guard predicate names — that was
+    # `policy_explain`. One verb, one name across CLI/MCP/method; the audience
+    # split is a parameter, not two tools.
+    class RuleExplain
+      extend Textus::Contract::DSL
+
+      verb     :rule_explain
+      summary  "Effective rules for a key. Lean {fetch, guard} by default; detail: true adds matched blocks + guard predicates."
+      surfaces :cli, :ruby, :mcp
+      cli      "rule explain"
+      arg :key,    String, required: true, positional: true,
+                           description: "dotted key whose effective rules you want (fetch ttl/action, write guard, ...)"
+      arg :detail, :boolean,
+          description: "defaults false: lean {fetch, guard}. detail: true adds matched blocks + guard predicates per transition."
+      view(:cli) { |r| { "verb" => "rule_explain" }.merge(r.transform_keys(&:to_s)) }
+
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest = container.manifest
+        @schemas  = container.schemas
+      end
+
+      def call(key, detail: false)
+        detail ? explain(key) : effective(key)
+      end
+
+      private
+
+      # Lean: the effective winners only (formerly Read::Rules / the `rules` verb).
+      def effective(key)
+        set = @manifest.rules.for(key)
+        {
+          "fetch" => set.fetch && {
+            "ttl_seconds" => set.fetch.ttl_seconds,
+            "on_stale" => set.fetch.on_stale,
+            "sync_budget_ms" => set.fetch.sync_budget_ms,
+            "fetch_timeout_seconds" => set.fetch.fetch_timeout_seconds,
+          },
+          "guard" => set.guard,
+        }.compact
+      end
+
+      # Verbose: every matching block, per-slot effective value, and the
+      # effective guard predicate names for each write transition (formerly
+      # Read::PolicyExplain, ADR 0031).
+      def explain(key)
+        matching = @manifest.rules.explain(key)
+        winners  = @manifest.rules.for(key)
+        factory  = Textus::Domain::Policy::GuardFactory.new(manifest: @manifest, schemas: @schemas)
+
+        {
+          key: key,
+          matched_blocks: matching.map do |b|
+            {
+              match: b.match,
+              fetch: !b.fetch.nil?,
+              handler_allowlist: !b.handler_allowlist.nil?,
+              guard: !b.guard.nil?,
+              retention: !b.retention.nil?,
+            }
+          end,
+          effective: {
+            fetch: winners.fetch && {
+              ttl_seconds: winners.fetch.ttl_seconds,
+              on_stale: winners.fetch.on_stale,
+            },
+            handler_allowlist: winners.handler_allowlist&.handlers,
+            retention: winners.retention && {
+              expire_after: winners.retention.expire_after,
+              archive_after: winners.retention.archive_after,
+            },
+          },
+          guards: Textus::Domain::Policy::BaseGuards::BASE.keys.to_h do |transition|
+            [transition, factory.for(transition, key).predicates.map(&:name)]
+          end,
+        }
+      end
+    end
+  end
+end

data/lib/textus/read/rule_list.rb

@@ -0,0 +1,39 @@
+module Textus
+  module Read
+    # Enumerate every declared rule block in the manifest, in order. This is
+    # the whole-manifest view; `rule_explain` is the for-key view. Extracted
+    # from the CLI verb so the rule family is fully use-case-backed (ADR 0059);
+    # CLI-only (no MCP contract) — an agent reasons per-key via rule_explain.
+    class RuleList
+      extend Textus::Contract::DSL
+
+      verb     :rule_list
+      summary  "List every rule block in the manifest."
+      surfaces :cli, :ruby
+      cli      "rule list"
+      view(:cli) { |policies| { "verb" => "rule_list", "policies" => policies } }
+
+      def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
+        @manifest = container.manifest
+      end
+
+      def call
+        @manifest.rules.blocks.map do |b|
+          row = { "match" => b.match }
+          if b.fetch
+            row["fetch"] = {
+              "ttl_seconds" => b.fetch.ttl_seconds,
+              "on_stale" => b.fetch.on_stale,
+              "sync_budget_ms" => b.fetch.sync_budget_ms,
+              "fetch_timeout_seconds" => b.fetch.fetch_timeout_seconds,
+            }
+          end
+          row["handler_allowlist"] = b.handler_allowlist.handlers if b.handler_allowlist
+          row["guard"] = b.guard if b.guard
+          row["retention"] = { "expire_after" => b.retention.expire_after, "archive_after" => b.retention.archive_after } if b.retention
+          row
+        end
+      end
+    end
+  end
+end

data/lib/textus/read/schema_envelope.rb

@@ -3,9 +3,10 @@ module Textus
     class SchemaEnvelope
       extend Textus::Contract::DSL
 
-      verb     :schema
+      verb     :schema_show
       summary  "Return the schema (field shape) for an entry's family, by key."
-      surfaces :ruby, :mcp
+      surfaces :cli, :ruby, :mcp
+      cli      "schema show"
       arg :key, String, required: true, positional: true,
                         description: "any key in the family whose schema you want; returns required/optional fields and their types"
 

data/lib/textus/read/uid.rb

@@ -1,6 +1,15 @@
 module Textus
   module Read
     class Uid
+      extend Textus::Contract::DSL
+
+      verb     :uid
+      summary  "Return the stable UID of an entry without reading its body."
+      surfaces :cli, :ruby
+      cli      "key uid"
+      arg :key, String, required: true, positional: true, description: "entry key"
+      view(:cli) { |uid, inputs| { "key" => inputs[:key], "uid" => uid } }
+
       def initialize(container:, call:)
         @container = container
         @call      = call

data/lib/textus/read/where.rb

@@ -1,6 +1,14 @@
 module Textus
   module Read
     class Where
+      extend Textus::Contract::DSL
+
+      verb     :where
+      summary  "Resolve a key to its zone, owner, and path without reading the body."
+      surfaces :cli, :ruby, :mcp
+      arg :key, String, required: true, positional: true,
+                        description: "dotted key to locate (returns zone, owner, path; does not read content)"
+
       def initialize(container:, call: nil) # rubocop:disable Lint/UnusedMethodArgument
         @manifest = container.manifest
       end

data/lib/textus/role_scope.rb

@@ -36,14 +36,42 @@ module Textus
       self.class.new(container: @container, role: @role, dry_run: true, correlation_id: @correlation_id)
     end
 
+    # Single bind + invoke site for every surface. `inputs` is the uniform
+    # by-name hash (the binder's currency). MCP/CLI build it from their raw
+    # transport shape and call this directly; the per-verb Ruby methods below
+    # normalize positional+keyword Ruby args into `inputs` and delegate here.
+    def dispatch_bound(verb, inputs, session: nil)
+      klass = Textus::Dispatcher::VERBS[verb]
+      spec = (klass.contract if klass.respond_to?(:contract?) && klass.contract?)
+
+      invoke = lambda do |effective_inputs|
+        args, kwargs =
+          if spec
+            Textus::Contract::Binder.bind(spec, effective_inputs, session: session)
+          else
+            [[], effective_inputs]
+          end
+        call_value = Textus::Call.build(role: @role, correlation_id: @correlation_id, dry_run: @dry_run)
+        Textus::Dispatcher.invoke(verb, container: @container, call: call_value, args: args, kwargs: kwargs)
+      end
+
+      if spec&.around
+        Textus::Contract::Around.with(spec.around, scope: self, inputs: inputs, session: session, &invoke)
+      else
+        invoke.call(inputs)
+      end
+    end
+
     Textus::Dispatcher::VERBS.each_key do |verb|
       define_method(verb) do |*args, **kwargs|
-        call_value = Textus::Call.build(
-          role: @role, correlation_id: @correlation_id, dry_run: @dry_run,
-        )
-        Textus::Dispatcher.invoke(
-          verb, container: @container, call: call_value, args: args, kwargs: kwargs
-        )
+        klass = Textus::Dispatcher::VERBS[verb]
+        inputs =
+          if klass.respond_to?(:contract?) && klass.contract?
+            Textus::Contract::Binder.inputs_from_ordered(klass.contract, args, kwargs)
+          else
+            kwargs
+          end
+        dispatch_bound(verb, inputs)
       end
     end
   end

data/lib/textus/schema/tools.rb

@@ -6,7 +6,7 @@ module Textus
     module Tools
       # textus schema init NAME --from=KEY  → infer YAML schema from an entry's frontmatter
       def self.init(store, name:, from:)
-        env = store.as(Textus::Role::DEFAULT).get(from)
+        env = pure_get(store, Textus::Role::DEFAULT, from)
         meta = env.meta
         schema = {
           "name" => name,
@@ -25,7 +25,7 @@ module Textus
         schema = load_schema(store, name)
         drift = []
         store.manifest.resolver.enumerate.each do |row|
-          env = store.as(Textus::Role::DEFAULT).get(row[:key])
+          env = pure_get(store, Textus::Role::DEFAULT, row[:key])
           begin
             schema.validate!(env.meta)
           rescue SchemaViolation => e
@@ -53,7 +53,7 @@ module Textus
         ops = store.as(authority)
         touched = []
         store.manifest.resolver.enumerate.each do |row|
-          env = ops.get(row[:key])
+          env = pure_get(store, authority, row[:key])
           meta = env.meta.dup
           changed = false
           renames.each do |old, new|
@@ -81,6 +81,15 @@ module Textus
         end
       end
 
+      # Orchestrator-free read: schema tooling must never trigger a fetch
+      # while inspecting/migrating entries (ADR 0062).
+      def self.pure_get(store, role, key)
+        Textus::Read::Get.new(
+          container: store.as(role).container,
+          call: Textus::Call.build(role: role),
+        ).call(key)
+      end
+
       def self.load_schema(store, name)
         store.schemas.fetch(name)
       rescue IoError

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.43.2"
+  VERSION = "0.45.1"
   PROTOCOL = "textus/3"
 end

data/lib/textus/write/accept.rb

@@ -1,6 +1,14 @@
 module Textus
   module Write
     class Accept
+      extend Textus::Contract::DSL
+
+      verb :accept
+      summary "apply a queued proposal to its target zone; requires the author capability"
+      surfaces :cli, :ruby
+      cli "accept"
+      arg :pending_key, String, required: true, positional: true, description: "the queued proposal's key"
+
       def initialize(container:, call:)
         @container = container
         @call      = call

data/lib/textus/write/{publish.rb → build.rb}

@@ -1,14 +1,23 @@
 module Textus
   module Write
-    # Single-pass publish use case: dispatches polymorphically to each
-    # entry's `publish_via` method. Derived entries materialize their body
-    # via Materializer; Nested entries mirror their subtree via publish_tree;
-    # Leaf and Intake entries copy their stored body to publish_to targets.
-    # The Publish layer owns wiring (context, accumulation) but not per-kind
-    # logic.
+    # Single-pass build use case (the verb `build`, ADR 0061): dispatches
+    # polymorphically to each entry's `publish_via` method — the copy-out step
+    # (`publish` is the output-destination concept the verb drives, not the verb).
+    # Derived entries materialize their body via Materializer; Nested entries
+    # mirror their subtree via publish_tree; Leaf and Intake entries copy their
+    # stored body to publish_to targets. The Build layer owns wiring (context,
+    # accumulation) but not per-kind logic.
     #
     # Return shape: { "protocol", "built", "published_leaves" }
-    class Publish
+    class Build
+      extend Textus::Contract::DSL
+
+      verb     :build
+      summary  "materialize derived entries; publish_to and publish_tree fan out copies"
+      surfaces :cli, :ruby
+      cli      "build"
+      arg :prefix, String, required: false, description: "limit the build to keys under this prefix"
+
       def initialize(container:, call:)
         @container = container
         @call      = call