textus 0.22.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38a9a929bb63f94d5a3cdc4708f09ce5c8e0eca28928d5733b8d842d90ece8b8
-  data.tar.gz: 26a8aeb22666788cd30e949eb25c7336db1de9ef7f4110aaf700f7abecdec644
+  metadata.gz: e822d94de7ae06481dd8c03eab813a097b62e78121d94c9d1045017675da665c
+  data.tar.gz: 3372f74bb31465b28be8e6ce5b4721a3f15cae7536ebdfc8ef9b6c6d7c9f2d88
 SHA512:
-  metadata.gz: 9b4ce0da2828f2623f60601cdd0ac8a69e51cc9670c5de80b92e3b41e0f955361154664b8cb0a7de0e838b5403336ff26589698201885b44001a83cfcd2c3f21
-  data.tar.gz: 672d948ab0ccdea1470dcb38c87c233ed717a538d4e4902191a32224dac8475fe1269b4569be00e5eb1f40e9c6146f8867d557d6455601c13fc2e0ce2c381cae
+  metadata.gz: 31e4b83f9a7d3b061d043c447393b23ba404a47e7d79b0a411ad49719625d01ec30116a067f28bf88ac6944ff0262c1825d35c851022340d63b813dca26f98aa
+  data.tar.gz: 590cc3419cb7823688bab11c4fce49a011bf62b463ab887b415753dd3c8037cd0704b8ccc4df6e778b21c04bd8101847a28fa5d4819e447e7af3d44febc017f3

data/ARCHITECTURE.md

@@ -2,88 +2,191 @@
 
 ```
 ┌─ Interface ────────────────────────────────────────────────┐
-│  CLI verbs:  ops = Operations.for(store, role:)            │
-│              ops.<name>(...)   # flat methods, one per use │
-│                                # case (put/get/refresh/…)  │
+│  CLI verbs:  session = Session.for(store, role:)           │
+│              session.<name>(...)   # one method per         │
+│                                # registered use case        │
+│                                # (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,   │
 │                    dry_run — request state only)           │
-│  Operations       (flat facade; inline use-case factories) │
+│  Caps             (Read/Write/Hook records — store slices) │
+│  Session          (per-call dispatch; methods generated    │
+│                    from UseCase registry)                  │
+│  UseCase          (registry: verb → module, caps_kind)     │
 │                                                            │
-│  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,            │
+│        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/{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 Sessions)                       │
 │  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}      │
+│  Infra::{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.
+   Use cases declare their real collaborators in their Impl
+   constructor; UseCase.register hooks them into Session.
 ```
 
-## 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 module under `lib/textus/application/{read,write,maintenance}/`. The shape is uniform:
+
+```ruby
+module Textus
+  module Application
+    module Read
+      module Get
+        def self.call(*, session:, ctx:, caps:, **)
+          Impl.new(ctx: ctx, caps: caps).call(*, **)
+        end
+
+        class Impl
+          def initialize(ctx:, caps:, ...)
+            @ctx = ctx; @manifest = caps.manifest; ...
+          end
+
+          def call(key) ... end
+        end
+      end
+    end
+  end
+end
+
+Textus::Application::UseCase.register(:get, Textus::Application::Read::Get, caps: :read)
+```
+
+`Session` generates one dispatch method per registered entry (see `lib/textus/session.rb` — the `Application::UseCase.each do |entry| ... end` block at the bottom). Adding a new verb is **one `UseCase.register` line** plus the module — no edits to `Session`.
+
+Two collaborators live outside the registry because they're composed by other use cases, not invoked as verbs:
+
+- `Application::Write::RefreshOrchestrator` — composes `RefreshWorker` with the freshness `Action` returned by `Domain::Freshness`. Session memoizes one (`session.refresh_orchestrator`).
+- `Application::Envelope::{Reader,Writer}` — own the parse and persist halves of the write pipeline; the audit-append-as-final-step invariant lives in `Writer`. Session memoizes both.
+
+## Caps
+
+Use cases never see the raw `Store`. `Application::Caps` defines three role-scoped slices:
+
+```ruby
+ReadCaps  = Data.define(:manifest, :file_store, :schemas, :root, :audit_log, :events)
+WriteCaps = Data.define(:manifest, :file_store, :schemas, :root, :audit_log, :events, :authorizer)
+HookCaps  = Data.define(:events, :rpc, :manifest, :root)
+```
+
+`Session.for(store, role:)` builds all three via `Application.caps_from_store(store)`; the dispatch method picks `read_caps` or `write_caps` based on the `caps_kind` declared at registration time. RPC hook callables (`:resolve_intake`, `:transform_rows`, `:validate`) receive a `caps:` kwarg that is the appropriate Read/Write slice — legacy `store:` is rejected by `Hooks::RpcRegistry#invoke`.
+
+## Read path (`session.get(key)`)
+
+1. CLI verb (or MCP tool) builds `session = Session.for(store, role:)` then `session.get(key)`.
+2. `Session#get` dispatches to `Application::Read::Get.call(key, session:, ctx:, caps:)`.
+3. `Read::Get::Impl#call` resolves the path through `caps.manifest`, reads bytes via `caps.file_store`, parses the envelope.
+4. Looks up the refresh policy via `caps.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.
+`session.get_or_refresh(key)` composes `Read::Get` with `Write::RefreshOrchestrator` to optionally refresh on stale.
 
-## Write path (`ops.put(key, ...)`)
+## Write path (`session.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 `session = Session.for(store, role:)` then `session.put(key, meta:, body:, content:, if_etag:)`.
+2. `Write::Put::Impl#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 `session.envelope_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 `caps.events` with `ctx: session.hook_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 caps, `Authorizer` for authz, `Envelope::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::Writer#move`, then publishes `:entry_renamed` itself. UID injection (when the source lacks one) goes through `Envelope::Writer#write` directly — no `Put` bypass.
 
-## Refresh path (`ops.refresh(key)`)
+## Refresh path (`session.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` builds `session = Session.for(store, role: "runner")` then calls `session.refresh(key)`.
+2. `Write::RefreshWorker::Impl#run(key)`:
+   - Resolves the manifest entry, looks up the intake handler via `caps.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 `@authorizer.authorize_write!` and persists via `Envelope::Writer#write` directly (no `Put` round-trip); publishes `:entry_refreshed` unless etag is unchanged.
+3. `session.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 wraps the session and 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 `ReadCaps` or `WriteCaps` slice. 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)  ──▶  Session  ──▶  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 `Session.for(store, role:)`. 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,108 @@ 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.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

@@ -79,7 +79,7 @@ For the full shape — Claude plugin with agents, skills, commands, pending walk
 
 - **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.
+- **Build and publish in one pass.** `Application::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 (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`.
 - **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.

data/SPEC.md

@@ -888,10 +888,10 @@ Given a review entry `review.identity.self.patch` proposing a change to `identit
 
 Textus internals are organized into four layers. The dependency rule is one-way — each layer may only import from the layer beneath it.
 
-- **Interface** (`lib/textus/cli/`) — CLI verbs. Parses flags, calls a use case, formats JSON.
-- **Application** (`lib/textus/application/`) — Use cases: `Reads::Get`, `Refresh::Worker`, `Refresh::Orchestrator`, `Refresh::All`. Orchestrate domain + infra; no business rules.
-- **Domain** (`lib/textus/domain/`) — Pure values: `Freshness::Policy`, `Action`, `Outcome`, `Freshness::Verdict`, `Freshness::Evaluator`. No I/O, no globals, testable without disk.
-- **Infrastructure** (`lib/textus/infra/`) — Adapters: `EventBus`, `Clock`, `Refresh::Lock`, `Refresh::Detached`. Wrap OS / library primitives.
+- **Interface** (`lib/textus/cli/`, `lib/textus/mcp/`) — CLI verbs and the MCP gate. Parses flags / RPC, calls a use case, formats JSON.
+- **Application** (`lib/textus/application/`) — Use cases: `Read::Get`, `Write::Put`, `Write::RefreshWorker`, `Write::RefreshOrchestrator`, `Write::RefreshAll`, `Maintenance::Migrate`, etc. Orchestrate domain + infra; no business rules.
+- **Domain** (`lib/textus/domain/`) — Pure values: `Authorizer`, `Permission`, `Freshness::{Policy,Verdict,Evaluator}`, `Action`, `Outcome`, `Sentinel`, `Staleness`. No I/O, no globals, testable without disk.
+- **Infrastructure** (`lib/textus/infra/`) — Adapters: `Storage::FileStore`, `AuditLog`, `AuditSubscriber`, `Publisher`, `Clock`, `Refresh::Lock`, `Refresh::Detached`, `BuildLock`. Wrap OS / library primitives.
 
 The `lib/textus/store/`, `lib/textus/manifest/`, `lib/textus/hooks/` namespaces are infrastructure adapters that predate this split and remain at their existing paths for backward-compat with the plugin DSL.
 
@@ -899,14 +899,14 @@ Plugin authors interact only with the Hook DSL (`Textus.hook { |reg| reg.on(:res
 
 Both read and write paths flow through the application layer:
 
-- **Reads** flow through `Application::Reads::Get`, which takes a `Context` and dispatches refresh via `Application::Refresh::Orchestrator`.
-- **Writes** flow through `Application::Writes::{Put,Delete,Build,Accept,Publish}`, each taking a `Context`. Permission checks happen at the use-case layer (via `Context#can_write?`); I/O happens at `Store::Writer#write_envelope_to_disk` (pure).
-- `Application::Context` is the universal request object: it carries `store`, `role`, `correlation_id`, `clock`, and `dry_run`. Use cases never thread these as separate kwargs.
-- `Textus::Operations` is the factory CLI verbs (and future MCP server / HTTP shim)
-  use to construct Contexts and use cases. `Operations.for(store, role:)` returns
-  a flat facade exposing one method per use case (`#put`, `#get`, `#refresh`, …);
-  internal use-case instances are memoized via `||=` and live under
-  `lib/textus/application/{reads,writes,refresh}/`.
+- **Reads** flow through `Application::Read::Get` (pure read + freshness annotation) or `Read::GetOrRefresh` (composes Get with `Write::RefreshOrchestrator`). Each takes a `caps:` slice and an `Application::Context`.
+- **Writes** flow through `Application::Write::{Put,Delete,Mv,Accept,Reject,Publish,RefreshWorker}`. Permission checks happen at the use-case layer (via `Domain::Authorizer#authorize_write!`); the audit-append invariant lives in `Application::Envelope::Writer`.
+- `Application::Context` is the slim request record: `role`, `correlation_id`, `now`, `dry_run`. Ports come from a `Caps` record (Read/Write/Hook), not from the Context.
+- `Textus::Session` is the factory CLI verbs and the MCP gate use to dispatch
+  use cases. `Session.for(store, role:)` returns a per-call object exposing one
+  method per registered use case (`#put`, `#get`, `#refresh`, …); methods are
+  generated from `Application::UseCase.entries` so adding a use case is a
+  single `UseCase.register(...)` line.
 
 See `ARCHITECTURE.md` for an ASCII diagram and the full read-path walkthrough.
 

data/docs/conventions.md

@@ -126,6 +126,16 @@ Build always uses the pure path; injecting refresh into materialization caused t
 
 For multi-writer environments, **always pass `if_etag`** on `put`. The gem treats etag-less writes as last-writer-wins on purpose (single-writer scripts, fresh-file creation), but anything resembling a daemon or a long-running agent should round-trip the etag.
 
+## Application layering
+
+The application layer is organised around three patterns — `Manifest` as a composition record, capability slices (`Caps`) handed to use cases, 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 0020](architecture/decisions/0020-capability-records.md), and [ADR 0021](architecture/decisions/0021-session-and-module-use-cases.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(zone)`, `manifest.resolver.resolve(key)`, `manifest.rules.for(key)`. (The legacy top-level shims were removed in 0.26.0.)
+- **Application use cases take `session:`, `ctx:`, `caps:`** and are registered with `Application::UseCase.register(:verb, mod, caps: :read|:write)`. Each use case is a module with a `self.call(...)` entry point and a nested `class Impl` for state. `Caps` is a `Data.define` slice of the Store (`ReadCaps`, `WriteCaps`, `HookCaps`) — use cases pull only what they need into ivars; nobody passes the raw `Store` around the application layer.
+- **Write path is split**: `Application::Envelope::Reader` owns read/parse (existing-uid lookup, raw read, parse), and `Application::Envelope::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/3`) are unchanged.
+
 ## Pairing with other tools
 
 - **MCP servers**: a thin server that exposes `textus get` and `textus put` as tools is the recommended way to give Claude/agents access. Don't bake MCP into this gem.

data/lib/textus/application/caps.rb

@@ -0,0 +1,49 @@
+module Textus
+  module Application
+    # Capability records: role-scoped slices of the Store handed to use cases.
+    # Zeitwerk maps this file to Textus::Application::Caps; the three
+    # concrete cap types are also promoted to the Application namespace for
+    # concise reference (Application::ReadCaps, etc.).
+    module Caps
+      ReadCaps = Data.define(:manifest, :file_store, :schemas, :root, :audit_log, :events)
+
+      WriteCaps = Data.define(
+        :manifest, :file_store, :schemas, :root,
+        :audit_log, :events, :authorizer
+      ) do
+        def read
+          ReadCaps.new(
+            manifest: manifest, file_store: file_store, schemas: schemas, root: root,
+            audit_log: audit_log, events: events
+          )
+        end
+      end
+
+      HookCaps = Data.define(:events, :rpc, :manifest, :root)
+    end
+
+    # Promote to Application namespace for concise reference.
+    ReadCaps  = Caps::ReadCaps
+    WriteCaps = Caps::WriteCaps
+    HookCaps  = Caps::HookCaps
+
+    def self.caps_from_store(store)
+      read = ReadCaps.new(
+        manifest: store.manifest, file_store: store.file_store,
+        schemas: store.schemas, root: store.root,
+        audit_log: store.audit_log, events: store.events
+      )
+      write = WriteCaps.new(
+        manifest: store.manifest, file_store: store.file_store,
+        schemas: store.schemas, root: store.root,
+        audit_log: store.audit_log, events: store.events,
+        authorizer: Textus::Domain::Authorizer.new(manifest: store.manifest)
+      )
+      hook = HookCaps.new(
+        events: store.events, rpc: store.rpc,
+        manifest: store.manifest, root: store.root
+      )
+      [read, write, hook]
+    end
+  end
+end

data/lib/textus/application/context.rb

@@ -7,8 +7,8 @@ module Textus
     # writes should be suppressed (dry_run).
     #
     # Collaborators (manifest, file_store, bus, audit log, authorizer) are
-    # never read from Context — use cases declare them as explicit
-    # constructor ports, and Operations wires them in from the Store.
+    # never read from Context — use cases pull them from a Caps record
+    # (Read/Write/Hook) that Session derives from the Store.
     Context = Data.define(:role, :correlation_id, :now, :dry_run) do
       def self.build(role:, correlation_id: nil, now: nil, dry_run: false)
         new(

data/lib/textus/application/envelope/reader.rb

@@ -0,0 +1,44 @@
+module Textus
+  module Application
+    module Envelope
+      # Read-only counterpart to EnvelopeWriter. Resolves a key, reads the
+      # bytes, parses them via the format strategy, and hands back an
+      # Envelope. Used by Mv (pre-move inspection) and by EnvelopeWriter
+      # (existing-uid lookup for the uid-preservation step in #put).
+      #
+      # No audit, no events, no permission checks — those live one layer up.
+      class Reader
+        def initialize(file_store:, manifest:)
+          @file_store = file_store
+          @manifest   = manifest
+        end
+
+        def read(key)
+          res = @manifest.resolver.resolve(key)
+          path = res.path
+          return nil unless @file_store.exists?(path)
+
+          mentry = res.entry
+          raw = @file_store.read(path)
+          parsed = Entry.for_format(mentry.format).parse(raw, path: path)
+          Textus::Envelope.build(
+            key: key, mentry: mentry, path: path,
+            meta: parsed["_meta"], body: parsed["body"],
+            etag: Etag.for_bytes(raw), content: parsed["content"]
+          )
+        end
+
+        def existing_uid(key)
+          env = read(key)
+          env&.uid
+        rescue StandardError
+          nil
+        end
+
+        def exists?(key)
+          @file_store.exists?(@manifest.resolver.resolve(key).path)
+        end
+      end
+    end
+  end
+end