textus 0.22.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38a9a929bb63f94d5a3cdc4708f09ce5c8e0eca28928d5733b8d842d90ece8b8
-  data.tar.gz: 26a8aeb22666788cd30e949eb25c7336db1de9ef7f4110aaf700f7abecdec644
+  metadata.gz: 0e8208a516e0a7760953e7c44a74fb459f168192ac4b0a20059b8686285f137a
+  data.tar.gz: 063deb01f793cec399a68620ce23bf1e9daf6d797edb985d919cb3bd6b9a1f87
 SHA512:
-  metadata.gz: 9b4ce0da2828f2623f60601cdd0ac8a69e51cc9670c5de80b92e3b41e0f955361154664b8cb0a7de0e838b5403336ff26589698201885b44001a83cfcd2c3f21
-  data.tar.gz: 672d948ab0ccdea1470dcb38c87c233ed717a538d4e4902191a32224dac8475fe1269b4569be00e5eb1f40e9c6146f8867d557d6455601c13fc2e0ce2c381cae
+  metadata.gz: 29d392ea08bbd23f460761c1849c90d144a97b9e9208355818b364acbf72c708e2129c650ecf032a562b62271064094dac96ed5f6497c97128666e004959d47d
+  data.tar.gz: 2260fe709abe9685285cad7171e36def69a6e25047762c2077dcb4c70e670f8232123156b33b5811dfd79393592b563470819c641ff9508ec2b795f3b87065ad

data/ARCHITECTURE.md

@@ -2,88 +2,235 @@
 
 ```
 ┌─ Interface ────────────────────────────────────────────────┐
-│  CLI verbs:  ops = Operations.for(store, role:)            │
-│              ops.<name>(...)   # flat methods, one per use │
-│                                # case (put/get/refresh/…)  │
+│  CLI verbs:  store.<verb>(..., role:)                      │
+│              store.as(role).<verb>(...)                    │
+│                                # (put/get/refresh/…)       │
 │                                                            │
-│  Or, for embedders bringing their own ports:               │
-│              Operations.new(ctx:, manifest:, file_store:,  │
-│                             schemas:, audit_log:, bus:,    │
-│                             registry:, root:, store:)      │
+│  MCP gate:   textus mcp serve — same use cases, JSON-RPC.  │
 └──────────────────────┬─────────────────────────────────────┘
                        │
 ┌─ Application ────────▼─────────────────────────────────────┐
-│  Context          (slim Data: role, correlation_id, now,   │
+│  Call             (slim Data: role, correlation_id, now,   │
 │                    dry_run — request state only)           │
-│  Operations       (flat facade; inline use-case factories) │
+│  Container        (single record — wired ports + manifest) │
+│  Dispatcher       (static VERBS table: verb → use-case)    │
+│  RoleScope        (Store#as(role) — forwards verb calls)   │
 │                                                            │
-│  reads/{get,list,where,uid,schema_envelope,deps,rdeps,     │
-│         published,stale,validate_all,freshness,audit,      │
-│         blame,policy_explain,get_or_refresh}.rb            │
-│  writes/{put,delete,mv,accept,reject,build,publish,        │
-│          envelope_io}.rb                                   │
-│  refresh/{worker,orchestrator,all}.rb                      │
-│  policy/{promotion,predicates/{schema_valid,human_accept}} │
+│  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}                     │
-│  Action  Outcome                                           │
-│  Policy::{Promote,Refresh,Matcher,HandlerAllowlist}        │
+│  Staleness          (Generator/Intake checks)              │
+│  Action  Outcome  Sentinel                                 │
+│  Policy::{Promote,Refresh,Matcher,HandlerAllowlist,        │
+│           Predicates::{SchemaValid,AcceptAuthoritySigned}} │
 └──────────────────────────────────────────┬─────────────────┘
                                            │ implements
 ┌─ Infrastructure ─────────────────────────▼─────────────────┐
-│  Store              (composition root — wires ports)       │
+│  Store              (composition root — wires ports,       │
+│                      vends a Container + dispatches verbs) │
 │  Storage::FileStore (bytes-only port: read/write/delete/   │
 │                      exists?/etag)                         │
-│  Manifest           (Entry, Rules, Schema, permission_for) │
+│  Manifest           (Data, Resolver, Policy, Rules)        │
 │  Schemas            (eager-load cache)                     │
-│  AuditLog                                                  │
-│  Hooks::{Registry,Dispatcher,Loader,FireReport}            │
-│  Infra::{Publisher,EventBus,Clock,Refresh::Lock,           │
-│          Refresh::Detached,BuildLock,AuditSubscriber}      │
+│  Ports::{AuditLog,AuditSubscriber,Publisher,Clock,         │
+│          Refresh::Lock,Refresh::Detached,BuildLock}        │
+│  Hooks::{EventBus,RpcRegistry,Loader,Context,FireReport,   │
+│          Builtin,ErrorLog}                                 │
 │  Entry::{Markdown,Json,Yaml,Text}  (format strategies)     │
 └────────────────────────────────────────────────────────────┘
 
-   Dependency rule: arrows point DOWN. Domain has zero outbound
-   imports. Application imports Domain + Infra (via ports).
-   Use cases declare their real ports in their constructor.
+   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.
 ```
 
-## Read path (`ops.get(key)`)
+## How a verb becomes a method
 
-1. CLI verb (or any external caller) builds `ops = Textus::Operations.for(store, role:)` then `ops.get(key)`.
-2. `Operations#get` constructs `Application::Reads::Get.new(ctx:, manifest:, file_store:)` and calls it.
-3. `Reads::Get#call(key)` resolves the path through `@manifest`, reads bytes via `@file_store`, parses the envelope.
-4. Looks up the refresh policy via `@manifest.rules_for(key)`. If absent, returns the envelope annotated fresh.
+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.
+
+`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.
+
+## 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`. Derived from a `Data` snapshot; no filesystem I/O. |
+| `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`.
 
-`ops.get_or_refresh(key)` composes `Reads::Get` with `Refresh::Orchestrator` to optionally refresh on stale — same as 0.18.x.
+`store.get_or_refresh(key)` composes `Read::Get` with `Write::RefreshOrchestrator` to optionally refresh on stale.
 
-## Write path (`ops.put(key, ...)`)
+## Write path (`store.put(key, ...)`)
 
-1. CLI verb calls `ops = Operations.for(store, role:)` then `ops.put(key, meta:, body:, content:, if_etag:)`.
-2. `Writes::Put#call` validates the key, resolves the manifest entry, and calls `@authorizer.authorize_write!(mentry, role: @ctx.role)` — raises `WriteForbidden` if denied.
-3. Delegates persistence to `EnvelopeIO#write`, 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 `@bus` with `store: @store`, `key:`, `envelope:`, `role: @ctx.role`, `correlation_id: @ctx.correlation_id`.
+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:`.
 
-`Writes::{Delete,Mv,Accept,Reject,Build,Publish}` follow the same shape: explicit ports, `Authorizer` for authz, `EnvelopeIO` for persistence (where applicable), event published with `store: real Store + role:` in payload.
+`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.
 
-`Writes::Mv` delegates the file-move + audit to `EnvelopeIO#move`, then publishes `:entry_renamed` itself. UID injection (when the source lacks one) goes through `EnvelopeIO#write` directly — no `Put` bypass.
+`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 (`ops.refresh(key)`)
+## Refresh path (`store.refresh(key)`)
 
-1. CLI `Verb::Refresh` builds `ops = Operations.for(store, role: "runner")` then calls `ops.refresh(key)`.
-2. `Refresh::Worker#run(key)`:
-   - Resolves the manifest entry, looks up the intake handler via `@registry.rpc_callable(:resolve_intake, mentry.intake_handler)`.
-   - Publishes `:refresh_started` with `role:` in the payload.
+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 `@authorizer.authorize_write!` and persists via `EnvelopeIO#write` directly (no `Put` round-trip); publishes `:entry_refreshed` unless etag is unchanged.
-3. `ops.refresh_all(prefix:, zone:)` lists stale entries via `Reads::Stale` and runs `Worker#run` per entry; returns `{ refreshed:, failed:, skipped: }`.
+   - 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
 
-Hooks/intakes/transforms receive the actual `Textus::Store` (the composition root) as `store:`. Every write/refresh event payload carries `role:` directly so hook authors observe the actor without reaching through `store:`.
+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
+
+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`.

data/CHANGELOG.md

@@ -9,6 +9,184 @@ 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.29.0 — 2026-05-29
+
+A domain-purity pass that routes all filesystem and wall-clock I/O through injected ports. Breaking changes are Ruby-API only; the wire format (`textus/3`) and CLI are unchanged.
+
+### Breaking
+
+- `Domain::Staleness#initialize` now requires `file_stat:` and `clock:` (was `manifest:` only).
+- `Domain::Staleness::IntakeCheck#initialize` now requires `file_stat:` and `clock:`.
+- `Domain::Staleness::GeneratorCheck#initialize` now requires `file_stat:` (no clock — `GeneratorCheck` has no wall-clock dependency).
+- `Domain::Sentinel` is now a pure value object. Its persistence class methods (`write!`, `load`, `sentinel_path`) and `SUFFIX`/`DIR` constants have moved to the new `Ports::SentinelStore`.
+- `Domain::Sentinel#orphan?` and `#drift?` now take a `file_stat` argument.
+- `Textus::Boot.run_via(container:, role:)` → `Textus::Boot.build(container:)` (the `role:` parameter was unused).
+- `Textus::Doctor.run_via(container:, role:, checks:)` → `Textus::Doctor.build(container:, checks:)` (the `role:` parameter was unused).
+- `RoleScope#boot` / `#doctor` are removed as special cases; `boot` and `doctor` are now entries in `Dispatcher::VERBS`. `store.boot`, `store.doctor`, and `store.as(role).boot` are unchanged.
+
+### Added
+
+- `Ports::Storage::FileStat` — read-only filesystem query port (`exists?`, `directory?`, `read`, `mtime`, `glob`); the narrow interface pure domain logic depends on (distinct from the write-side `FileStore`).
+- `Ports::SentinelStore` — sentinel persistence + path-layout adapter, extracted from `Domain::Sentinel`.
+- `Read::Boot` and `Read::Doctor` — dispatched use-case classes on the uniform `(container:, call:)` shape.
+
+### Changed
+
+- `manifest_etag` (in `pulse` output and the MCP session drift token) is now the system-standard `sha256:`-prefixed etag, computed via `FileStore#etag`, instead of a bare SHA-256 hex digest. The token is opaque (compared for equality, never parsed).
+
+### Internal
+
+- The domain layer no longer performs direct filesystem or wall-clock I/O; all disk/clock access is routed through injected ports (`FileStat`, `Clock`). Enforced by a new `spec/domain_purity_spec.rb` that fails on any regression.
+- Freshness request timestamps now originate from `Ports::Clock` (via `Call.build`) rather than a bare `Time.now`.
+- Cosmetic refactors: deduped the audit limit guard; made `RefreshWorker.normalize_action_result` a public class method (dropped a `send`); extracted staleness guard helpers.
+- New guard spec `spec/no_handrolled_manifest_etag_spec.rb` forbids `Digest::SHA256.hexdigest(File.read(...))` from reappearing in `lib/` (exempt: `etag.rb` and `sentinel_store.rb`, the latter being a wire-pinned integrity checksum, not an etag).
+- See [ADR 0024](docs/architecture/decisions/0024-domain-purity-ports.md) for the design rationale.
+
+## 0.28.0 — 2026-05-29
+
+A consistency-and-cleanup pass that finishes the seams [ADR 0022](docs/architecture/decisions/0022-container-call-dispatcher.md) left behind. Breaking changes are Ruby-API only.
+
+### Breaking
+
+- Use-case constructors no longer accept `hook_context:`. Use cases that emit events derive their `Hooks::Context` internally from `(container, call)` via the new `Textus::Hooks::Context.for(container:, call:)` factory. Every use case now has the uniform shape `def initialize(container:, call:)`.
+- `Textus::Envelope::IO::Writer` and `Textus::Write::RefreshOrchestrator` constructors take `call:` instead of `ctx:` (both received a `Call` already; the kwarg name is corrected).
+- `Read::Audit#call` now accepts filter keywords and builds a `Read::Audit::Query` value object internally — keyword callers (`store.audit(key:, limit:)`) are unchanged.
+- `Builder::Pipeline.run` takes `(mentry:, deps:)` where `deps` is a `Builder::Pipeline::Deps` record, instead of eight loose keyword collaborators.
+- Removed the `CLI::VERBS` const-missing shim (use `CLI.verbs`).
+- Removed the `Manifest::Entry::PUBLISH_EACH_VARS` / `PUBLISH_EACH_VAR_RE` re-exports (use `Manifest::Entry::Validators::PublishEach::KNOWN_VARS` / `::VAR_RE`).
+
+### Internal
+
+- Removed the runtime `initialize`-parameter reflection from both `RoleScope` and `Doctor::Check`; verb dispatch is now an unconditional `klass.new(container:, call:).call(...)`.
+- `Lint/UnusedMethodArgument` disables dropped from 27 to 20; two `Metrics/ParameterLists` (and two complexity) disables removed by the value-object refactors. `Metrics/ParameterLists` ceiling documented and kept at `Max 6` (the honest ceiling for value-object constructors, `AuditLog#append`, and the public `put` API).
+- `ARCHITECTURE.md`'s "uniform `(container:, call:)`" claim is now accurate; active docs refreshed to the 0.27/0.28 vocabulary.
+- No wire-format change. Protocol stays at `textus/3`. CLI verb signatures unchanged. Hook callable surfaces (`ctx:` for pub-sub, `caps:` for RPC) unchanged.
+- See [ADR 0023](docs/architecture/decisions/0023-uniform-use-case-shape.md) for the design rationale.
+
+## 0.27.0 — 2026-05-29
+
+### Breaking
+
+- Removed `Textus::Session`. Use `store.as(role).put(...)` or `store.put(..., role:)` instead of `store.session(role:).put(...)`.
+- Removed `Textus::Application::UseCase` registry. Verb dispatch is now via the static `Textus::Dispatcher::VERBS` table.
+- Replaced `Textus::Application::ReadCaps` / `WriteCaps` / `HookCaps` with a single `Textus::Container` record (field names preserved: `manifest`, `file_store`, `schemas`, `root`, `audit_log`, `events`, `rpc`, `authorizer`).
+- Renamed `Textus::Application::Context` to `Textus::Call`. Field shape identical.
+- Use-case classes are no longer `module Foo; def self.call; Impl.new(...).call; end`. They are plain classes: `class Foo; def initialize(container:, call:); def call(...); end`.
+- Flattened `Textus::Application::Write::*` → `Textus::Write::*`, `Application::Read::*` → `Read::*`, `Application::Envelope::*` → `Envelope::IO::*`, `Application::Maintenance::*` → `Maintenance::*`, `Application::Projection` → `Projection`.
+- Renamed `Textus::Infra::*` → `Textus::Ports::*`.
+- `Manifest::Entry::Base#zone_writers` / `#in_generator_zone?` / `#in_proposal_zone?` now take an explicit `policy` argument; entries no longer carry an `@manifest` back-reference.
+- `PublishContext` shrunk from 12 fields to `(container, call, reader)` with derived accessors. Custom derived entries that destructured `pctx.caps` / `pctx.session` / `pctx.ctx` / `pctx.bus` need to use `pctx.container` / construct a `RoleScope` / `pctx.call` / `pctx.events`.
+- Hook RPC callables (`:resolve_intake`, `:transform_rows`, `:validate`) receive `caps: container` (a `Textus::Container`) instead of `caps: <WriteCaps>`. Field names preserved, so handlers reading `caps.manifest` / `caps.events` / etc. continue to work.
+
+### Internal
+
+- ~600 LOC removed net across ~60 files.
+- No wire-format change. Protocol stays at `textus/3`.
+- CLI verb signatures unchanged. No envelope shape changes.
+- See [ADR 0022](docs/architecture/decisions/0022-container-call-dispatcher.md) for the design rationale.
+
+## 0.26.0 — 2026-05-28
+
+### Breaking
+- Split `Textus::Hooks::Bus` into `Textus::Hooks::EventBus` (pubsub) and `Textus::Hooks::RpcRegistry` (named callables). The `Hooks::Bus` constant is removed.
+- Replaced `Textus::Application::Ports` with three capability records: `Textus::Application::ReadCaps`, `WriteCaps`, `HookCaps`.
+- Renamed `Textus::Operations` to `Textus::Session`. Access via `store.session(role:)`. `Operations.for(store, ...)` is removed.
+- Hook RPC callables (`resolve_intake`, `transform_rows`, `validate`) no longer accept `store:` — declare `caps:` (a `WriteCaps` for `resolve_intake`/`validate`, `ReadCaps` for `transform_rows`).
+- Removed all `Manifest` top-level deprecation shims (`zones`, `entries`, `zone_writers`, `permission_for`, etc.). Use `manifest.data.*` / `manifest.policy.*` / `manifest.resolver.*` / `manifest.rules.*`.
+- Moved `Textus::Application::Writes::EnvelopeReader`/`EnvelopeWriter` to `Textus::Application::Envelope::Reader`/`Writer`.
+- Renamed `Textus::Application::Writes` → `Textus::Application::Write`; `Textus::Application::Reads` → `Textus::Application::Read`; `Textus::Application::Restructure` → `Textus::Application::Maintenance`.
+- Merged `Textus::Application::Refresh::*` into `Textus::Application::Write::Refresh{Worker,Orchestrator,All}`.
+- Moved `Textus::Application::Policy::Promotion` and predicates to `Textus::Domain::Policy::Promotion`/`Predicates`.
+
+## 0.25.1 — 2026-05-28
+
+### Internal refactors
+
+- **ADR 0018**: `Manifest` is now a composition record over `Data`,
+  `Resolver`, `Policy`, `Rules`. Top-level methods like
+  `Manifest#permission_for` are deprecated; use
+  `manifest.policy.permission_for(zone)`. One-cycle bridge — shims
+  warn until 0.26.0.
+
+- **ADR 0016**: Application use cases take a single `ports:` kwarg
+  bundling six adapters + the store root. Hook DSL callables that
+  declare `|store:|` continue to work with a one-shot deprecation
+  warning per (event, hook_name); declare `|ports:|` to silence it.
+
+- **ADR 0017**: `Application::Writes::EnvelopeIO` split into
+  `EnvelopeReader` (parse) and `EnvelopeWriter` (put/delete/move
+  + audit). Every public `EnvelopeWriter` method now ends with an
+  audit-row append — the write-without-audit failure mode is gone.
+
+### Breaking (internal)
+
+- `Operations#store` accessor removed. There is no clean deprecation
+  shim because `Ports` cannot reconstruct a `Store`. External
+  callers should use `ops.ports.X` directly.
+
+- `Textus::Manifest::Entry::Base::PublishContext` struct shape
+  changed: `:store` removed, `:ports` + `:boot` added. Affects
+  third-party plugins that build custom derived entries.
+
+- `transform_context` passed to `transform_rows` RPC callables is
+  now an `Application::Ports`, not a `Store`. Transforms that treat
+  it as opaque continue to work; transforms that reach `.x` need
+  updates.
+
+No CLI verb signatures changed. No wire envelopes changed.
+Protocol remains `textus/3`.
+
+## 0.25.0 — 2026-05-28
+
+### Added (additive — backward-compatible pulse fields)
+- `pulse.manifest_etag` — sha256 of `manifest.yaml`; lets agents detect contract drift without a second verb.
+- `pulse.next_due_at` — soonest `next_due_at` across all entries with a refresh policy. Schedulers sleep until this timestamp instead of polling.
+- `pulse.hook_errors` — recent hook failures since cursor; bounded in-memory ring on `Hooks::Bus#error_log` (default 256).
+
+### Changed
+- `Application::Reads::Freshness` memoizes the evaluator verdict by `(key, last_refreshed_at)` per request — pulse no longer pays O(N) evaluator calls when nothing has changed.
+- `Application::Refresh::Orchestrator` gains a cooperative-cancel fallback for `RefreshTimed` when `fork(2)` is unavailable (Windows). Previously degraded to `Failed("timed_sync requires fork")`; now executes within the budget on a Thread, killing it on budget exceeded.
+
+### Protocol
+- No wire-format change. `textus/3` envelopes are unchanged. Pulse fields are additive — existing consumers ignoring unknown keys continue to work.
+
+## 0.24.0 — 2026-05-28
+
+### Added
+- **Context-structure ergonomics** (ADR 0015 Phase 2):
+  - `textus key mv --prefix OLD NEW` — bulk rename leaves under a prefix; preserves UIDs.
+  - `textus key delete --prefix P` — bulk delete leaves.
+  - `textus zone mv FROM TO` — rename a zone; refuses if destination exists; rewrites manifest + moves files.
+  - `textus rule lint --against=FILE` — diff candidate manifest YAML's `rules:` block against the live manifest.
+  - `textus migrate PLAN.yaml` — run a multi-op declarative migration plan (ops: `key_mv_prefix`, `key_delete_prefix`, `zone_mv`).
+  - All five operations also surface as MCP tools (`key_mv_prefix`, `key_delete_prefix`, `zone_mv`, `rule_lint`, `migrate`).
+- `Textus::Application::Restructure` module with `Plan` value object and one use case per operation.
+
+### Protocol
+- No wire-format change. `textus/3` envelopes are unchanged.
+
+## 0.23.0 — 2026-05-28
+
+### Added
+- **Agent gate (MCP transport).** `textus mcp serve` — stdio JSON-RPC 2.0
+  server speaking MCP draft 2024-11-05. Wraps `Textus::Operations` as ten
+  auto-derived tools (`boot`, `tick`, `find`, `read`, `write`, `propose`,
+  `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/mcp.md`](docs/mcp.md) and [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.
+
+### Changed (docs)
+- `ARCHITECTURE.md`: fixed stale `registry` references (now `bus`),
+  added Agent Surface section and complete Hooks::Bus event catalog.
+- `docs/agent-integration.md`: documents three transports (CLI, Ruby API,
+  MCP); points agent authors at the MCP transport by default.
+
+### Protocol
+- No wire-format change. `textus/3` envelopes are unchanged.
+
 ## 0.22.0 — 2026-05-28
 
 ### Changed (internal — no manifest-schema impact)

data/README.md

@@ -5,20 +5,62 @@
 [![Ruby](https://img.shields.io/badge/ruby-%E2%89%A53.3-CC342D.svg)](https://www.ruby-lang.org/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-A context store for codebases that humans and AI agents both have to read and write. Dotted keys, schema-validated entries, role-gated writes, byte-copy publish, an audit log of every change. Built so an agent landing in your repo can run one command (`textus boot`) and know what to read, what to write, and what's off-limits.
+**Durable, multi-writer context for codebases that humans and AI agents both touch.** Your agent forgets everything between sessions; your runbooks and `CLAUDE.md` get edited by whoever ran last; nobody can reconstruct who wrote what. textus is the memory that survives the model, the session, and the vendor — a shared workspace where humans, agents, and runners write into separate lanes, propose changes through a review queue, and leave an audit trail behind every byte.
 
-Reference implementation in Ruby. Wire format `textus/3`. SPEC: [`SPEC.md`](SPEC.md). Implementation notes: [`docs/`](docs/).
+*textus* is Latin for "the fabric a text is woven from" — same root as *context*, from *con-texere*, "to weave together." The protocol weaves human edits, agent proposals, and runner intake into one durable fabric. The shape of that fabric is yours; the rules for writing into it are textus's.
 
-## Versioning
+## The idea
 
-Two versions, deliberately independent:
+Three actors write to your repo today:
 
-- **Protocol wire string:** `textus/3`. Breaking changes require `textus/4`.
-- **Gem version:** semver, currently `0.18.0`. Decoupled from the protocol string — internal refactors bump the gem; only wire-format changes bump the protocol.
+- **Humans** — you, your team. Authoritative on identity, decisions, voice.
+- **Agents** — Claude, Cursor, custom assistants. Smart, fast, forgetful, and not always right.
+- **Runners** — cron jobs, fetchers, CI. Bring outside data in.
 
-Envelope payloads carry the `protocol` field. The gem version is irrelevant to the wire format.
+Without coordination, they overwrite each other and nothing remembers why. textus gives each actor a **lane** (a zone), routes everything they can't write directly through a **review queue**, and writes every successful change to an **append-only audit log**. The lanes are enforced at the protocol level, not by convention.
 
-See [CHANGELOG.md](CHANGELOG.md) for per-release notes.
+```
+identity/   human only          — who you are, what you decide, how you sound
+working/    human + agent + runner — day-to-day catalog
+intake/     runner only         — declared external inputs
+review/     agent + human       — proposals waiting on a human accept
+output/     builder only        — computed, published artifacts
+```
+
+An agent that tries to write directly into `working/` or `identity/` gets `write_forbidden`. It writes to `review/` instead. 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.**
+
+## See it in four commands
+
+```sh
+gem install textus
+textus init                          # creates .textus/ with zones + schemas
+# agent proposes a change to review/
+echo '{"_meta":{"name":"oncall","proposal":{"target_key":"working.notes.oncall","action":"put"}},"body":"Patrick on call.\n"}' \
+  | textus put review.notes.oncall --as=agent --stdin
+# you accept it — textus promotes to working/ and audits the move
+textus accept review.notes.oncall --as=human
+```
+
+Try the gate the other way (`textus put working.notes.X --as=agent`) and you get `write_forbidden`, with the role that *would* be allowed named in the error. That refusal is the whole point.
+
+## Try it
+
+- **5-command worked demo** — single terminal scroll, no MCP, no schemas: [`examples/hello/`](examples/hello/)
+- **Wire textus into Claude Code via MCP** — 4 steps, ~5 minutes: [`INTEGRATE_WITH_CLAUDE.md`](INTEGRATE_WITH_CLAUDE.md)
+- **Use textus as your own project's context store**: [`examples/project/`](examples/project/)
+- **Use textus to author a Claude plugin** (textus is the source-of-truth, build publishes to `agents/`, `skills/`, `commands/`): [`examples/claude-plugin/`](examples/claude-plugin/)
+
+## Protocol, not just a gem
+
+This Ruby gem is the reference implementation of **`textus/3`** — a wire format and storage convention any language can speak. The protocol owns the envelope shape, the role/zone gate, the audit log format, and the key grammar. The gem version (semver, see badge) and the protocol version (`textus/3`) move independently; envelopes carry the `protocol` field so consumers can pin to the contract, not the implementation.
+
+- Specification: [`SPEC.md`](SPEC.md)
+- Architecture: [`ARCHITECTURE.md`](ARCHITECTURE.md)
+- Per-release notes: [`CHANGELOG.md`](CHANGELOG.md)
+
+A second implementation in another language would share the same `.textus/` directory and the same audit log. That's deliberate.
 
 ## Install
 
@@ -75,15 +117,15 @@ textus audit --limit=20              # query the audit log
 
 For the full shape — Claude plugin with agents, skills, commands, pending walkthrough, intake action — see [`examples/claude-plugin/`](examples/claude-plugin/).
 
-## What ships today
+## What's shipped
 
 - **Per-entry formats.** `format: markdown | json | yaml | text` on a manifest entry. `cat .textus/zones/output/marketplace.json | jq .` works without going through textus — the in-store file *is* the consumer-shaped artifact. Structured outputs carry `_meta` at the top level (`generated_at`, `from`, `template`, `transform`).
 - **Per-leaf publishing.** Nested entries declare `publish_each: "skills/{basename}/SKILL.md"`. Every leaf byte-copies to its consumer location on `textus build`. No more hand-mirrored `agents/` / `skills/` / `commands/` directories.
-- **Split build/publish (v0.14.0).** `Application::Writes::Build` materializes generator-zone entries; `Application::Writes::Publish` copies nested leaves to `publish_each` targets. The `textus build` CLI verb calls both and merges results, so wire output is unchanged.
-- **Typed envelopes (v0.14.0).** `Textus::Envelope` is a `Data.define` value object with typed accessors (`.meta`, `.body`, `.etag`, `.uid`, `.freshness`, …). Ruby API callers get IDE help and `NoMethodError` on typos. The CLI JSON wire format is preserved byte-for-byte via `envelope.to_h_for_wire`.
+- **Build and publish in one pass.** `Textus::Write::Publish` materializes generator-zone entries and copies nested leaves to their `publish_each` targets. The `textus build` CLI verb dispatches to it; the wire envelope is unchanged.
+- **Typed envelopes.** `Textus::Envelope` is a `Data.define` value object with typed accessors (`.meta`, `.body`, `.etag`, `.uid`, `.freshness`, …). Ruby API callers get IDE help and `NoMethodError` on typos. The CLI JSON wire format is preserved byte-for-byte via `envelope.to_h_for_wire`.
 - **Stable identity (`uid:`).** 16-char hex, auto-minted on first `put`, preserved across writes and moves. `textus key mv old.key new.key` renames in place — uid survives, audit row records `from_key`, `to_key`, `uid`. Reorganising a tree no longer breaks references.
 - **Strict key grammar.** `/^[a-z0-9][a-z0-9-]*$/`, max 8 segments × 64 chars. `textus key normalize --dry-run|--write` rewrites existing stores with illegal segments deterministically.
-- **`textus boot`.** One-shot store orientation: zones with writers + purposes, entry families with schemas and publish targets, loaded hooks, write flows per role, the full CLI verb table, and an `agent_quickstart` block (read/write verbs, writable zones, propose zone, latest audit seq). The boot signal for any agent — one tool call and it knows your store.
+- **`textus boot`.** One-shot store orientation: zones with writers + purposes, entry families with schemas and publish targets, loaded hooks, write flows per role, the full CLI verb table, and an `agent_quickstart` block (read/write verbs, writable zones, propose zone, latest audit seq).
 - **`textus pulse [--since=N]`.** Per-turn heartbeat for agents: changed entries since cursor N, stale keys, pending review proposals, and a doctor summary. Cursor is a monotonic seq stamped on every audit row; rotation keeps the last 5 files (configurable via `audit:` in the manifest) and raises `CursorExpired` when the requested cursor has fallen off disk.
 - **`textus doctor`.** Health check across 9 categories: missing schemas/templates, broken hooks, illegal nested keys, sentinel drift, audit log readability, unowned schema fields, schema violations, and missing manifest files. Returns `ok: true` only when nothing is wrong; warnings and info don't flip the bit.
 - **Actionable hints on every error.** `UnknownKey` carries ranked "did you mean" suggestions. `WriteForbidden` names the role that *would* be allowed. `BadFrontmatter` tells you exactly what to rename. Printed to stderr alongside the JSON envelope on stdout.
@@ -163,7 +205,7 @@ See [`docs/agent-integration.md`](docs/agent-integration.md) for the agent boot
 bundle exec rspec
 ```
 
-~637 examples; includes conformance fixtures A–I from SPEC §12.
+~880 examples; includes conformance fixtures A–I from SPEC §12.
 
 ## Code quality