textus 0.46.0 → 0.47.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd3d64e647d112827056119d45576eda3b7f6ba95446f7a08522d674fb496d2c
-  data.tar.gz: b8c7c4d86eccd1469bdd024732dc0321fb64d837f59451efe1280fd7ae8d96e2
+  metadata.gz: c87fe067b0988d187beac617c4540e1563d0f006a08d6090b2b483c699555d46
+  data.tar.gz: 4f0503119ebf3eeff28d7a16aee8dc8c62673e6b41912e85bc3453e596075e65
 SHA512:
-  metadata.gz: 10096cbffbd633d18a915744ddc4e70b7324ad955525a76fc9fb4b95b32ab8b0781d566e10d1fc6695dd5a795b4721926859030e4c86e661bdef1728304b62aa
-  data.tar.gz: d393eee10185c057a7fe727dbb9abb572761e12bcec4b5253cda9a5367d5cd3684850e87432079cd71296f2ff917bd4e1a3e1be5b6484cc7be5ff3c33b4611a0
+  metadata.gz: fde04b0339e798e545c98699462afaf2767a772f1e76811c4f8833b561b69d02b172e4879cf17ffaea1dd51f1930846007abf4523a801ccfb5525c53e1365b7f
+  data.tar.gz: 10a4343781cb2251ba8f91121c0a89b1fe211702e7c5057693fce27357eee55c3abe6bfe7a88009ffc89f5fcc49ad6c44fcf258f532f5ac9d69d960857e833c6

data/CHANGELOG.md

@@ -9,6 +9,22 @@ The **gem version** (`0.x.y`) is distinct from the **protocol version**
 bump is a breaking change that requires a store migration; the gem version
 tracks both additive improvements and breaking protocol bumps independently.
 
+## 0.47.0 — 2026-06-04 — Close the agent loop over MCP
+
+The edit→accept→rebuild loop now closes over a single MCP transport: `build` is surfaced to MCP, `init --with-agent` scaffolds a connectable agent setup, and connection-lifecycle hardening (whole-contract drift fingerprint + a connect-time event carrying the resolved role) underpins it.
+
+### Changed (breaking)
+
+- **Drift guard now fingerprints the whole contract.** `Session#manifest_etag` is renamed `contract_etag` and now digests `manifest.yaml` + `hooks/**/*.rb` + `schemas/**/*` ([ADR 0074](docs/architecture/decisions/0074-contract-etag-drift-guard.md)). A mid-session edit to any hook or schema raises `contract_drift` on the next MCP `tools/call`, where previously only a manifest edit did. The composite digest lives as `Etag.for_contract`.
+  - **Wire:** the `pulse` envelope key `manifest_etag` is renamed `contract_etag`.
+  - **Ruby:** `Textus::Session#manifest_etag` / `Textus::MCP::Session#manifest_etag` is renamed `contract_etag`. Embedders constructing a `Session` must pass `contract_etag:`.
+
+### Added
+
+- **`build` is surfaced to MCP** ([ADR 0076](docs/architecture/decisions/0076-build-gates-by-capability-actor-surface-to-mcp.md)) — previously CLI-only. `build` is transport-uniform, caller-agnostic, and self-elevating: it always runs as the manifest's `build`-capable actor (not the caller) and grants no authority over content, since it only recomputes the deterministic, content-addressed projection of already-accepted canon. Actor-resolution and the `BuildLock` moved out of the CLI verb into the shared `Write::Build` use-case (an `around :build_lock` resource), so single-writer serialization now spans **every** transport — closing a latent gap where the Ruby API path skipped the lock. The MCP catalog derives the new tool; `boot` auto-advertises it.
+- **`textus init --with-agent`** ([ADR 0077](docs/architecture/decisions/0077-init-with-agent-profile.md)) — an opt-in profile that scaffolds a connectable agent setup on top of the neutral store: `knowledge.project` + `knowledge.runbooks` entries (with their schemas), an `artifacts.orientation` derived entry that projects them to `CLAUDE.md`/`AGENTS.md`, and a write-once starter `.mcp.json` at the project root. The default `init` (no flag) is unchanged and stays vendor-neutral; under the flag, `init` writes exactly one file outside `.textus/` (`.mcp.json`, never clobbered if present). Paired with `build` over MCP, an agent can edit `knowledge.*` and rebuild its own orientation without leaving the conversation.
+- **`:session_opened` hook event** ([ADR 0075](docs/architecture/decisions/0075-session-opened-connect-event.md)) — fires once per MCP connection at `initialize` with `ctx:, role:, cursor:` (the resolved connection role). Use it for connect-time, role-keyed behavior (session logging, context priming). Distinct from `:store_loaded` (process-time, default role).
+
 ## 0.46.0 — 2026-06-03 — Container is the single source of truth
 
 No `textus/3` wire-format change. Internal refactor of the composition root. The 7-field capability set (`manifest, file_store, schemas, root, audit_log, events, rpc`) was previously spelled out four times — `Container`'s `Data.define`, `Store`'s ivar assignments, `Store`'s `attr_reader`s, and `Container.from_store`. It now lives in exactly one place.

data/SPEC.md

@@ -653,6 +653,7 @@ end
 | `:entry_renamed`        | pubsub  | ctx:, key:, from_key:, to_key:, envelope:                 | (discarded)           | logged        |
 | `:proposal_rejected`    | pubsub  | ctx:, key:, target_key:                                   | (discarded)           | logged        |
 | `:store_loaded`         | pubsub  | ctx:                                                      | (discarded)           | logged        |
+| `:session_opened`       | pubsub  | ctx:, role:, cursor:                                     | (discarded)           | logged        |
 | `:fetch_started`        | pubsub  | ctx:, key:, mode:                                         | (discarded)           | logged        |
 | `:fetch_failed`         | pubsub  | ctx:, key:, error_class:, error_message:                  | (discarded)           | logged        |
 | `:fetch_backgrounded`   | pubsub  | ctx:, key:, started_at:, budget_ms:                       | (discarded)           | logged        |
@@ -672,7 +673,7 @@ The three `:fetch_*` lifecycle events report the progress and failures of backgr
 
 Declaring `store:` instead of `caps:` in an RPC callable will pass registration but raise `UsageError` at call time (`Hooks::RpcRegistry#invoke` rejects `store:` — there is no shim).
 
-The primary entity is always `key:` (for `:proposal_accepted`, `key:` is the pending key being accepted and `target_key:` is the destination). For `:entry_renamed`, `key:` is present and equals `to_key:` — it is the entry's post-move home, present so `keys:` glob filters route correctly; `from_key:` is the prior key. For `:proposal_rejected`, `key:` is the pending key being rejected. For `:store_loaded`, no key — the event observes store readiness, not an entry.
+The primary entity is always `key:` (for `:proposal_accepted`, `key:` is the pending key being accepted and `target_key:` is the destination). For `:entry_renamed`, `key:` is present and equals `to_key:` — it is the entry's post-move home, present so `keys:` glob filters route correctly; `from_key:` is the prior key. For `:proposal_rejected`, `key:` is the pending key being rejected. For `:store_loaded`, no key — the event observes store readiness, not an entry. For `:session_opened`, no key — it fires once per MCP connection at `initialize` with the connection's resolved `role:` and boot `cursor:` (ADR 0075); distinct from `:store_loaded`, which fires once per process at `Store#initialize` under the default role.
 
 **RPC mode** — exactly one handler per (event, name). The manifest references the handler by name (`intake.handler: NAME`, `compute.transform: NAME`). Failure or timeout aborts the calling operation.
 
@@ -909,7 +910,7 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 
 `read_verbs` is derived from the MCP verb catalog — the verbs the agent can actually call over its transport — so it lists the read/discovery verbs (`schema_show` for an entry's field shape, `rule_explain` for its freshness/guard policy, and the graph reads `where`/`deps`/`rdeps`, ADR 0060) and never the CLI-only `audit`/`freshness`/`doctor` (ADR 0056). An agent learns an entry's `_meta` shape by calling the `schema_show` verb before a `put`/`propose`, not by shelling out to a CLI. The graph reads `deps`/`rdeps` return a structured `{key, deps}`/`{key, rdeps}` envelope on every surface (CLI, Ruby, MCP) — a hash, not a bare array, consistent with the other structured read responses such as `where` (ADR 0060 amendment).
 
-The agent's MCP write surface includes the single-key `delete` and `mv` tools alongside their bulk `key_delete_prefix`/`key_mv_prefix` cousins (ADR 0060 amendment). All of these apply by default; `dry_run: true` is a uniform opt-in preview that returns a Plan without mutating (ADR 0071 — verbs are actions, dry-run is opt-in on every surface). Single-key `delete` additionally accepts an optional `if_etag` optimistic-concurrency check. The blast-radius reads (`where`/`deps`/`rdeps`) remain on MCP so an agent can look before it leaps. The promotion verbs `accept` and `reject` are also on MCP (ADR 0072): they are gated by the `author_held` capability floor, not by transport absence — a default-`agent` connection is refused, while a connection launched as a role holding `author` (`--as`/`TEXTUS_ROLE`/`.textus/role`, resolved once at launch per ADR 0040) can promote, closing the propose→accept loop over one transport.
+The agent's MCP write surface includes the single-key `delete` and `mv` tools alongside their bulk `key_delete_prefix`/`key_mv_prefix` cousins (ADR 0060 amendment). All of these apply by default; `dry_run: true` is a uniform opt-in preview that returns a Plan without mutating (ADR 0071 — verbs are actions, dry-run is opt-in on every surface). Single-key `delete` additionally accepts an optional `if_etag` optimistic-concurrency check. The blast-radius reads (`where`/`deps`/`rdeps`) remain on MCP so an agent can look before it leaps. The promotion verbs `accept` and `reject` are also on MCP (ADR 0072): they are gated by the `author_held` capability floor, not by transport absence — a default-`agent` connection is refused, while a connection launched as a role holding `author` (`--as`/`TEXTUS_ROLE`/`.textus/role`, resolved once at launch per ADR 0040) can promote, closing the propose→accept loop over one transport. `build` is also on MCP (ADR 0076): it is caller-agnostic and self-elevating — it always runs as the manifest's `build`-capable actor regardless of the calling role, grants no authority over content (build is a pure, idempotent function of already-accepted canon, ADR 0070), and is serialized by a shared single-writer lock across all transports so a concurrent CLI or background build cannot collide with an MCP-triggered one.
 
 `latest_seq` is the current high-water mark of the audit log; agents should use it as the starting cursor for `pulse`.
 
@@ -922,13 +923,13 @@ The agent's MCP write surface includes the single-key `delete` and `mv` tools al
   "stale":          [ "artifacts.marketplace" ],
   "pending_review": [ "proposals.proposal.123" ],
   "doctor":         { "ok": true, "warn": 0, "fail": 0 },
-  "manifest_etag":  "sha256:1f3a…",
+  "contract_etag":  "sha256:1f3a…",
   "next_due_at":    "2026-06-01T09:00:00Z",
   "hook_errors":    [ { "seq": 1844, "event": "after_put", "hook": "notify", "key": "knowledge.notes.x", "error_class": "Timeout::Error", "error_message": "…", "at": "..." } ]
 }
 ```
 
-`cursor` is the new high-water mark; pass it as `--since` on the next call. `changed` is sourced from `audit --seq-since`. `stale` is sourced from `freshness`. `pending_review` lists all keys in the queue zone. `doctor` is an `{ok, warn, fail}` count summary. `manifest_etag` is the `sha256:`-prefixed content hash of the manifest (ADR 0025), for cheap change-detection. `next_due_at` is the soonest upcoming freshness deadline across entries (ISO-8601, or `null` if none). `hook_errors` lists hook failures recorded since the cursor. When `--since` is below the oldest available seq (due to audit log rotation), pulse returns `CursorExpired`.
+`cursor` is the new high-water mark; pass it as `--since` on the next call. `changed` is sourced from `audit --seq-since`. `stale` is sourced from `freshness`. `pending_review` lists all keys in the queue zone. `doctor` is an `{ok, warn, fail}` count summary. `contract_etag` is the `sha256:`-prefixed composite content hash of the contract — the manifest plus hooks and schemas (ADR 0074, via ADR 0025) — for cheap change-detection. `next_due_at` is the soonest upcoming freshness deadline across entries (ISO-8601, or `null` if none). `hook_errors` lists hook failures recorded since the cursor. When `--since` is below the oldest available seq (due to audit log rotation), pulse returns `CursorExpired`.
 
 **`put` input** (read from stdin when `--stdin` is given):
 

data/docs/architecture/README.md

@@ -237,7 +237,7 @@ soul (skill/agent)  ──▶  gate (CLI | MCP)  ──▶  Store  ──▶  me
 Two transports, one façade:
 
 - **CLI** — human/script surface. `textus boot`, `textus pulse --since=N`, `textus get/put/...`.
-- **MCP** — agent surface. `textus mcp serve` runs a stdio JSON-RPC 2.0 server speaking MCP draft 2024-11-05. Tools are auto-derived from the manifest. Session state (cursor, role, manifest_etag) is server-side.
+- **MCP** — agent surface. `textus mcp serve` runs a stdio JSON-RPC 2.0 server speaking MCP draft 2024-11-05. Tools are auto-derived from the manifest. Session state (cursor, role, contract_etag) is server-side.
 
 Both transports call `store.<verb>(..., role:)` (or `store.as(role).<verb>(...)`). No duplicate logic.
 
@@ -247,7 +247,7 @@ The agent loop (cadence guide in [`agents-mcp.md`](../how-to/agents-mcp.md)):
 2. **Per turn:** `pulse(since=cursor)` → `{cursor, changed, stale, pending_review, doctor}`.
 3. **On demand:** `get`, `put`, `propose`, `fetch`, `schema_show`, `rule_explain`.
 
-Manifest drift surfaces as `ContractDrift` (manifest_etag mismatch); audit cursor falls off the keep window as `CursorExpired`. Both signal "call `boot` again."
+Contract drift surfaces as `ContractDrift` (contract_etag mismatch — a change to the manifest, hooks, or schemas; ADR 0074); audit cursor falls off the keep window as `CursorExpired`. Both signal "call `boot` again."
 
 ## Hooks event catalog
 

data/lib/textus/cli/verb/build.rb

@@ -7,16 +7,7 @@ module Textus
         option :prefix, "--prefix=K"
 
         def invoke(store)
-          role = store.manifest.policy.actor_for("build") or
-            raise UsageError.new(
-              "no role holds the 'build' capability",
-              hint: "declare a role with `can: [build]` in .textus/manifest.yaml",
-            )
-          Textus::Ports::BuildLock.with(root: store.root) do
-            ops = store.as(role)
-            result = ops.build(prefix: prefix)
-            emit(result)
-          end
+          emit(store.as(resolved_role(store)).build(prefix: prefix))
         end
       end
     end

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

@@ -4,11 +4,13 @@ module Textus
       class Init < Verb
         command_name "init"
 
+        option :with_agent, "--with-agent"
+
         def self.needs_store? = false
 
         def call(_store)
           target = File.join(@cwd, ".textus")
-          emit(Textus::Init.run(target))
+          emit(Textus::Init.run(target, with_agent: !!with_agent))
         end
       end
     end

data/lib/textus/contract/resources/build_lock.rb

@@ -0,0 +1,17 @@
+module Textus
+  module Contract
+    module Resources
+      # Serializes builds across every surface (CLI, MCP, Ruby). Previously the
+      # CLI verb wrapped each build in a BuildLock by hand; lifting it into the
+      # contract means the MCP surface inherits the single-writer guarantee and
+      # cannot collide with a concurrent CLI or background build.
+      class BuildLock
+        def wrap(scope:, inputs:, session: nil) # rubocop:disable Lint/UnusedMethodArgument
+          Textus::Ports::BuildLock.with(root: scope.container.root) { yield(inputs) }
+        end
+      end
+    end
+  end
+end
+
+Textus::Contract::Around.register(:build_lock, Textus::Contract::Resources::BuildLock.new)

data/lib/textus/etag.rb

@@ -9,5 +9,28 @@ module Textus
     def self.for_file(path)
       for_bytes(File.binread(path))
     end
+
+    # The fingerprint of everything an agent's boot orientation depends on:
+    # the manifest PLUS the executable contract — hooks and schemas. A
+    # mid-session edit to any of these makes the cached orientation stale, so
+    # the session must re-boot (ADR 0074). The composite is one digest over the
+    # sorted per-file listing, so it is order-stable.
+    def self.for_contract(root)
+      listing = contract_files(root).map do |path|
+        rel = path.delete_prefix(root).delete_prefix("/")
+        "#{rel}:#{for_file(path)}"
+      end.join("\n")
+      for_bytes(listing)
+    end
+
+    # manifest.yaml, then every hook and schema file. Dir.glob already returns
+    # sorted paths (Ruby 3.0+), keeping the digest independent of FS order.
+    def self.contract_files(root)
+      [
+        File.join(root, "manifest.yaml"),
+        *Dir.glob(File.join(root, "hooks", "**", "*.rb")),
+        *Dir.glob(File.join(root, "schemas", "**", "*")).select { |f| File.file?(f) },
+      ]
+    end
   end
 end

data/lib/textus/hooks/catalog.rb

@@ -20,6 +20,7 @@ module Textus
         proposal_rejected: %i[ctx key target_key],
         file_published: %i[ctx key envelope source target],
         store_loaded: %i[ctx],
+        session_opened: %i[ctx role cursor],
         fetch_started: %i[ctx key mode],
         fetch_failed: %i[ctx key error_class error_message],
         fetch_backgrounded: %i[ctx key started_at budget_ms],

data/lib/textus/init/templates/orientation_reducer.rb

@@ -0,0 +1,17 @@
+# Reducer that reshapes the raw projection rows into the keys the
+# orientation.mustache template references. Without this, the template
+# would only have access to the flat rows list.
+Textus.hook do |reg|
+  reg.on(:transform_rows, :orientation_reducer) do |rows:, **|
+    project_row = rows.find { |r| r["_key"] == "knowledge.project" } || {}
+    runbook_rows = rows.select { |r| r["_key"]&.start_with?("knowledge.runbooks.") }
+
+    {
+      "project" => {
+        "name" => project_row["name"],
+        "description" => project_row["description"]
+      },
+      "runbooks" => runbook_rows.map { |r| { "name" => r["name"], "description" => r["description"] } }
+    }
+  end
+end

data/lib/textus/init.rb

@@ -94,13 +94,36 @@ module Textus
       Events: :resolve_intake, :transform_rows, :validate (rpc — return value used)
               :entry_put, :entry_deleted, :entry_fetched, :entry_renamed,
               :build_completed, :proposal_accepted, :proposal_rejected,
-              :file_published, :store_loaded,
+              :file_published, :store_loaded, :session_opened,
               :fetch_started, :fetch_failed, :fetch_backgrounded (pub-sub — return discarded)
 
       See SPEC.md §5.10 for the full table.
     MD
 
-    def self.run(target_root)
+    AGENT_ENTRIES = <<~YAML.gsub(/^/, "  ")
+      # --with-agent profile: project facts + runbooks feed the orientation
+      # projection below, which `textus build` renders to CLAUDE.md/AGENTS.md.
+      - { key: knowledge.project, path: knowledge/project.md, zone: knowledge, schema: project, owner: human:self, kind: leaf }
+      - { key: knowledge.runbooks, path: knowledge/runbooks, zone: knowledge, schema: runbook, owner: human:self, nested: true, kind: nested }
+      - key: artifacts.orientation
+        path: artifacts/orientation.md
+        zone: artifacts
+        template: orientation.mustache
+        inject_boot: true
+        publish:
+          to:
+          - CLAUDE.md
+          - AGENTS.md
+        compute:
+          kind: projection
+          select:
+          - knowledge.project
+          - knowledge.runbooks
+          transform: orientation_reducer
+        kind: derived
+    YAML
+
+    def self.run(target_root, with_agent: false)
       raise UsageError.new(".textus/ already exists at #{target_root}") if File.directory?(target_root)
 
       FileUtils.mkdir_p(File.join(target_root, "schemas"))
@@ -115,12 +138,52 @@ module Textus
       scaffold_dir = File.expand_path("init/templates", __dir__)
       File.write(File.join(target_root, "hooks", "machine_intake.rb"),
                  File.read(File.join(scaffold_dir, "machine_intake.rb")))
-      File.write(File.join(target_root, "manifest.yaml"), DEFAULT_MANIFEST)
+      File.write(File.join(target_root, "manifest.yaml"), manifest_yaml(with_agent: with_agent))
+      mcp_status = nil
+      if with_agent
+        scaffold_agent_profile(target_root, scaffold_dir)
+        mcp_status = write_mcp_config(target_root, scaffold_dir)
+      end
       FileUtils.mkdir_p(Textus::Layout.audit_dir(target_root))
       FileUtils.mkdir_p(Textus::Layout.state(target_root))
       FileUtils.mkdir_p(Textus::Layout.locks(target_root))
       File.write(File.join(target_root, ".gitignore"), derived_gitignore(target_root))
-      { "protocol" => PROTOCOL, "initialized" => target_root }
+      result = { "protocol" => PROTOCOL, "initialized" => target_root, "profile" => with_agent ? "agent" : "default" }
+      result["mcp_config"] = mcp_status if with_agent
+      result
+    end
+
+    # Composes the agent profile by inserting AGENT_ENTRIES immediately before the
+    # top-level `rules:` block of DEFAULT_MANIFEST — that block is load-bearing for
+    # this `.sub`; removing it from DEFAULT_MANIFEST would silently drop the entries.
+    def self.manifest_yaml(with_agent:)
+      return DEFAULT_MANIFEST unless with_agent
+
+      DEFAULT_MANIFEST.sub(/^rules:/, "#{AGENT_ENTRIES}rules:")
+    end
+
+    # Copies the proven orientation bundle into a freshly-init'd store.
+    def self.scaffold_agent_profile(target_root, scaffold_dir)
+      {
+        "project.schema.yaml" => File.join("schemas", "project.yaml"),
+        "runbook.schema.yaml" => File.join("schemas", "runbook.yaml"),
+        "orientation.mustache" => File.join("templates", "orientation.mustache"),
+        "orientation_reducer.rb" => File.join("hooks", "orientation_reducer.rb"),
+      }.each do |src, dest|
+        File.write(File.join(target_root, dest), File.read(File.join(scaffold_dir, src)))
+      end
+    end
+
+    # The one file init writes outside .textus/: a starter .mcp.json at the
+    # project root. Write-once — never clobber a hand-authored config. The
+    # command form assumes a gem-installed `textus` on PATH; the user owns
+    # the file after this first write.
+    def self.write_mcp_config(target_root, scaffold_dir)
+      dest = File.join(File.dirname(target_root), ".mcp.json")
+      return "skipped" if File.exist?(dest)
+
+      File.write(dest, File.read(File.join(scaffold_dir, "mcp.json")))
+      "written"
     end
 
     # The store's `.gitignore` is generated, never hand-kept (ADR 0038), and now

data/lib/textus/mcp/server.rb

@@ -59,7 +59,17 @@ module Textus
           role: @role,
           cursor: @store.audit_log.latest_seq,
           propose_zone: propose_zone,
-          manifest_etag: manifest_etag,
+          contract_etag: contract_etag,
+        )
+
+        # ADR 0075: announce the connection to connect-time hooks with the
+        # resolved role. Distinct from :store_loaded (fired at Store.new under
+        # the default role, before any connection's role is known).
+        @store.events.publish(
+          :session_opened,
+          ctx: Hooks::Context.new(scope: @store.as(@role)),
+          role: @role,
+          cursor: @session.cursor,
         )
 
         emit_result(rid, {
@@ -79,7 +89,7 @@ module Textus
           return
         end
 
-        @session.check_etag!(manifest_etag)
+        @session.check_etag!(contract_etag)
 
         name = params["name"]
         args = params["arguments"] || {}
@@ -100,8 +110,8 @@ module Textus
         emit_error(rid, -32_603, "internal: #{e.class}: #{e.message}")
       end
 
-      def manifest_etag
-        @store.file_store.etag(File.join(@store.root, "manifest.yaml"))
+      def contract_etag
+        Textus::Etag.for_contract(@store.root)
       end
 
       def emit_result(rid, result)

data/lib/textus/read/pulse.rb

@@ -33,7 +33,7 @@ module Textus
           "stale" => freshness_rows.select { |r| r[:status] == :stale }.map { |r| r[:key] },
           "pending_review" => review_keys,
           "doctor" => doctor_summary,
-          "manifest_etag" => manifest_etag,
+          "contract_etag" => contract_etag,
           "next_due_at" => soonest_due(freshness_rows),
           "hook_errors" => hook_errors_since(since),
         }
@@ -76,8 +76,8 @@ module Textus
         }
       end
 
-      def manifest_etag
-        @file_store.etag(File.join(@root, "manifest.yaml"))
+      def contract_etag
+        Textus::Etag.for_contract(@root)
       end
 
       def hook_errors_since(seq)

data/lib/textus/session.rb

@@ -1,16 +1,17 @@
 module Textus
   # The agent session: per-connection (MCP), per-process (CLI), or per-loop
-  # (Ruby) orientation state — the audit cursor plus the manifest etag and
+  # (Ruby) orientation state — the audit cursor plus the contract etag and
   # propose_zone captured at boot. Immutable Data value; advance_cursor
-  # returns a new instance. ADR 0036.
-  Session = Data.define(:role, :cursor, :propose_zone, :manifest_etag) do
+  # returns a new instance. ADR 0036; contract_etag widened in ADR 0074.
+  Session = Data.define(:role, :cursor, :propose_zone, :contract_etag) do
     def advance_cursor(new_cursor) = with(cursor: new_cursor)
 
     def check_etag!(observed_etag)
-      return if observed_etag == manifest_etag
+      return if observed_etag == contract_etag
 
       raise Textus::MCP::ContractDrift.new(
-        "manifest changed (was #{short_etag(manifest_etag)}, now #{short_etag(observed_etag)}); re-run boot",
+        "contract changed (manifest/hooks/schemas were #{short_etag(contract_etag)}, " \
+        "now #{short_etag(observed_etag)}); re-run boot",
       )
     end
 

data/lib/textus/store.rb

@@ -55,7 +55,7 @@ module Textus
         role: role,
         cursor: audit_log.latest_seq,
         propose_zone: manifest.policy.propose_zone_for(role),
-        manifest_etag: file_store.etag(File.join(root, "manifest.yaml")),
+        contract_etag: Textus::Etag.for_contract(root),
       )
     end
 

data/lib/textus/version.rb

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

data/lib/textus/write/build.rb

@@ -14,8 +14,9 @@ module Textus
 
       verb     :build
       summary  "materialize derived entries; publish_to and publish_tree fan out copies"
-      surfaces :cli
+      surfaces :cli, :mcp
       cli      "build"
+      around   :build_lock
       arg :prefix, String, required: false, description: "limit the build to keys under this prefix"
 
       def initialize(container:, call:)
@@ -25,10 +26,21 @@ module Textus
       end
 
       def call(prefix: nil)
+        build_role = @manifest.policy.actor_for("build") or
+          raise Textus::UsageError.new(
+            "no role holds the 'build' capability",
+            hint: "declare a role with `can: [build]` in .textus/manifest.yaml",
+          )
+        build_call = Textus::Call.build(
+          role: build_role,
+          correlation_id: @call.correlation_id,
+          dry_run: @call.dry_run,
+        )
+
         built  = []
         leaves = []
         pruned = []
-        context = build_context
+        context = build_context(build_call)
 
         @manifest.data.entries.each do |mentry|
           next if prefix && !entry_matches_prefix?(mentry, prefix)
@@ -49,11 +61,11 @@ module Textus
 
       private
 
-      def build_context
+      def build_context(call)
         Textus::Manifest::Entry::Base::PublishContext.new(
           container: @container,
-          call: @call,
-          reader: reader,
+          call: call,
+          reader: reader(call),
         )
       end
 
@@ -70,8 +82,8 @@ module Textus
         end
       end
 
-      def reader
-        @reader ||= Textus::Read::Get.new(container: @container, call: @call)
+      def reader(call)
+        Textus::Read::Get.new(container: @container, call: call)
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.46.0
+  version: 0.47.0
 platform: ruby
 authors:
 - Patrick
@@ -147,6 +147,7 @@ files:
 - lib/textus/contract.rb
 - lib/textus/contract/around.rb
 - lib/textus/contract/binder.rb
+- lib/textus/contract/resources/build_lock.rb
 - lib/textus/contract/resources/cursor.rb
 - lib/textus/contract/sources.rb
 - lib/textus/contract/view.rb
@@ -222,6 +223,7 @@ files:
 - lib/textus/hooks/signature.rb
 - lib/textus/init.rb
 - lib/textus/init/templates/machine_intake.rb
+- lib/textus/init/templates/orientation_reducer.rb
 - lib/textus/key/distance.rb
 - lib/textus/key/grammar.rb
 - lib/textus/key/path.rb