textus 0.55.1 → 0.55.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27ac7fc2922b98c97c7873939781a13330e0765b7f0521449aa4871c414fc201
-  data.tar.gz: 055ed0684590d9ca8cf5e2ad49fc17ee05c70b8cbaa5f8b589b9bb9a3de99f0e
+  metadata.gz: 68d4176e50949378dcf62b98617c28bcf6f553c196b24f9263a97d8d5c6f382f
+  data.tar.gz: 7de0c2d9ee56d71e09cc0821d19b8ffcc00e3573fccc20ef3e610988ec5ff43c
 SHA512:
-  metadata.gz: 437568a688e1ff1b6f9786d1965633e9dfa69be5b6f7450ffeeaecb3c0be5a6729e94851f2066a26e2d313f8d23335d2ff12b83ad5e73718b27e784887c9ceb4
-  data.tar.gz: a8f4167af7c3ce315301996d3d3fedc13139f8eae4804b445ec4ed930da0d284ec96cab3467af1169ce8f6a64288d6f1d805bbfad60c0acb949f62e03ce1322d
+  metadata.gz: 34322a4bfd59c817bdbaec436caba5cd8a25a7896065e16633270eb22bed7db20af339f45f7ee8ed632732f3679469328939d45490e3a6ce3528f654b00feba9
+  data.tar.gz: 6c4f94a584d8334e7dc68e543852bb687fa662c6e6eb1334cadf9d70ff01576552f71d773d462f03f3c4f0955496fe094c167df090880f473d3e850469f4c3cd

data/CHANGELOG.md

@@ -904,7 +904,7 @@ Protocol remains `textus/3`.
   `refresh`, `refresh_stale`, `schema`, `rules`). Session state (cursor,
   role, manifest_etag) held server-side. Manifest drift surfaces as
   `ContractDrift` (-32001); cursor expiry as `CursorExpired` (-32002).
-  See [`docs/reference/mcp.md`](docs/reference/mcp.md) and [ADR 0015](docs/architecture/decisions/0015-agent-gate-mcp.md).
+  See [ADR 0015](docs/architecture/decisions/0015-agent-gate-mcp.md).
 - `examples/claude-plugin/.mcp.json` and migrated skills/commands/agents —
   zero `textus <verb>` shell strings remain in plugin markdown.
 

data/README.md

@@ -39,7 +39,7 @@ flowchart LR
     end
 
     human -->|author| knowledge["knowledge<br/>(canon)"]
-    agent -->|keep| notebook["notebook<br/>(workspace)"]
+    agent -->|keep| scratchpad["scratchpad<br/>(workspace)"]
     agent -->|propose| proposals["proposals<br/>(queue)"]
     automation -->|drain| artifacts["artifacts<br/>(machine)"]
     human -->|ingest| raw["raw<br/>(intake)"]
@@ -68,7 +68,7 @@ The point of those lanes is to **build context you can trust**. Place each lane
                        LOW TRUST                     HIGH TRUST
                       (unreviewed)                (authoritative)
               ┌──────────────────────────┬───────────────────────────────┐
-DURABLE       │  notebook                │  knowledge  ★ the goal        │
+DURABLE       │  scratchpad                │  knowledge  ★ the goal        │
 (kept)        │  agent's working truth   │  canon — a human authors      │
               │  durable, but low-trust  │  here · the context you ship  │
               ├──────────────────────────┼───────────────────────────────┤
@@ -84,12 +84,12 @@ Without coordination, they overwrite each other and nothing remembers why. textu
 
 ```
 knowledge/   author only            — who you are, what you decide, how you sound
-notebook/    keep only              — agent's own durable lane (bytes climb to knowledge only via propose→accept)
+scratchpad/    keep only              — agent's own durable lane (bytes climb to knowledge only via propose→accept)
 proposals/   propose (agent+human) — proposals waiting on a human accept
 artifacts/   converge only         — machine-maintained: computed outputs + external inputs
 ```
 
-An agent that tries to write directly into `knowledge/` gets `write_forbidden`. It writes to `proposals/` (to change authoritative content) or its own `notebook/` (for working memory). You accept the good proposals; textus promotes them, records the move, and audits both halves. Stable per-entry `uid:` means a reorganization doesn't break references. A monotonic audit cursor (`textus pulse --since=N`) means the next session — possibly a different agent, possibly a different model — picks up exactly where the last one left off.
+An agent that tries to write directly into `knowledge/` gets `write_forbidden`. It writes to `proposals/` (to change authoritative content) or its own `scratchpad/` (for working memory). You accept the good proposals; textus promotes them, records the move, and audits both halves. Stable per-entry `uid:` means a reorganization doesn't break references. A monotonic audit cursor (`textus pulse --since=N`) means the next session — possibly a different agent, possibly a different model — picks up exactly where the last one left off.
 
 That's the load-bearing claim: **coordination is a protocol invariant, not a library convenience.**
 
@@ -156,7 +156,7 @@ roles:
 
 lanes:
   - { name: knowledge, kind: canon }      # author   — canonical truth
-  - { name: notebook,  kind: workspace }  # keep     — agent's own durable lane
+  - { name: scratchpad,  kind: workspace }  # keep     — agent's own durable lane
   - { name: proposals, kind: queue }      # propose  — proposals awaiting accept
   - { name: artifacts, kind: machine }    # converge — computed outputs + external inputs
 ```
@@ -170,7 +170,7 @@ lanes:
   .gitignore             # generated — ignores .state/ and any tracked:false entries
   data/                  # one dir per lane; kinds + capabilities are in the manifest above
     knowledge/           # e.g. identity (knowledge.identity.*), voice, decisions, notes
-    notebook/
+    scratchpad/
     proposals/
     artifacts/           # machine lane: computed outputs + external inputs
   .state/                  # disposable runtime state — gitignored, safe to delete (ADR 0038)
@@ -207,7 +207,7 @@ For a worked store — knowledge entries, a staged proposal, schemas, ERB templa
 - **Agent loop.** `textus boot` orients a fresh session; `textus pulse --since=N` is the per-turn heartbeat (changed entries, pending proposals, index etag for catalog drift detection). ([docs/how-to/agents-mcp.md](docs/how-to/agents-mcp.md))
 - **MCP surface.** The official `mcp` Ruby SDK drives the stdio JSON-RPC server; protocol version auto-negotiated up to `2025-11-25`. Wire textus into Claude Code, Cursor, or any MCP host in one config block.
 - **`textus doctor`.** Health checks across schemas, workflow registrations, keys, sentinels, and the audit log.
-- **`raw` lane and `ingest` verb.** Write-once intake lane for external URL bookmarks, files, and binary assets. Three source kinds (`url`/`file`/`asset`); daily key derivation; notebook stub per ingest. See "Intake and ingest" section below.
+- **`raw` lane and `ingest` verb.** Write-once intake lane for external URL bookmarks, files, and binary assets. Three source kinds (`url`/`file`/`asset`); daily key derivation; scratchpad stub per ingest. See "Intake and ingest" section below.
 
 ## CLI and lanes
 
@@ -281,8 +281,8 @@ textus ingest url agentskills-io-brainstorming \
 # see what landed in the raw lane
 textus list --lane=raw
 
-# a notebook stub was created alongside — annotate it
-textus get notebook.notes.raw
+# a scratchpad stub was created alongside — annotate it
+textus get scratchpad.notes.raw
 ```
 
 Stale produced entries are re-materialised by `drain`, not by reads — `get` is a pure read (ADR 0089).

data/SPEC.md

@@ -57,7 +57,7 @@ You **shape your own memory structure** inside `.textus/`. The protocol manages
 textus/4 names its concepts along six axes. Reviewers who internalize these can map any part of the spec to the right category:
 
 - **Actor** — who is interacting: roles such as `human`, `agent`, `automation`, each holding a set of capabilities (`propose`, `author`, `keep`, `converge`).
-- **Place** — where data lives: lanes such as `knowledge`, `notebook`, `raw`, `proposals`, `artifacts`.
+- **Place** — where data lives: lanes such as `knowledge`, `scratchpad`, `raw`, `proposals`, `artifacts`.
 - **Thing** — what is stored: entries, fields, keys.
 - **Operation** — how you act on things: RPC and CLI verbs (`get`, `put`, `drain`, `serve`, `ingest`, …).
 - **Event** — what gets fired after an operation: pub-sub events (`:entry_written`, `:entry_produced`, `:entry_published`, …).
@@ -111,7 +111,7 @@ The root is `.textus/` at the project working directory. A typical tree:
     sentinels/           # byte-copied publish bookkeeping (see §5.3)
   data/                  # ALL user content lives here
     knowledge/           # lane: knowledge (kind: canon — author-holders write)
-    notebook/            # lane: notebook (kind: workspace — keep-holders write; agent's own durable lane)
+    scratchpad/            # lane: scratchpad (kind: workspace — keep-holders write; agent's own durable lane)
     proposals/           # lane: proposals (kind: queue — propose-holders write)
     artifacts/           # lane: artifacts (kind: machine — converge-holders write)
     raw/                 # lane: raw (kind: raw — ingest-holders write; write-once)
@@ -149,7 +149,7 @@ roles:
 lanes:
   - name: knowledge
     kind: canon
-  - name: notebook
+  - name: scratchpad
     kind: workspace
     owner: agent              # optional, informational — agent's own lane
     desc: "agent's durable working memory; bytes climb to knowledge only via propose→accept"
@@ -241,7 +241,7 @@ Default scaffold — Setup-1 (roles `human=[author, propose, ingest]`, `agent=[p
 | Lane | `kind` | Required capability | Writable by (default) | Use case |
 |---|---|---|---|---|
 | `knowledge` | `canon` | `author` | `human` | Authored truth: identity, voice, decisions, network. |
-| `notebook` | `workspace` | `keep` | `agent` | Agent's own durable working memory. Bytes climb to `knowledge` only via propose→accept. |
+| `scratchpad` | `workspace` | `keep` | `agent` | Agent's own durable working memory. Bytes climb to `knowledge` only via propose→accept. |
 | `proposals` | `queue` | `propose` | `agent`, `human` | Proposals awaiting human review via `textus accept`. |
 | `artifacts` | `machine` | `converge` | `automation` | Computed outputs produced by `drain` via the workflow DSL. |
 | `raw` | `raw` | `ingest` | `human`, `agent`, `automation` | Write-once external source material: URL bookmarks, files, binary assets. |
@@ -284,7 +284,7 @@ Every successful write records the resolved role and a wall-clock timestamp in `
 
 #### 5.1.1 Capabilities
 
-Roles declare **capabilities** — verbs from a closed four-element set. A
+Roles declare **capabilities** — verbs from a closed five-element set. A
 manifest declares a `roles:` block mapping each role name to the capabilities
 it holds via `can:`:
 
@@ -296,7 +296,7 @@ roles:
   - { name: keeper,   can: [keep] }
 ```
 
-Capability allow-list: `propose`, `author`, `keep`, `converge`. The mapping from
+Capability allow-list: `propose`, `author`, `keep`, `converge`, `ingest`. The mapping from
 lane-kind to its required capability is a **bijection** (ADR 0091, which folded
 the former `quarantine` + `derived` kinds back into one `machine` kind — undoing
 the two-kind split of ADR 0090): each capability authorizes exactly one
@@ -308,8 +308,9 @@ lane-kind:
 | `keep` | `workspace` |
 | `propose` | `queue` |
 | `converge` | `machine` |
+| `ingest` | `raw` |
 
-A manifest naming a folded capability — `ingest` or `build`, or the pre-0088
+A manifest naming a folded capability — `build` or the pre-0088
 spelling `fetch` — in a `can:` list is rejected at load with a hint pointing to
 `converge` (ADR 0090, 0091, 0111).
 
@@ -425,7 +426,7 @@ The `raw` lane (`kind: raw`) is a write-once intake lane for external source mat
 
 **`access` field** — entries MAY carry `source.access: public | private` (field is `maintained_by: human`). Set `private` for sources not safe to reproduce publicly.
 
-**Notebook stub** — every ingest creates a `notebook.notes` stub with a backlink (`Ingested from raw.<key>`) so the agent or human can annotate the ingested material without touching the write-once record.
+**Notebook stub** — every ingest creates a `scratchpad.notes` stub with a backlink (`Ingested from raw.<key>`) so the agent or human can annotate the ingested material without touching the write-once record.
 
 **Example — URL bookmark:**
 
@@ -689,7 +690,7 @@ Every successful CLI response (`--output=json`) is a single JSON envelope:
   "schema_ref": "person",
   "uid": "a1b2c3d4e5f60718",
   "sources": [
-    "raw.2026.06.20.url-mcp-spec"
+    { "key": "raw.2026.06.20.url-mcp-spec", "etag": "sha256:1a2b…", "suspended": false }
   ],
   "stale": false,
   "stale_reason": null,
@@ -700,7 +701,7 @@ Every successful CLI response (`--output=json`) is a single JSON envelope:
 **Field rules:**
 - `protocol` MUST be the exact string `textus/4`.
 - `key` MUST be the canonical resolved key.
-- `lane` MUST be one of the lanes declared in the manifest (`knowledge`, `notebook`, `feeds`, `proposals`, `artifacts` in the default Setup-1 scaffold).
+- `lane` MUST be one of the lanes declared in the manifest (`knowledge`, `scratchpad`, `proposals`, `artifacts`, `raw` in the default Setup-1 scaffold).
 - `path` MUST be an absolute filesystem path.
 - `format` MUST be one of `markdown`, `json`, `yaml`, `text` (§5.12). Absent envelopes are treated as `markdown` for back-compat.
 - `body` is the raw on-disk bytes as a UTF-8 string for every format.
@@ -708,7 +709,7 @@ Every successful CLI response (`--output=json`) is a single JSON envelope:
 - `etag` MUST be `sha256:<hex>` of the raw file bytes, computed identically for every format.
 - `schema_ref` MAY be `null` for entries in subtrees with `schema: null`.
 - `uid` is the stable Textus UID (§7) if the entry carries one, else `null`. Always present in the envelope.
-- `sources` is an array of raw-lane key strings. Present only when non-empty. Each string starts with `raw.`.
+- `sources` is an array of source objects. Each object has `key` (the referenced entry's key), `etag` (sha256 snapshot taken at write time, or absent when no snapshot exists), and `suspended` (`true` when the referenced entry's current on-disk etag differs from the stored snapshot — the source changed after this entry was last written). Present only when non-empty.
 - `stale` is `true` when the entry's `source.ttl` has elapsed and the entry has not yet been re-materialised; `false` otherwise. Only populated for produced entries with a declared `ttl`; always `false` for other entries.
 - `stale_reason` is a short human-readable string describing why the entry is stale (e.g. `"ttl_exceeded"`, `"never_fetched"`), or `null` when `stale` is `false`.
 - `fetching` is `true` when a background re-pull is in flight for this entry; `false` otherwise. Callers observing `stale: true, fetching: true` SHOULD retry after a short delay.
@@ -791,7 +792,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 retention/guard policy, and the graph reads `where`/`deps`/`rdeps`, ADR 0060) and never the CLI-only `audit`/`doctor`, nor `freshness` (the Ruby-only internal lifecycle scan, ADR 0085) (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 `key_delete` and `key_mv` tools alongside their bulk `key_delete_prefix`/`key_mv_prefix` cousins (ADR 0060 amendment; the single-key tools were renamed from `delete`/`mv` to share the `key_` family stem in ADR 0082, which also removed the `migrate` YAML-plan orchestrator — its `zone_mv`/`key_mv_prefix`/`key_delete_prefix` ops remain individually callable). 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 `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. `drain` is also on MCP (ADR 0076, ADR 0087, ADR 0110): it is caller-agnostic and its produce jobs self-elevate — materialization always runs as the manifest's `converge`-capable actor regardless of the calling role, granting no authority over content (materialization is a pure, idempotent function of already-accepted canon, ADR 0070); the destructive retention sweep runs as the caller. Each produce job self-acquires the single-writer build lock, so a concurrent CLI, reactive, or background pass cannot collide with an MCP-triggered one — a held lock is a graceful soft-miss (ADR 0110).
+The agent's MCP write surface includes the single-key `key_delete` and `key_mv` tools alongside their bulk `key_delete_prefix`/`key_mv_prefix` cousins (ADR 0060 amendment; the single-key tools were renamed from `delete`/`mv` to share the `key_` family stem in ADR 0082, which also removed the `migrate` YAML-plan orchestrator — its `data_mv`/`key_mv_prefix`/`key_delete_prefix` ops remain individually callable). The structural mutation verbs (`key_mv`, `key_mv_prefix`, `key_delete_prefix`, `data_mv`) accept `dry_run: true` as an opt-in preview that returns a Plan without mutating (ADR 0071). `drain` does not support `dry_run` (it is async-only, ADR 0110). Single-key `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. `drain` is also on MCP (ADR 0076, ADR 0087, ADR 0110): it is caller-agnostic and its produce jobs self-elevate — materialization always runs as the manifest's `converge`-capable actor regardless of the calling role, granting no authority over content (materialization is a pure, idempotent function of already-accepted canon, ADR 0070); the destructive retention sweep runs as the caller. Each produce job self-acquires the single-writer build lock, so a concurrent CLI, reactive, or background pass cannot collide with an MCP-triggered one — a held lock is a graceful soft-miss (ADR 0110).
 
 `latest_seq` is the current high-water mark of the audit log; agents should use it as the starting cursor for `pulse`.
 
@@ -819,7 +820,7 @@ The agent's MCP write surface includes the single-key `key_delete` and `key_mv`
 
 `if_etag` is optional on both `put` and `key_delete`. When provided, the write fails with `etag_mismatch` if the on-disk file's etag differs. When omitted, the write is unconditional (last-writer-wins).
 
-The lifecycle scan behind `pulse.stale`/`pulse.next_due_at` reports, per entry, one verdict (`fresh`, `expired`, or `no_policy`) against each intake entry's `source.ttl`. ADR 0085 removed the standalone `freshness` verb that used to render these rows; the scan is now Ruby-only (consumed by `pulse` and the hook context), and human drill-down into a single entry's verdict is `textus get KEY` (carries `stale`/`stale_reason`) plus `textus rule_explain KEY` (the `source.ttl` and retention policy). `textus drain` enqueues the convergence jobs — produce every in-scope derived entry, re-pull every stale intake entry, and a retention sweep — then drains the queue to empty (§5.11). Convergence is async-only (ADR 0110): there is no `--dry-run`.
+The lifecycle scan runs per-entry at `get` time — each `get` response carries `stale`/`stale_reason` when the entry has a TTL rule. ADR 0085 removed the standalone `freshness` verb; human drill-down into a single entry's verdict is `textus get KEY` (carries `stale`/`stale_reason`) plus `textus rule_explain KEY` (the `source.ttl` and retention policy). `pulse` does not include a `stale` list. `textus drain` enqueues the convergence jobs — produce every in-scope derived entry, re-pull every stale intake entry, and a retention sweep — then drains the queue to empty (§5.11). Convergence is async-only (ADR 0110): there is no `--dry-run`.
 
 `textus accept K --as=human` promotes a pending entry into its target lane: it copies the patch body into the target key, deletes the pending entry, and writes one audit line per side (§audit). Only a role holding the `author` capability (the trust anchor — `human` by default) may invoke `accept`.
 

data/docs/architecture/README.md

@@ -41,7 +41,7 @@ surfaces/cli/     CLI command generation from contracts
   sources.rb      CLI-only input acquisition (stdin parsing, file sourcing, coercion)
 surfaces/mcp/     MCP server — stdio JSON-RPC 2.0, tools derived from contracts
 surfaces/role_scope.rb
-                  (Store#as(role)) — holds (container, role, dry_run, correlation_id);
+                  (Store#with_role(role)) — holds (container, role, dry_run, correlation_id);
                   all verb methods injected via define_method in textus.rb
 ```
 
@@ -214,7 +214,7 @@ Both are built from a `Container` via named constructors — `Writer.from(contai
 
 `Action::Get` is a **pure read** — it resolves the path, reads bytes, parses the envelope, and annotates a freshness verdict. It never ingests and never mutates.
 
-1. CLI/MCP surface calls `store.as(role).get(key)`.
+1. CLI/MCP surface calls `store.with_role(role).get(key)`.
 2. `Gate#dispatch` runs Auth → `Action::Get#call`.
 3. `Get` resolves path via `manifest.resolver`, reads bytes via `file_store`, parses the envelope, annotates `freshness` based on retention-rule TTL (if any).
 
@@ -222,7 +222,7 @@ Staleness is age-based (retention-rule TTL vs file mtime). A stale entry is retu
 
 ## Write path (`store.put(key, ...)`)
 
-1. CLI/MCP surface calls `store.as(role).put(key, meta:, body:)`.
+1. CLI/MCP surface calls `store.with_role(role).put(key, meta:, body:)`.
 2. `Gate#dispatch` runs Auth → `Action::Put#call`.
 3. `Put` validates, resolves manifest entry, delegates to `Envelope::Writer#put` (serialize → schema-validate → etag-check → FileStore#write → AuditLog#append).
 4. `WriteVerb#cascade_to_rdeps` enqueues `materialize` jobs for any entries with publish_tree that depend on the written key.

data/docs/reference/conventions.md

@@ -24,7 +24,7 @@ Recommended top-level layout — the spec allows alternatives, but this is what
   templates/      # ERB templates for publish rendering
   data/
     knowledge/    # authored truth: identity, voice, decisions — author-holders write
-    notebook/     # agent's own durable lane (workspace) — keep-holders write
+    scratchpad/     # agent's own durable lane (workspace) — keep-holders write
     proposals/    # AI proposals awaiting accept (propose)
     artifacts/    # computed outputs produced by drain — never edit by hand
     raw/          # write-once external source material (ingest)
@@ -126,7 +126,10 @@ For multi-writer environments, **always pass `if_etag`** on `put`. The gem treat
 The application layer is organised around three shapes — `Manifest` as a composition record, a single `Container` capability record handed to every use case, and a split envelope reader/writer. See [ADR 0018](../architecture/decisions/0018-manifest-carving.md), [ADR 0017](../architecture/decisions/0017-envelope-io-split.md), [ADR 0022](../architecture/decisions/0022-container-call-dispatcher.md), and [ADR 0023](../architecture/decisions/0023-uniform-use-case-shape.md).
 
 - **`Manifest` is a composition record** (`Data.define(:data, :resolver, :policy, :rules)`). Reach individual concerns through the field accessors: `manifest.data.entries`, `manifest.policy.permission_for(lane)`, `manifest.resolver.resolve(key)`, `manifest.rules.for(key)`.
-- **Use cases are plain `(container:, call:)` classes.** Each is a single class under `lib/textus/action/` with `def initialize(...)` (args from contract) and a `#call(container:, call:)` method; verbs are looked up in the static `Textus::Action::VERBS` table. `Container` is a `Dry::Struct` record bundling the wired ports + manifest (`manifest`, `file_store`, `schemas`, `root`, `audit_log`, `workflows`, `gate`); `Call` is the immutable per-invocation value (`role`, `correlation_id`, `now`, `dry_run`). All dispatch routes through `Gate#dispatch(spec:, inputs:, role:, correlation_id:, session:)` — the single seam that binds inputs via `Gate::Binder`, checks auth, and invokes the action. `store.as(role)` returns a `RoleScope` that forwards verbs to `Gate::dispatch`.
+- **`Store` is the single dispatch module.** `Store` holds the `Container`, the active role, session state (cursor, propose_lane, contract_etag), and dispatches verbs through `method_missing`. Each verb call (`store.get(key: ...)`, `store.put(key:, meta:, body:)`) goes through `VerbRegistry`, binds inputs via `Dispatch::Binder`, routes through `Dispatch::Pipeline` (middleware chain: auth, cascade, audit), and reaches the handler. `Store#with_role(role)` returns a new `Store` bound to that role.
+- **`Container` is a `Data.define` composition** of `Infrastructure` (`file_store`, `schemas`, `audit_log`, `job_store`, `geometry`) and `Coordination` (`manifest`, `workflows`, `pipeline`). Built in a single pass — no circular dependencies or lazy proxies.
+- **Dispatch lives in `lib/textus/dispatch/`**: `Dispatch.dispatch` orchestrates verb dispatch, `Dispatch::Pipeline` runs middleware then invokes the handler, `Dispatch::Binder` handles input binding (wire format, CLI flags, session defaults). Auth predicates moved to `Manifest::Policy::Predicates`.
+- **Handlers receive `container:`** and access I/O via `@container.pipeline.read/write/delete/move` and manifest config via `@container.manifest`.
 - **Write path is split**: `Envelope::IO::Reader` owns read/parse (existing-uid lookup, raw read, parse), and `Envelope::IO::Writer` owns put/delete/move + the audit-append invariant (every public method's final action is `@audit_log.append(...)`).
 
 The user-facing CLI surface, the wire envelope shape, and the protocol version (`textus/4`) are unchanged.

data/lib/textus/boot.rb

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

data/lib/textus/{gate → dispatch}/binder.rb

@@ -1,8 +1,5 @@
 module Textus
-  class Gate
-    # Raised when a required arg is absent from the bound input. Surface
-    # adapters translate this to their native error (MCP ToolError, CLI
-    # UsageError); a direct Ruby call lets it surface as-is.
+  module Dispatch
     class MissingArgs < Textus::Error
       attr_reader :spec, :missing
 
@@ -13,21 +10,22 @@ module Textus
       end
     end
 
-    # Validates and resolves a by-name inputs hash against a contract spec.
-    # Returns a flat hash with defaults and session_defaults filled in.
-    # Every caller receives the same shape — no positional/kwarg split.
     module Binder
+      Pending = Data.define(:spec, :inputs)
+
       module_function
 
-      def bind(spec, inputs, session: nil)
+      def command(spec, inputs)
+        Pending.new(spec: spec, inputs: inputs)
+      end
+
+      def bind(spec, inputs)
         missing = spec.required_args.reject { |a| inputs.key?(a.name) }
         raise MissingArgs.new(spec, missing) unless missing.empty?
 
         spec.args.each_with_object({}) do |a, h|
           if inputs.key?(a.name)
             h[a.name] = inputs[a.name]
-          elsif a.session_default && session
-            h[a.name] = session.public_send(a.session_default)
           elsif !a.default.nil?
             h[a.name] = a.default
           end

data/lib/textus/dispatch/contracts.rb

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

data/lib/textus/dispatch/handler_registry.rb

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