textus 0.30.0 → 0.35.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d84508fac499044df50d5fa793000fbd2249732c6b867f1b0f88535bfab4f083
-  data.tar.gz: 5069218d7c3c1a8360f4507bb99f94951e92a7d345ba4fb44ee72819fb4739e4
+  metadata.gz: e3e6ac596658c63369ce977d194a2c43d0a789cdfa97b04d100b70e572165e63
+  data.tar.gz: c3ed7085fa38777fdc6e8a38e8c4c8f4a51ce113065f24b42f596aa220acb9f3
 SHA512:
-  metadata.gz: abf8e5e74b77227f34bbc95dd38c1e9b8d716f56f1cda11664f3da284f417d8581a51e4c27accdcb88173c274ff1aa929443bb027b851a95cbced029fdf34852
-  data.tar.gz: bd63c95ae46643c063c1b035fc859957418f185795fc32b54f798b44779d825101d9f71667a85f518dacab6ffbcebe70bc5676c9ae24e80cc9de4fa44e38aa38
+  metadata.gz: a95c23aaf19216505f272f0262b66e1e7a3e01b3e78a2b8062ab827a3c8109a6d085348b3e1b1e664a41f0bbdeaf46cf736b47fe211495905445c9ae283c88fa
+  data.tar.gz: 453327b6cea08e0102e76dd22723d6f77a69d10f8d6810427e23934956d5a332b5f9d33b81d568bf7529cf8ab83bdfb6b323b447d2d9dead6d06c2b703e66ac4

data/ARCHITECTURE.md

@@ -1,242 +1,3 @@
-# Textus architecture
+# Architecture
 
-```
-┌─ Interface ────────────────────────────────────────────────┐
-│  CLI verbs:  store.<verb>(..., role:)                      │
-│              store.as(role).<verb>(...)                    │
-│                                # (put/get/refresh/…)       │
-│                                                            │
-│  MCP gate:   textus mcp serve — same use cases, JSON-RPC.  │
-└──────────────────────┬─────────────────────────────────────┘
-                       │
-┌─ Application ────────▼─────────────────────────────────────┐
-│  Call             (slim Data: role, correlation_id, now,   │
-│                    dry_run — request state only)           │
-│  Container        (single record — wired ports + manifest) │
-│  Dispatcher       (static VERBS table: verb → use-case)    │
-│  RoleScope        (Store#as(role) — forwards verb calls)   │
-│                                                            │
-│  read/{get,get_or_refresh,list,where,uid,schema_envelope,  │
-│        deps,rdeps,published,stale,validate_all,boot,doctor,│
-│        freshness,audit,blame,policy_explain,pulse}.rb      │
-│  write/{put,delete,mv,accept,reject,publish,               │
-│         materializer,authority_gate,                       │
-│         refresh_worker,refresh_orchestrator,refresh_all}   │
-│  maintenance/{migrate,key_mv_prefix,key_delete_prefix,     │
-│               zone_mv,rule_lint}.rb                        │
-│  envelope/io/{reader,writer}.rb  (split: parse vs persist) │
-│  projection.rb                                             │
-└──────────┬───────────────────────────────┬─────────────────┘
-           │ uses domain                   │ uses ports
-┌─ Domain ─▼─────────────────────────────────────────────────┐
-│  Authorizer         (manifest + role → allow / deny)       │
-│  Permission         (write/read predicate per zone)        │
-│  Freshness::{Policy,Verdict,Evaluator}                     │
-│  Staleness          (Generator/Intake checks)              │
-│  Action  Outcome  Sentinel                                 │
-│  Policy::{Promote,Refresh,Matcher,HandlerAllowlist,        │
-│           Predicates::{SchemaValid,AcceptAuthoritySigned}} │
-└──────────────────────────────────────────┬─────────────────┘
-                                           │ implements
-┌─ Infrastructure ─────────────────────────▼─────────────────┐
-│  Store              (composition root — wires ports,       │
-│                      vends a Container + dispatches verbs) │
-│  Storage::FileStore (bytes-only port: read/write/delete/   │
-│                      exists?/etag)                         │
-│  Manifest           (Data, Resolver, Policy, Rules)        │
-│  Schemas            (eager-load cache)                     │
-│  Ports::{AuditLog,AuditSubscriber,Publisher,Clock,         │
-│          Refresh::Lock,Refresh::Detached,BuildLock}        │
-│  Hooks::{EventBus,RpcRegistry,Loader,Context,FireReport,   │
-│          Signature,Builtin,ErrorLog}                       │
-│  Entry::{Markdown,Json,Yaml,Text}  (format strategies)     │
-└────────────────────────────────────────────────────────────┘
-
-   Dependency rule: arrows point DOWN. Domain performs no direct
-   File/Dir/Time.now I/O — all disk and clock access is routed through
-   injected ports (FileStat, Clock). Pure path math (File.join/dirname/
-   absolute_path?/expand_path/basename), Digest hashing of injected
-   bytes, and Time.parse of stored strings are NOT I/O and are allowed.
-   Application imports Domain + Ports.
-   Use cases are plain classes on (container:, call:).
-   Verbs are looked up in the static Dispatcher::VERBS table.
-```
-
-## How a verb becomes a method
-
-Each application use case is a plain class under `lib/textus/{read,write,maintenance}/`. The shape is uniform:
-
-```ruby
-module Textus
-  module Read
-    class Get
-      def initialize(container:, call:)
-        @container = container
-        @call      = call
-      end
-
-      def call(key)
-        ...
-      end
-    end
-  end
-end
-```
-
-Verbs are looked up in a static frozen table (`Textus::Dispatcher::VERBS`) that maps `:get → Textus::Read::Get`, `:put → Textus::Write::Put`, etc. `Store#put` / `Store#get` / `Store#as(role).<verb>(...)` instantiate the use case on `(container:, call:)` and invoke `#call`. Adding a new verb is **one entry in `Dispatcher::VERBS`** plus the class — no metaprogramming.
-
-The instantiate-and-call step itself has one home: `Dispatcher.invoke(verb, container:, call:, args:, kwargs:)` (ADR 0026). `RoleScope` builds the `Call` (request state) and delegates the dispatch to `Dispatcher.invoke`; the convention for invoking a uniform-shape use case lives next to the table that maps the verbs, not re-spelled in the caller. `Store`'s own verb loop is separate — it extracts the `role:` keyword and forwards to `as(role)`, a role-selection job distinct from invocation.
-
-`boot` and `doctor` are read verbs like any other: `Read::Boot` / `Read::Doctor`
-are thin `(container:, call:)` use cases that delegate to the `Textus::Boot` /
-`Textus::Doctor` report-builder libraries (`build(container:, ...)`). They are
-reached through `Dispatcher::VERBS`, not a special method on `RoleScope`.
-
-Two collaborators live outside the dispatcher because they're composed by other use cases, not invoked as verbs:
-
-- `Write::RefreshOrchestrator` — composes `RefreshWorker` with the freshness `Action` returned by `Domain::Freshness`.
-- `Envelope::IO::{Reader,Writer}` — own the parse and persist halves of the write pipeline; the audit-append-as-final-step invariant lives in `Writer`.
-
-## Container
-
-Use cases never see the raw `Store`. `Textus::Container` is a single record holding the wired collaborators:
-
-```ruby
-Container = Data.define(
-  :manifest, :file_store, :schemas, :root,
-  :audit_log, :events, :rpc, :authorizer
-)
-```
-
-The `Store` builds one `Container` at boot; every use case receives it via `(container:, call:)`. RPC hook callables (`:resolve_intake`, `:transform_rows`, `:validate`) receive `caps: <Container>` — field names match what the prior `WriteCaps` exposed, so handlers reading `caps.manifest`, `caps.events`, etc. continue to work.
-
-## Ports
-
-Ports are infrastructure adapters with an interface defined by the domain. Each port is independently replaceable — swap the implementation for tests or alternative runtimes without touching application or domain code.
-
-| Class | Role |
-|---|---|
-| `Ports::Storage::FileStore` | Bytes-only FS I/O — `read`, `write`, `delete`, `exists?`, `etag`. No knowledge of envelopes or schemas. |
-| `Ports::AuditLog` | Append-only structured log (`audit.log`). Owns seq numbering, file-locking, and rotation. |
-| `Ports::Clock` | Supplies `Time.now` — a module-function so tests can swap it without dependency injection boilerplate. |
-| `Ports::Publisher` | Copies a built artifact to a repo-relative consumer path and writes a sentinel so the next publish can confirm the target is managed. |
-| `Ports::Refresh::Lock` | Non-blocking `flock`-backed lock per key — prevents concurrent refresh workers from racing on the same entry. |
-| `Ports::Refresh::Detached` | Spawns a background thread for async refresh; the caller receives a `refresh_backgrounded` event instead of blocking. |
-| `Ports::BuildLock` | Process-exclusive `flock` guard over the materializer build pipeline. Raises `BuildInProgress` if a build is already running. |
-
-Application use cases access ports only through `Container` fields — never through the raw `Store`.
-
-### EnvelopeIO
-
-`Envelope::IO::Reader` and `Envelope::IO::Writer` split the envelope pipeline into read-only parse and write-with-audit halves.
-
-**Reader** (`lib/textus/envelope/io/reader.rb`) — resolves a key through `manifest.resolver`, reads bytes via `FileStore`, delegates parsing to the format strategy (`Entry.for_format`), and returns an `Envelope`. No audit, no events, no permission checks. Also used by `Writer` for the existing-uid lookup on `put`.
-
-**Writer** (`lib/textus/envelope/io/writer.rb`) — owns the full write pipeline: serialize → schema-validate → etag-check → `FileStore#write` → `AuditLog#append`. The class comment states the invariant directly: every public method's final action is `@audit_log.append(...)`. If the audit append fails, the caller sees the underlying error — the byte write already happened, but the pipeline contract treats audit as the commit step. No permission check, no event firing — those stay in the calling use case (`Write::Put`, `Write::Delete`, `Write::Mv`).
-
-The three public methods are `put`, `delete`, and `move`; all follow the same validate → write → audit sequence.
-
-Both are built from a `Container` via named constructors — `Writer.from(container:, call:)` (which builds its own `Reader.from`) and `Reader.from(container:)` (ADR 0026). Write use cases call `Writer.from` rather than reconstructing the object graph by hand, so a change to the Writer's dependencies is a one-line edit in one place.
-
-## Manifest carving
-
-Manifest carving means slicing the parsed manifest YAML into four purpose-specific sub-objects. Each consumer sees only the fields it needs; none reach into the full raw document.
-
-`Manifest` itself is a `Data.define` struct — a composition record with four named members:
-
-| Member | Class | Responsibility |
-|---|---|---|
-| `data` | `Manifest::Data` | Frozen value: `raw`, `root`, `zones`, `entries`, `audit_config`, `role_mapping`. Structural data only — no behaviour beyond accessors and key validation. |
-| `resolver` | `Manifest::Resolver` | Key → `Resolution(entry, path, remaining)`. Handles nested entry enumeration and fuzzy-match suggestions. |
-| `policy` | `Manifest::Policy` | Zone/role authority — `zone_writers`, `zone_kinds`, `permission_for`, `role_kind`, `roles_with_kind`, `propose_zone_for(role)`. Derived from a `Data` snapshot; no filesystem I/O. `propose_zone_for` owns the "first writable zone whose name contains `review`" convention used by `MCP::Server` (ADR 0027). |
-| `rules` | `Manifest::Rules` | Pattern-matched rule engine. `rules.for(key)` returns a `RuleSet(refresh, handler_allowlist, promote, retention)` by evaluating all `match:` blocks against the key. |
-
-Rationale: cleaner test seams — a use case that only needs key resolution constructs a `Manifest::Resolver` from a stub `Data`; one that only needs rule lookup constructs a `Manifest::Rules` directly. No consumer is forced to build the full manifest to exercise one sub-view.
-
-The four members are wired in `Manifest.build` (`lib/textus/manifest.rb`). `Manifest::Data` constructs `Policy` internally during `initialize`; the others are assembled by the loader and handed in as named arguments.
-
-## Read path (`store.get(key)`)
-
-1. CLI verb (or MCP tool) calls `store.get(key, role:)` (or `store.as(role).get(key)`).
-2. `Store#get` looks up `Dispatcher::VERBS[:get] → Read::Get`, builds a `Call`, instantiates `Read::Get.new(container:, call:).call(key)`.
-3. `Read::Get#call` resolves the path through `container.manifest`, reads bytes via `container.file_store`, parses the envelope.
-4. Looks up the refresh policy via `container.manifest.rules.for(key)`. If absent, returns the envelope annotated fresh.
-5. Otherwise `Domain::Freshness::Evaluator.call(policy, envelope, now:)` returns a `Verdict`; the envelope is annotated with `stale`, `reason`, `refreshing: false`.
-
-`store.get_or_refresh(key)` composes `Read::Get` with `Write::RefreshOrchestrator` to optionally refresh on stale.
-
-## Write path (`store.put(key, ...)`)
-
-1. CLI verb calls `store.put(key, meta:, body:, content:, if_etag:, role:)`.
-2. `Write::Put#call` validates the key, resolves the manifest entry, and calls `container.authorizer.authorize_write!(mentry, role: call.role)` — raises `WriteForbidden` if denied.
-3. Delegates persistence to `Envelope::IO::Writer#put`, which serializes, schema-validates, etag-checks (raises `EtagMismatch` on conflict), writes via the `FileStore` port, and appends the audit row.
-4. Publishes `:entry_put` via `container.events` with `ctx: <Hooks::Context>`, `key:`, `envelope:`.
-
-`Write::{Delete,Mv,Accept,Reject,Publish}` follow the same shape: explicit container, `Authorizer` for authz, `Envelope::IO::Writer` for persistence (where applicable), event published with the `Hooks::Context` handle.
-
-`Write::Mv` delegates the file-move + audit to `Envelope::IO::Writer#move`, then publishes `:entry_renamed` itself. UID injection (when the source lacks one) goes through `Envelope::IO::Writer#write` directly — no `Put` bypass.
-
-## Refresh path (`store.refresh(key)`)
-
-1. CLI `Verb::Refresh` calls `store.refresh(key, role: "runner")`.
-2. `Write::RefreshWorker#run(key)`:
-   - Resolves the manifest entry, looks up the intake handler via `container.rpc.callable(:resolve_intake, mentry.handler)`.
-   - Publishes `:refresh_started` with the hook context.
-   - Invokes the handler under a 30s thread-join deadline.
-   - On any error: publishes `:refresh_failed`, then re-raises.
-   - On success: applies `container.authorizer.authorize_write!` and persists via `Envelope::IO::Writer#write` directly (no `Put` round-trip); publishes `:entry_refreshed` unless etag is unchanged.
-3. `store.refresh_all(prefix:, zone:)` lists stale entries via `Read::Stale` and runs `Worker#run` per entry; returns `{ refreshed:, failed:, skipped: }`.
-
-## Hook payload contract
-
-Pub-sub hooks (`:entry_put`, `:entry_refreshed`, …) receive `ctx:` — a `Textus::Hooks::Context` that exposes a narrow surface (`get`, `list`, `put`, `delete`, `audit`, `publish_followup`, plus `role` and `correlation_id`). The raw `Store` is not handed out.
-
-RPC hooks (`:resolve_intake`, `:transform_rows`, `:validate`) receive `caps:` — a `Textus::Container`. They are gem-internal: the framework calls them, not user pub-sub.
-
-## Agent surface (boot + pulse + MCP)
-
-Agents and plugins talk to a textus store through three layers:
-
-```
-soul (skill/agent)  ──▶  gate (CLI | MCP)  ──▶  Store  ──▶  memory (.textus/)
-```
-
-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.
-
-Both transports call `store.<verb>(..., role:)` (or `store.as(role).<verb>(...)`). No duplicate logic.
-
-The agent loop (cadence guide in `docs/agent-integration.md`):
-
-1. **Session start:** `boot()` → contract envelope (zones, entries, schemas, write_flows, agent_quickstart with `latest_seq`).
-2. **Per turn:** `pulse(since=cursor)` → `{cursor, changed, stale, pending_review, doctor}`.
-3. **On demand:** `get`, `put`, `propose`, `refresh`, `schema`, `rules`.
-
-Manifest drift surfaces as `ContractDrift` (manifest_etag mismatch); audit cursor falls off the keep window as `CursorExpired`. Both signal "call `boot` again."
-
-## Hooks::EventBus event catalog
-
-`Hooks::Signature` is the single home of callable keyword-introspection — both `EventBus` (pub-sub dispatch) and `RpcRegistry` (RPC dispatch) delegate to it for `accepts_keyrest?`, `declared_keys`, `missing`, and `filter` rather than each maintaining a hand-rolled copy (ADR 0027).
-
-RPC (single handler, declares `caps:`):
-- `resolve_intake(caps:, config:, args:)` — intake fetch handler.
-- `transform_rows(caps:, rows:, config:)` — row transform for intakes.
-- `validate(caps:)` — custom doctor validator.
-
-Pub-sub (0..N handlers, declare `ctx:`):
-- `entry_put(ctx:, key:, envelope:)`
-- `entry_deleted(ctx:, key:)`
-- `entry_refreshed(ctx:, key:, envelope:, change:)`
-- `entry_renamed(ctx:, key:, from_key:, to_key:, envelope:)`
-- `build_completed(ctx:, key:, envelope:, sources:)`
-- `proposal_accepted(ctx:, key:, target_key:)`
-- `proposal_rejected(ctx:, key:, target_key:)`
-- `file_published(ctx:, key:, envelope:, source:, target:)`
-- `store_loaded(ctx:)`
-- `refresh_started(ctx:, key:, mode:)`
-- `refresh_failed(ctx:, key:, error_class:, error_message:)`
-- `refresh_backgrounded(ctx:, key:, started_at:, budget_ms:)`
-
-Authoritative source: `lib/textus/hooks/event_bus.rb` `EVENTS`.
+Moved to [`docs/architecture/README.md`](docs/architecture/README.md).

data/CHANGELOG.md

@@ -9,6 +9,119 @@ 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.35.1 — 2026-05-31 — RSpec foundation consolidation (test-only)
+
+No `textus/3` wire-format change; no manifest-schema change; no library behavior change.
+Test-suite maintenance only.
+
+### Changed
+
+- Removed redundant per-file `include TextusSpecHelpers` lines (the module is
+  globally included via `spec/support/fixtures.rb`).
+- Envelope-writer specs now assert audit side-effects through the shared
+  `have_audit_verb` / `last_audit_row` helpers instead of raw `audit.log`
+  JSON substring matching.
+
+### Fixed
+
+- `pulse_queue_zone` spec no longer leaks a temp directory per run (its second
+  store now builds under the `textus_store_fixture` tmp tree, which is cleaned up).
+
+## 0.35.0 — 2026-05-31 — Proposal target-zone constraint + `author_held` ([ADR 0035](docs/architecture/decisions/0035-proposal-target-zone-constraint.md))
+
+No `textus/3` wire-format change; no manifest-schema change.
+
+### Changed (BREAKING)
+
+- **`accept` now refuses a proposal whose `target_key` is not a `canon` zone** (new floor
+  predicate `target_is_canon`). Previously such a proposal failed confusingly downstream
+  (accept-into-derived) or incoherently "succeeded" (accept-into-workspace). Refusals surface
+  as `guard_failed` naming `target_is_canon`.
+- **Predicate `author_signed` renamed to `author_held`** — it checks possession of the `author`
+  capability, not a signing gesture. `guard_failed` output and any `rules[].guard` referencing
+  the old name change accordingly.
+
+### Added
+
+- **`doctor` check `proposal_targets`** — warns on queued proposals whose `target_key` is
+  non-canon (`proposal.target_not_canon`) or unresolvable (`proposal.target_unresolved`).
+
+## 0.34.0 — 2026-05-31 — Unify the Lane vocabulary + finish boot's kind-derived zone naming ([ADR 0034](docs/architecture/decisions/0034-unify-lane-vocabulary.md))
+
+No `textus/3` wire-format change; no manifest-schema change. The five zone-kinds and five
+capabilities, their names, and their mapping are identical to 0.33.0.
+
+### Changed
+
+- **One `Schema::LANES` table is now the source of truth** for the closed coordination
+  vocabulary; `ZONE_KINDS`, `CAPABILITIES`, and `KIND_REQUIRES_VERB` are derived from it, so a
+  zone-kind and its required capability can no longer drift. (`CAPABILITIES` array ordering
+  now follows `LANES.values`; no behaviour depends on it.)
+- **`boot` names zones by kind, not by hardcoded instance.** `write_flows`, the
+  `agent_protocol` recipes, and the CLI verb catalog now reflect the live store
+  (`knowledge`/`notebook`/`feeds`/`proposals`/`artifacts`) and survive zone renames —
+  completing the rename-fragility fix [ADR 0033](docs/architecture/decisions/0033-complete-primitives-and-vocabulary.md) §6 began for `ZONE_PURPOSES`.
+- **`keep`-holders now get a `notebook` write-flow in `boot`.** 0.33 added the `keep`
+  capability but no boot guidance for it; the agent's durable-lane flow was silently omitted.
+
+### Fixed
+
+- **`pulse` `pending_review` was silently empty on default stores since 0.33.** It hardcoded
+  the pre-0.33 zone name `review`; it now derives the queue zone from the manifest, so it
+  surfaces pending proposals from the (default-named) `proposals` zone again.
+
+### Removed (BREAKING, internal)
+
+- **`Manifest::Data#zones`** (the unused `name => []` map) is removed; the four internal
+  readers now use `Manifest::Data#declared_zone_kinds`. No manifest-schema or wire change.
+
+## 0.33.0 — Complete primitives + vocabulary (ADR 0033) — 2026-05-31
+
+**BREAKING (manifest schema + default scaffold + predicate/error names; `textus/3` wire format UNCHANGED):**
+- New coordination primitive: `workspace` zone-kind + `keep` capability — agents get a durable self-owned lane (`notebook` in the default scaffold). Closes the agent-memory gap.
+- Renamed capability `accept` → `author` (the `accept` *transition* / CLI verb is unchanged); predicate `accept_signed` → `author_signed`; zone-kind `origin` → `canon`.
+- Default scaffold renamed: `identity` + `working` → `knowledge` (identity is now the `knowledge.identity.*` key prefix), `intake` → `feeds`, `review` → `proposals`, `output` → `artifacts`; new `notebook` workspace zone.
+- Zones may declare optional `owner:` (informational) and `desc:` (surfaced as the boot zone purpose).
+- Manifests using `origin` / `accept` (capability) / `accept_signed` get an unknown-value rejection at load — no aliasing.
+- The `textus/3` envelope, audit-log, and key-grammar wire formats are unchanged.
+
+## 0.32.1 — 2026-05-30
+
+### Internal
+
+- Test-suite cleanup for the unified-Guard specs (no `lib/` change): the new Guard/predicate/write specs now use the shared `textus_store_fixture` context plus a single `store_from_manifest` helper (replacing 9 per-file `build_*_store` methods and hand-rolled `Dir.mktmpdir` nesting), a `fail_guard_with` matcher for `GuardFailed` assertions, and uniformly mockist predicate unit specs (`zone_writable_by_spec` joins `accept_signed_spec`/`schema_valid_spec`).
+
+## 0.32.0 — 2026-05-30
+
+Unified Guard engine ([ADR 0031](docs/architecture/decisions/0031-unified-guard.md), moves 2 & 3 of [ADR 0028](docs/architecture/decisions/0028-coordination-planes.md)), plus dropping the never-enforced read gate ([ADR 0032](docs/architecture/decisions/0032-drop-read-policy.md)). Every write transition now authorizes through **one Guard** — an ordered list of pure predicates over a single `Evaluation` context. No wire format (`textus/3`) change; the manifest schema and error envelopes change (breaking).
+
+### Changed (BREAKING)
+
+- **Manifest `rules[].promotion: { requires: [...] }` is removed; use `rules[].guard: { accept: [...] }`.** A `guard:` block is a map of transition (`put`/`delete`/`mv`/`accept`/`reject`/`fetch`) → predicate list, composed (AND) onto each transition's built-in base guard. A stale `promotion:` key is now rejected at load (unknown key).
+- **Authorization is unified into one Guard** (ADR 0031). Promotion / accept-authority / schema failures now surface as `guard_failed` naming the unmet predicate(s); the topology refusal keeps the `write_forbidden` code and `--as=<role>` hint. Custom/vendored predicates must use the `#call(Evaluation)` signature.
+- **`read_policy` is removed from the manifest** (ADR 0032): textus gates writes, not reads. `Domain::Authorizer` and `ReadForbidden` are gone. Reads are unrestricted at the protocol layer (the `.textus/` files are on disk); per-role read-scoping, if needed, is an agent-surface projection, not a manifest field.
+
+### Internal
+
+- New `Domain::Policy::{Evaluation, Guard, GuardFactory, BaseGuards}` and `Predicates::{Registry, ZoneWritableBy, EtagMatch, FreshWithin}`; `Predicates::{AcceptSigned, SchemaValid}` reshaped to `#call(Evaluation)`. `Domain::Policy::{Promotion, Promote}` and `Write::AuthorityGate` are deleted (folded into the Guard + single `Predicates::REGISTRY`). `Manifest::Rules` `RuleSet` gains `guard`, loses `promote`. `Permission` collapses to `(zone, writers)`.
+
+## 0.31.0 — 2026-05-30
+
+Capability-based roles and the `refresh`→`fetch` transition rename ([ADR 0030](docs/architecture/decisions/0030-capability-based-roles.md)). No wire format (`textus/3`) change; the manifest schema changes (breaking) and the data-in transition is renamed.
+
+### Changed (BREAKING)
+
+- **Roles are now capability-based.** A role declares `can: [verbs]` over a closed 4-verb set — `propose`, `accept`, `fetch`, `build` — replacing the 1:1 `role → kind` model. The role-kinds `accept_authority`/`proposer`/`generator`/`runner` are gone, as are the role names `runner` and `builder` (the umbrella automated role is now `automation`). Default mapping (when no `roles:` block is declared): `human=[accept, propose]`, `agent=[propose]`, `automation=[fetch, build]`.
+- **Per-zone `write_policy:` is removed.** Write authority is **derived** from the role's capabilities × the zone's kind: a role may write a zone iff it holds the verb that kind requires — `queue→propose`, `origin→accept`, `quarantine→fetch`, `derived→build`. Zones now declare only `kind:` (and optional `read_policy:`). A manifest carrying `write_policy:` is rejected at load (unknown key).
+- **`accept` is the single trust anchor:** at most one role may hold the `accept` capability. The `accept`/`reject` gate and the `maintained_by` override key on the `accept` capability rather than a hard-coded role kind. The promotion predicate `:accept_authority_signed` (and the older `:human_accept`) is renamed `:accept_signed`.
+- **The `refresh` transition is renamed `fetch`.** CLI `textus fetch` / `textus fetch stale` (was `refresh` / `refresh stale`); the rule block `refresh:` is now `fetch:`; events `:refresh_started`/`:refresh_failed`/`:refresh_backgrounded`/`:entry_refreshed` are `:fetch_started`/`:fetch_failed`/`:fetch_backgrounded`/`:entry_fetched`; the freshness meta field `last_refreshed_at` is `last_fetched_at`, the freshness verdict `never_refreshed` is `never_fetched`, and the envelope's `refreshing?`/`fetching` field is `fetching`. The MCP tools `refresh`/`refresh_stale` are `fetch`/`fetch_stale`.
+- `WriteForbidden` now reports the missing capability: `writing '<key>' (zone '<zone>') needs capability '<verb>'`, with a hint naming the roles that hold it (or `no declared role`).
+
+### Internal
+
+- `Manifest::Capabilities` (was `RoleKinds`) resolves `roles:` to `{ name => [verbs] }`; `Manifest::Data#role_caps` replaces `#role_mapping`. `Manifest::Policy` gains `verb_for_zone`, `roles_with_capability`, `proposer_role`, and derives `zone_writers` from capabilities × zone-kind; `role_kind`/`roles_with_kind`/`role_mapping` are removed. Schema validates the capability vocabulary, the ≤1-`accept` invariant, and that every declared zone-kind's required verb is held by some role.
+- The `refresh`→`fetch` rename is mechanical across the engine: `Write::{FetchWorker,FetchAll,FetchOrchestrator}`, `Read::GetOrFetch`, `Domain::Policy::Fetch`, `Ports::Fetch::{Lock,Detached}`, `Domain::Policy::Predicates::AcceptSigned`, `Outcome::Fetched`, and the dispatcher verb keys.
+
 ## 0.30.0 — 2026-05-29
 
 Explicit zone kind (strict) and entry retention (ADR 0028, moves 1 & 4). No wire format (`textus/3`) change.