textus 0.26.0 → 0.30.0

data/SPEC.md

@@ -10,7 +10,7 @@
 
 ## 1. What textus is
 
-A storage convention and JSON wire protocol that lets humans, agents, and runners read and write structured project memory **deterministically**, with addressable dotted keys, schema validation, role-based write gates, declarative compute, and copy-based publish targets.
+A storage convention and JSON wire protocol for humans, agents, and runners to read and write structured project memory **deterministically**. It provides addressable dotted keys, schema validation, role-based write gates, declarative compute, and copy-based publish targets.
 
 The storage lives in a `.textus/` directory at the project root. Each entry is a Markdown file with YAML frontmatter. A manifest binds dotted keys to subtrees and declares which roles may write to each zone. Schemas (also YAML) define what frontmatter shape each entry must have. Derived entries are computed from other entries via pure projections and a vendored Mustache template engine, then optionally published to repo-relative paths as byte-for-byte file copies. The CLI surface (`textus get/put/list/where/schema/build/...` `--output=json`) returns a versioned envelope any caller can parse without knowing Markdown.
 
@@ -68,10 +68,10 @@ The root is `.textus/` at the project working directory. A typical tree:
 .textus/
   manifest.yaml          # internal: key → subtree mapping + zones declarations
   audit.log              # internal, append-only NDJSON log of every successful write
-  role                   # internal, role token (one line, e.g. "human")
   schemas/               # internal: YAML schema files
   templates/             # internal: Mustache templates referenced by derived entries
-  parsers/               # internal: project-local parser extensions
+  hooks/                 # internal: one Ruby file per hook
+  sentinels/             # internal: bookkeeping for byte-copied publish targets (see §5.3)
   zones/                 # ALL user content lives here
     identity/            # zone: identity (human-only)
     working/             # zone: working (human, agent, runner)
@@ -80,7 +80,7 @@ The root is `.textus/` at the project working directory. A typical tree:
     output/              # zone: output (builder only — computed outputs)
 ```
 
-Textus internals (`manifest.yaml`, `audit.log`, `role`, `schemas/`, `templates/`, `parsers/`) live directly under `.textus/`. **All user content lives under `.textus/zones/`.** Manifest `path:` fields are relative to `.textus/zones/` — they do **not** include the `zones/` prefix. Implementations MUST prepend `zones/` to every `path:` when resolving a key to a filesystem location.
+Textus internals (`manifest.yaml`, `audit.log`, `schemas/`, `templates/`, `hooks/`, `sentinels/`) live directly under `.textus/`. **All user content lives under `.textus/zones/`.** Manifest `path:` fields are relative to `.textus/zones/` — they do **not** include the `zones/` prefix. Implementations MUST prepend `zones/` to every `path:` when resolving a key to a filesystem location.
 
 Zone directories under `zones/` are conventional; their write semantics are declared in the manifest, not the directory name.
 
@@ -106,14 +106,19 @@ version: textus/3
 
 zones:
   - name: identity
+    kind: origin
     write_policy: [human]
   - name: working
+    kind: origin
     write_policy: [human, agent, runner]
   - name: intake
+    kind: quarantine
     write_policy: [runner]
   - name: review
+    kind: queue
     write_policy: [agent, human]
   - name: output
+    kind: derived
     write_policy: [builder]
 
 entries:
@@ -138,6 +143,10 @@ entries:
 rules:
   - match: intake.**
     refresh: { ttl: 6h, on_stale: warn }
+
+audit:
+  max_size: 10485760   # bytes before rotating (default: 10 485 760 = 10 MiB)
+  keep: 5              # rotated files to retain (default: 5)
 ```
 
 Zone names are conventional — the manifest is the source of truth for write permissions; rename freely.
@@ -197,16 +206,27 @@ A leaf at `working.skills.writing.voice-writer` (authored at `.textus/zones/work
 
 Each zone declares which **roles** may write to it via `write_policy:` in the manifest. An optional `read_policy:` (default `[all]`) gates reads. Writes are gated; reads are unrestricted by default.
 
-| Zone | `write_policy` | Use case |
-|---|---|---|
-| `identity` | `[human]` | Identity, voice, immutable principles — things only a human edits. |
-| `working` | `[human, agent, runner]` | Active project state: notes, decisions, network — what humans and agents update day-to-day. |
-| `intake` | `[runner]` | Declared external inputs (calendar, feeds, scraped pages). Refreshed by external runner scripts; never by humans or agents directly. |
-| `review` | `[agent, human]` | Agent-generated proposals awaiting human review via `textus accept`. Lets agents stage changes without touching `working`. |
-| `output` | `[builder]` | Computed outputs (catalogs, indexes, published context). Written only by the build runner via `textus build`. |
+| Zone | `kind` | `write_policy` | Use case |
+|---|---|---|---|
+| `identity` | `origin` | `[human]` | Identity, voice, immutable principles — things only a human edits. |
+| `working` | `origin` | `[human, agent, runner]` | Active project state: notes, decisions, network — what humans and agents update day-to-day. |
+| `intake` | `quarantine` | `[runner]` | Declared external inputs (calendar, feeds, scraped pages). Refreshed by external runner scripts; never by humans or agents directly. |
+| `review` | `queue` | `[agent, human]` | Agent-generated proposals awaiting human review via `textus accept`. Lets agents stage changes without touching `working`. |
+| `output` | `derived` | `[builder]` | Computed outputs (catalogs, indexes, published context). Written only by the build runner via `textus build`. |
 
 A write is gated by the caller's **role**, supplied via `--as=<role>`. If the role is not in the target zone's `write_policy` list, the write returns `write_forbidden`.
 
+Every zone MUST declare a `kind:` describing its role in the data-flow graph.
+The vocabulary is closed: `origin` (authored truth), `quarantine` (external
+bytes pending validation), `queue` (proposals awaiting promotion), `derived`
+(computed from other zones). A manifest MUST declare at most one `queue` zone,
+and a zone's `kind:` MUST agree with its writers (`derived` ⇒ a `generator`
+writer, `queue` ⇒ a `proposer`, `quarantine` ⇒ a `runner`; `origin` is
+unconstrained). Coordination is keyed off the declared kind: a zone is derived
+only if it declares `kind: derived`, and proposals route to the declared
+`queue` zone — there is no name-based fallback. A manifest with a kind-less
+zone is rejected at load.
+
 ### 5.1 Role resolution
 
 The effective role for any CLI invocation is resolved in this order; the first match wins:
@@ -397,7 +417,7 @@ In intake mode the handler MUST return one of three shapes, all normalized by th
 
 **Refresh paths.** Two are supported:
 
-1. **In-process** — `textus refresh KEY --as=runner` resolves the entry's `intake.handler`, invokes the registered `:resolve_intake` hook with `(config:, store:, args: {})`, and writes the result under role `runner`.
+1. **In-process** — `textus refresh KEY --as=runner` resolves the entry's `intake.handler`, invokes the registered `:resolve_intake` hook with `(caps:, config:, args: {})`, and writes the result under role `runner`.
 2. **External runner** — a cron job or agent harness reads `textus list --zone=intake --stale --output=json`, fetches the source out of band, and pipes bytes back through `textus put KEY --as=runner --stdin`. The CLI verb `textus refresh stale [--prefix=K] [--zone=Z]` drives this loop in one shot.
 
 Both paths share the same role gate, audit-log entry, and `:entry_refreshed` event. User-supplied hooks live in `.textus/hooks/**/*.rb` and auto-load at `Store#initialize` — see §5.10 for the full hook contract.
@@ -439,6 +459,35 @@ Schema (one JSON object per line, no interior whitespace):
 
 For `mv`, the structural fields `from_key`, `to_key`, and `uid` appear at the top level of the JSON object. Remaining verb-specific data (e.g. `from_path`, `to_path`) is nested under an `extras` key. The `extras` key is omitted entirely when empty.
 
+**Rotation.** After every successful append the implementation checks whether `audit.log` exceeds `max_size` bytes (checked inside the held `flock`, so the check sees the post-write size). If it does, the active log is rotated:
+
+1. The seq range (`min_seq`, `max_seq`) of the active log is scanned, and a JSON sidecar (`audit.log.1.meta.json`) is written with those values plus a `rotated_at` ISO 8601 timestamp.
+2. Existing rotated files are shifted: `audit.log.(N)` → `audit.log.(N+1)` for N = `keep-1` down to 1 (with their `.meta.json` sidecars).
+3. `audit.log` is renamed to `audit.log.1`.
+4. The file that would be shifted to `audit.log.(keep+1)` — i.e., `audit.log.keep` and its sidecar — is deleted before the shift.
+5. The next append creates a fresh `audit.log` via `O_CREAT`. Seq numbering continues from the previous maximum; there is no reset.
+
+Rotation is triggered by **byte size only** — there is no row-count or time-based trigger.
+
+**Rotation knobs** (configured via the optional `audit:` block in `manifest.yaml`):
+
+| Key        | Default      | Meaning |
+|------------|--------------|---------|
+| `max_size` | `10485760`   | Maximum size of `audit.log` in bytes (10 MiB) before rotation is triggered. |
+| `keep`     | `5`          | Number of rotated files retained on disk. When this limit is exceeded the oldest rotated file and its sidecar are deleted. |
+
+Both keys are optional. Omitting `audit:` entirely uses the defaults above.
+
+**`CursorExpired`.** When `audit --seq-since=N` or `pulse --since=N` is called with a cursor `N`, the implementation checks whether `N` is below the oldest sequence number still available on disk (`min_available_seq`, derived from the oldest retained rotated file's sidecar). The condition that raises `CursorExpired` is:
+
+```
+N < min_available_seq - 1
+```
+
+The error includes `requested` (the supplied cursor value) and `min_available` (the oldest seq still on disk).
+
+**Recommended caller behavior on `CursorExpired`.** Call `textus boot` (without `--since`) to obtain a fresh `latest_seq` from the current audit log state, then resume `pulse` calls using that new cursor. Do not attempt to replay from an expired cursor — the intervening rows are gone.
+
 ### 5.7 Security bounds
 
 textus enforces fixed bounds to keep behavior predictable under hostile or buggy input:
@@ -478,7 +527,7 @@ evolution:
 
 **Defaults:** when `fields:` and `evolution:` are absent, `schema.maintained_by(field)` returns `nil` for every field and `schema.evolution` returns `{}`.
 
-**Override rule:** the role `human` is permitted to write any `maintained_by` field, regardless of declared owner. This preserves human authority over agent/runner-managed data — humans curating canon over agent-written embeddings is a feature, not a bug. All other role mismatches are reported by `doctor --check=schema_violations` with code `role_authority`, including fields `key`, `field`, `expected`, and `last_writer`.
+**Override rule:** the role `human` is permitted to write any `maintained_by` field, regardless of declared owner. Humans override agent-maintained fields by design: schema field ownership (`maintained_by:`) makes the boundary explicit, not implicit. All other role mismatches are reported by `doctor --check=schema_violations` with code `role_authority`, including fields `key`, `field`, `expected`, and `last_writer`.
 
 ### 5.9 Row transforms
 
@@ -495,11 +544,11 @@ The subdirectory layout under `hooks/` is organizational only; the registered ev
 ```ruby
 # Canonical form — works for every event:
 Textus.hook do |reg|
-  reg.on(:resolve_intake,  :my_source)              { |config:, args:, **|  … }
-  reg.on(:transform_rows,  :rank_by_recency)         { |rows:, **|            … }
-  reg.on(:validate,        :storage_writable)        { |store:|               … }
-  reg.on(:entry_put,       :audit, keys: ["working.*"]) { |key:, envelope:, **| … }
-  reg.on(:file_published,  :git_add, keys: ["derived.*"]) { |target:, **| `git add #{target.shellescape}` }
+  reg.on(:resolve_intake,  :my_source)              { |caps:, config:, args:, **|  … }
+  reg.on(:transform_rows,  :rank_by_recency)         { |caps:, rows:, **|            … }
+  reg.on(:validate,        :storage_writable)        { |caps:|                        … }
+  reg.on(:entry_put,       :audit, keys: ["working.*"]) { |ctx:, key:, envelope:, **| … }
+  reg.on(:file_published,  :git_add, keys: ["derived.*"]) { |ctx:, target:, **| `git add #{target.shellescape}` }
 end
 ```
 
@@ -509,21 +558,21 @@ end
 
 | Event                   | Mode    | Args                                                      | Return                | Failure       |
 |-------------------------|---------|-----------------------------------------------------------|-----------------------|---------------|
-| `:resolve_intake`       | rpc     | store:, config:, args:                                    | {_meta:, body:}       | aborts op     |
-| `:transform_rows`       | rpc     | store:, rows:, config:                                    | rows array            | aborts op     |
-| `:validate`             | rpc     | store:                                                    | issues array          | aborts doctor |
-| `:entry_put`            | pubsub  | store:, key:, envelope:                                   | (discarded)           | logged        |
-| `:entry_deleted`        | pubsub  | store:, key:                                              | (discarded)           | logged        |
-| `:entry_refreshed`      | pubsub  | store:, key:, envelope:, change:                          | (discarded)           | logged        |
-| `:build_completed`      | pubsub  | store:, key:, envelope:, sources:                         | (discarded)           | logged        |
-| `:proposal_accepted`    | pubsub  | store:, key:, target_key:                                 | (discarded)           | logged        |
-| `:file_published`       | pubsub  | store:, key:, envelope:, source:, target:                 | (discarded)           | logged        |
-| `:entry_renamed`        | pubsub  | store:, key:, from_key:, to_key:, envelope:               | (discarded)           | logged        |
-| `:proposal_rejected`    | pubsub  | store:, key:, target_key:                                 | (discarded)           | logged        |
-| `:store_loaded`         | pubsub  | store:                                                    | (discarded)           | logged        |
-| `:refresh_started`      | pubsub  | store:, key:, mode:                                       | (discarded)           | logged        |
-| `:refresh_failed`       | pubsub  | store:, key:, error_class:, error_message:                | (discarded)           | logged        |
-| `:refresh_backgrounded` | pubsub  | store:, key:, started_at:, budget_ms:                     | (discarded)           | logged        |
+| `:resolve_intake`       | rpc     | caps:, config:, args:                                     | {_meta:, body:}       | aborts op     |
+| `:transform_rows`       | rpc     | caps:, rows:, config:                                     | rows array            | aborts op     |
+| `:validate`             | rpc     | caps:                                                     | issues array          | aborts doctor |
+| `:entry_put`            | pubsub  | ctx:, key:, envelope:                                     | (discarded)           | logged        |
+| `:entry_deleted`        | pubsub  | ctx:, key:                                                | (discarded)           | logged        |
+| `:entry_refreshed`      | pubsub  | ctx:, key:, envelope:, change:                            | (discarded)           | logged        |
+| `:build_completed`      | pubsub  | ctx:, key:, envelope:, sources:                           | (discarded)           | logged        |
+| `:proposal_accepted`    | pubsub  | ctx:, key:, target_key:                                   | (discarded)           | logged        |
+| `:file_published`       | pubsub  | ctx:, key:, envelope:, source:, target:                   | (discarded)           | logged        |
+| `:entry_renamed`        | pubsub  | ctx:, key:, from_key:, to_key:, envelope:                 | (discarded)           | logged        |
+| `:proposal_rejected`    | pubsub  | ctx:, key:, target_key:                                   | (discarded)           | logged        |
+| `:store_loaded`         | pubsub  | ctx:                                                      | (discarded)           | logged        |
+| `:refresh_started`      | pubsub  | ctx:, key:, mode:                                         | (discarded)           | logged        |
+| `:refresh_failed`       | pubsub  | ctx:, key:, error_class:, error_message:                  | (discarded)           | logged        |
+| `:refresh_backgrounded` | pubsub  | ctx:, key:, started_at:, budget_ms:                       | (discarded)           | logged        |
 
 The three `:refresh_*` lifecycle events report the progress and failures of background (timed_sync) refreshes.
 
@@ -533,14 +582,19 @@ The three `:refresh_*` lifecycle events report the progress and failures of back
 
 **`:refresh_backgrounded`** fires when a `timed_sync` refresh exceeds its budget and is handed off to a background thread. `started_at:` is an ISO-8601 UTC string; `budget_ms:` is the configured deadline as an integer.
 
-**Signature invariant** — every hook receives `store:` as its first keyword argument. Event-specific kwargs follow in stable left-to-right order. The primary entity is always `key:` (for `:proposal_accepted`, `key:` is the pending key being accepted and `target_key:` is the destination). For `:entry_renamed`, `key:` is present and equals `to_key:` — it is the entry's post-move home, present so `keys:` glob filters route correctly; `from_key:` is the prior key. For `:proposal_rejected`, `key:` is the pending key being rejected. For `:store_loaded`, no key — the event observes store readiness, not an entry.
+**Signature invariant** — hooks receive a capability handle as their first keyword argument; the name depends on the mode:
+
+- **RPC hooks** (`rpc` mode) receive `caps:` — a `Textus::Container`. Event-specific kwargs (`config:`, `args:`, `rows:`) follow in the stable order shown in the table above.
+- **Pub-sub hooks** (`pubsub` mode) receive `ctx:` — a `Textus::Hooks::Context` that exposes a narrow surface: `get`, `list`, `deps`, `freshness` (reads), `put`, `delete`, `audit` (authorized writes), `publish_followup`, plus `role` and `correlation_id`. The raw `Store` is not handed out.
+
+Declaring `store:` instead of `caps:` in an RPC callable will pass registration but raise `UsageError` at call time (`Hooks::RpcRegistry#invoke` rejects `store:` — there is no shim).
+
+The primary entity is always `key:` (for `:proposal_accepted`, `key:` is the pending key being accepted and `target_key:` is the destination). For `:entry_renamed`, `key:` is present and equals `to_key:` — it is the entry's post-move home, present so `keys:` glob filters route correctly; `from_key:` is the prior key. For `:proposal_rejected`, `key:` is the pending key being rejected. For `:store_loaded`, no key — the event observes store readiness, not an entry.
 
 **RPC mode** — exactly one handler per (event, name). The manifest references the handler by name (`intake.handler: NAME`, `compute.transform: NAME`). Failure or timeout aborts the calling operation.
 
 **Pub-sub mode** — zero or more handlers per event. All matching handlers fire. The `keys:` option restricts a handler to keys matching one of the given globs (`File.fnmatch?` rules). Absence of `keys:` fires on every event of that type. Handler failures and 2s timeouts are logged to `audit.log` as `event_error` rows; they NEVER abort the triggering operation.
 
-The `store:` argument is always a read-only store proxy. Write attempts raise `UsageError`.
-
 Each handler runs under `Timeout.timeout(2)`.
 
 ### 5.11 Rules
@@ -568,7 +622,15 @@ rules:
 | `refresh` | `{ ttl, on_stale, sync_budget_ms }` | Freshness budget for intake entries. `on_stale` is `warn` (default), `sync`, or `timed_sync`. |
 | `intake_handler_allowlist` | list of strings | Constrains which `intake.handler:` names may be used by entries matched by this block. Enforced by `textus doctor`. |
 | `promotion` | `{ requires: [...] }` | Predicates a `review` entry must satisfy before `textus accept` will promote it. Built-in predicates: `schema_valid` (entry passes schema validation) and `human_accept` (the accepting role must be `human`). Additional predicates may be registered via `:validate` hooks. Enforced — `textus accept` refuses if any predicate fails. |
-| `retention` | (reserved) | Slot reserved for future retention policy (cap by age / count). Implementations parse it but otherwise ignore. |
+| `retention` | `{ expire_after:, archive_after: }` | Pruning policy for matched leaves. Duration strings: `30s`, `90m`, `12h`, `30d`, or bare integer seconds. `textus retain --as=ROLE` sweeps matched leaves: `expire_after` is checked first, so a leaf older than `expire_after` is deleted (and audited); otherwise a leaf older than `archive_after` is copied to `<store>/archive/<relative-path>` and then deleted. Age is measured from the leaf file's modification time. The `--as` role must be allowed to write the matched zone. |
+
+Both retention windows are optional, and `expire_after` is evaluated before
+`archive_after` — so when both apply, a leaf past the (longer) `expire_after`
+window is deleted rather than archived. The usual configuration is therefore
+`archive_after < expire_after` (archive a leaf, then delete it once older).
+`textus retain --as=ROLE` runs the sweep; `--prefix` and `--zone` narrow it, and
+any leaf whose zone the `--as` role cannot write is reported as a failure rather
+than aborting the run.
 
 **Match grammar.** `match:` is a single glob using `*` (single segment) and `**` (any depth). A literal segment ranks more specifically than `*`; `*` ranks more specifically than `**`.
 
@@ -899,14 +961,13 @@ 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::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.
+- **Reads** flow through `Textus::Read::Get` (pure read + freshness annotation) or `Read::GetOrRefresh` (composes Get with `Write::RefreshOrchestrator`). Each takes a `container:` and a `call:`.
+- **Writes** flow through `Textus::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 `Textus::Envelope::IO::Writer`.
+- `Textus::Call` is the slim per-invocation record: `role`, `correlation_id`, `now`, `dry_run`. Ports come from `Textus::Container`, not from the Call.
+- `Textus::Store` is the composition root and verb dispatcher. CLI verbs and the
+  MCP gate call `store.<verb>(..., role:)` (or `store.as(role).<verb>(...)`).
+  Verbs are looked up in the static `Textus::Dispatcher::VERBS` table; adding a
+  use case is a single entry in `VERBS` plus the class.
 
 See `ARCHITECTURE.md` for an ASCII diagram and the full read-path walkthrough.
 
@@ -914,7 +975,7 @@ See `ARCHITECTURE.md` for an ASCII diagram and the full read-path walkthrough.
 
 - **Locking on `put`:** the reference impl uses sha256 etags. Should the spec also define a file-lock fallback for systems where read-before-write is racy?
 - **Schema imports:** can one schema reference another (`type: $ref: person`)?
-- **Internationalization:** non-ASCII in keys? Spec currently restricts segments to `[a-z0-9_-]`. Revisit if community wants Unicode.
+- **Internationalization:** non-ASCII in keys? Spec currently restricts segments to `[a-z0-9][a-z0-9-]*`. Revisit if community wants Unicode.
 - **Generated content in `derived/`:** the spec says `schema: null` is allowed, but should there be a separate marker (`generated: true`) for clarity?
 
 ## 15. Implementation checklist

data/docs/conventions.md

@@ -128,11 +128,11 @@ For multi-writer environments, **always pass `if_etag`** on `put`. The gem treat
 
 ## 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).
+The application layer is organised around three shapes — `Manifest` as a composition record, a single `Container` capability record handed to every use case, and a split envelope reader/writer. See [ADR 0018](architecture/decisions/0018-manifest-carving.md), [ADR 0017](architecture/decisions/0017-envelope-io-split.md), [ADR 0022](architecture/decisions/0022-container-call-dispatcher.md), and [ADR 0023](architecture/decisions/0023-uniform-use-case-shape.md).
 
-- **`Manifest` is a composition record** (`Data.define(:data, :resolver, :policy, :rules)`). Reach individual concerns through the field accessors: `manifest.data.entries`, `manifest.policy.permission_for(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(...)`).
+- **`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)`.
+- **Use cases are plain `(container:, call:)` classes.** Each is a single class under `lib/textus/{read,write,maintenance}/` with `def initialize(container:, call:)` and a `#call(...)` method; verbs are looked up in the static `Textus::Dispatcher::VERBS` table. `Container` is a `Data.define` record bundling the wired ports + manifest (`manifest`, `file_store`, `schemas`, `root`, `audit_log`, `events`, `rpc`, `authorizer`); `Call` is the immutable per-invocation value (`role`, `correlation_id`, `now`, `dry_run`). A use case that emits events derives its `Hooks::Context` from `(container, call)` — nothing is injected. Use cases pull only what they need into ivars; nobody passes the raw `Store` around the application layer. `store.as(role)` returns a `RoleScope` that forwards verbs to the dispatcher.
+- **Write path is split**: `Envelope::IO::Reader` owns read/parse (existing-uid lookup, raw read, parse), and `Envelope::IO::Writer` owns put/delete/move + the audit-append invariant (every public method's final action is `@audit_log.append(...)`).
 
 The user-facing CLI surface, the wire envelope shape, and the protocol version (`textus/3`) are unchanged.
 

data/lib/textus/boot.rb

@@ -120,7 +120,7 @@ module Textus
         "summary" => "delta since cursor — changed entries, stale, pending review, doctor summary" },
     ].freeze
 
-    def self.agent_quickstart(manifest, session)
+    def self.agent_quickstart(manifest, audit_log)
       proposer_roles = manifest.policy.roles_with_kind(:proposer)
       agent_role = proposer_roles.first
 
@@ -128,14 +128,14 @@ module Textus
         acc << zname if agent_role && writers.include?(agent_role)
       end
 
-      propose_zone = writable_zones.find { |z| z.include?("review") } || writable_zones.first
+      propose_zone = manifest.policy.propose_zone_for(agent_role)
 
       {
         "read_verbs" => %w[boot get list audit pulse freshness doctor],
         "write_verbs" => agent_role ? ["put KEY --as=#{agent_role} --stdin"] : [],
         "writable_zones" => writable_zones,
         "propose_zone" => propose_zone,
-        "latest_seq" => session.write_caps.audit_log.latest_seq,
+        "latest_seq" => audit_log.latest_seq,
       }
     end
 
@@ -150,18 +150,18 @@ module Textus
       )
     end
 
-    def self.run(session)
-      manifest = session.read_caps.manifest
+    def self.build(container:)
+      manifest = container.manifest
       {
         "protocol" => PROTOCOL_ID,
-        "store_root" => session.read_caps.root,
+        "store_root" => container.root,
         "zones" => zones_for(manifest),
         "entries" => entries_for(manifest),
-        "hooks" => hooks_for(session),
+        "hooks" => hooks_for_container(container),
         "write_flows" => write_flows_for(manifest),
         "cli_verbs" => CLI_VERBS.map(&:dup),
         "agent_protocol" => agent_protocol(manifest),
-        "agent_quickstart" => agent_quickstart(manifest, session),
+        "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
         "docs" => { "spec" => "SPEC.md", "example" => "examples/claude-plugin/" },
       }
     end
@@ -169,6 +169,8 @@ module Textus
     def self.zones_for(manifest)
       manifest.data.zones.map do |name, writers|
         row = { "name" => name, "writers" => Array(writers) }
+        kind = manifest.policy.declared_kind(name)
+        row["kind"] = kind.to_s if kind
         purpose = ZONE_PURPOSES[name]
         row["purpose"] = purpose if purpose
         row
@@ -177,7 +179,7 @@ module Textus
 
     def self.entries_for(manifest)
       manifest.data.entries.map do |e|
-        derived = manifest.policy.zone_kinds(e.zone).include?(:generator)
+        derived = manifest.policy.derived_zone?(e.zone)
         {
           "key" => e.key,
           "zone" => e.zone,
@@ -193,13 +195,17 @@ module Textus
       end
     end
 
-    def self.hooks_for(session)
+    def self.hooks_for_container(container)
+      hooks_for_container_internal(rpc: container.rpc, events: container.events)
+    end
+
+    def self.hooks_for_container_internal(rpc:, events:)
       sections = {}
       Hooks::RpcRegistry::EVENTS.each_key do |event|
-        sections[event.to_s] = session.rpc.names(event).map(&:to_s).sort
+        sections[event.to_s] = rpc.names(event).map(&:to_s).sort
       end
       Hooks::EventBus::EVENTS.each_key do |event|
-        sections[event.to_s] = session.events.pubsub_handlers(event).map { |h| h[:name].to_s }.sort
+        sections[event.to_s] = events.pubsub_handlers(event).map { |h| h[:name].to_s }.sort
       end
       sections
     end

data/lib/textus/builder/pipeline.rb

@@ -53,6 +53,10 @@ module Textus
     end
 
     module Pipeline
+      Deps = Data.define(
+        :manifest, :reader, :lister, :rpc, :template_loader, :transform_context, :inject_boot
+      )
+
       def self.renderers
         @renderers ||= {
           "markdown" => Renderer::Markdown,
@@ -62,37 +66,34 @@ module Textus
         }
       end
 
-      # rubocop:disable Metrics/ParameterLists
-      def self.run(mentry:, manifest:, reader:, lister:, rpc:, template_loader:,
-                   transform_context: nil, inject_boot: nil)
+      def self.run(mentry:, deps:)
         # 1. Load sources + project + reduce
         data =
           if mentry.is_a?(Textus::Manifest::Entry::Derived) && mentry.projection?
-            Application::Projection.new(
-              reader: reader,
+            Textus::Projection.new(
+              reader: deps.reader,
               spec: mentry.source.to_h.transform_keys(&:to_s),
-              lister: lister,
-              rpc: rpc,
-              transform_context: transform_context,
+              lister: deps.lister,
+              rpc: deps.rpc,
+              transform_context: deps.transform_context,
             ).run
           else
             { "entries" => [], "count" => 0, "generated_at" => Time.now.utc.iso8601 }
           end
-        data = data.merge("boot" => inject_boot.call) if mentry.inject_boot && inject_boot
+        data = data.merge("boot" => deps.inject_boot.call) if mentry.inject_boot && deps.inject_boot
 
         # 2. Render
         klass = renderers[mentry.format] or
           raise UsageError.new("builder: unsupported format #{mentry.format.inspect} for '#{mentry.key}'")
-        bytes = klass.new(template_loader: template_loader).call(mentry: mentry, data: data)
+        bytes = klass.new(template_loader: deps.template_loader).call(mentry: mentry, data: data)
 
         # 3. Write (idempotent: skip if only generated_at would differ)
-        target_path = Key::Path.resolve(manifest.data, mentry)
+        target_path = Key::Path.resolve(deps.manifest.data, mentry)
         FileUtils.mkdir_p(File.dirname(target_path))
         write_if_changed(target_path, bytes, mentry.format)
 
         target_path
       end
-      # rubocop:enable Metrics/ParameterLists
 
       def self.write_if_changed(target_path, bytes, format)
         if File.exist?(target_path)

data/lib/textus/call.rb

@@ -0,0 +1,28 @@
+require "securerandom"
+
+module Textus
+  # Immutable per-invocation value. Carries who is acting (role), the
+  # request correlation id, the wall clock, and the dry_run flag — the
+  # bits Use Cases need that are not part of the Container.
+  Call = Data.define(:role, :correlation_id, :now, :dry_run) do
+    def self.build(role:, correlation_id: nil, now: nil, dry_run: false)
+      new(
+        role: role.to_s,
+        correlation_id: correlation_id || SecureRandom.uuid,
+        now: now || Textus::Ports::Clock.now,
+        dry_run: dry_run,
+      )
+    end
+
+    def dry_run? = dry_run
+
+    def with_role(new_role)
+      self.class.new(
+        role: new_role.to_s,
+        correlation_id: correlation_id,
+        now: now,
+        dry_run: dry_run,
+      )
+    end
+  end
+end

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

@@ -15,7 +15,7 @@ module Textus
 
         def call(store)
           ops = session_for(store)
-          since_time = since && Textus::Application::Read::Audit.parse_since(since, now: ops.ctx.now)
+          since_time = since && Textus::Read::Audit.parse_since(since, now: Time.now)
           rows = ops.audit(
             key: key_filter,
             zone: zone,

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

@@ -5,7 +5,7 @@ module Textus
         command_name "boot"
 
         def call(store)
-          emit(Textus::Boot.run(Textus::Session.for(store)))
+          emit(store.boot)
         end
       end
     end

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

@@ -7,9 +7,9 @@ module Textus
         option :prefix, "--prefix=K"
 
         def call(store)
-          Textus::Infra::BuildLock.with(root: store.root) do
+          Textus::Ports::BuildLock.with(root: store.root) do
             role = store.manifest.policy.roles_with_kind(:generator).first || "builder"
-            ops = store.session(role: role)
+            ops = store.as(role)
             result = ops.publish(prefix: prefix)
             emit(result)
           end

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

@@ -8,7 +8,7 @@ module Textus
 
         def call(store)
           check_list = checks&.split(",")&.map(&:strip)
-          res = Textus::Doctor.run(Textus::Session.for(store), checks: check_list)
+          res = store.doctor(checks: check_list)
           emit(res, exit_code: res["ok"] ? 0 : 1)
         end
       end

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

@@ -29,12 +29,8 @@ module Textus
           Role.resolve(flag: as_flag, env: ENV, root: store.root)
 
           begin
-            Timeout.timeout(Textus::Application::Write::RefreshWorker::FETCH_TIMEOUT_SECONDS) do
-              store.rpc.invoke(:resolve_intake, name, caps: nil, config: {}, args: args)
-            end
-          rescue Timeout::Error
-            raise UsageError.new(
-              "hook run '#{name}' exceeded #{Textus::Application::Write::RefreshWorker::FETCH_TIMEOUT_SECONDS}s timeout",
+            Textus::Write::IntakeFetch.invoke(
+              rpc: store.rpc, handler: name, config: {}, args: args, label: "hook run",
             )
           rescue Textus::Error
             raise

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

@@ -17,19 +17,10 @@ module Textus
           raw = @stdin.read
           payload =
             if fetch_name
-              result =
-                begin
-                  Timeout.timeout(Textus::Application::Write::RefreshWorker::FETCH_TIMEOUT_SECONDS) do
-                    store.rpc.invoke(:resolve_intake, fetch_name,
-                                     caps: nil,
-                                     config: { "bytes" => raw },
-                                     args: {})
-                  end
-                rescue Timeout::Error
-                  raise UsageError.new(
-                    "fetch '#{fetch_name}' exceeded #{Textus::Application::Write::RefreshWorker::FETCH_TIMEOUT_SECONDS}s timeout",
-                  )
-                end
+              result = Textus::Write::IntakeFetch.invoke(
+                rpc: store.rpc, handler: fetch_name,
+                config: { "bytes" => raw }, args: {}, label: "fetch"
+              )
               basename = key.split(".").last
               {
                 "_meta" => {
@@ -46,7 +37,7 @@ module Textus
           meta = payload["_meta"] || {}
           body = payload["body"] || ""
           if_etag = payload["if_etag"]
-          result = store.session(role: role).put(key, meta: meta, body: body, if_etag: if_etag)
+          result = store.as(role).put(key, meta: meta, body: body, if_etag: if_etag)
           emit(result.to_h_for_wire)
         end
       end

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

@@ -0,0 +1,19 @@
+module Textus
+  class CLI
+    class Verb
+      class Retain < Verb
+        command_name "retain"
+
+        option :prefix, "--prefix=KEY"
+        option :zone, "--zone=Z"
+        option :as_flag, "--as=ROLE"
+
+        def call(store)
+          result = session_for(store).retention_sweep(prefix: prefix, zone: zone)
+          emit(result)
+          result["ok"] ? 0 : 1
+        end
+      end
+    end
+  end
+end

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

@@ -18,7 +18,7 @@ module Textus
             end
             row["handler_allowlist"] = b.handler_allowlist.handlers if b.handler_allowlist
             row["promotion"] = { "requires" => b.promote.requires } if b.promote
-            row["retention"] = b.retention if b.retention
+            row["retention"] = { "expire_after" => b.retention.expire_after, "archive_after" => b.retention.archive_after } if b.retention
             row
           end
           emit({ "verb" => "policy_list", "policies" => policies })

data/lib/textus/cli/verb.rb

@@ -96,16 +96,16 @@ module Textus
         Role.resolve(flag: flag, env: ENV, root: store.root)
       end
 
-      # Returns an Application::Context bound to the resolved role.
-      # Convenience for verbs whose only pre-call boilerplate is
-      # resolving the role and wrapping it in a context.
+      # Returns a Call value bound to the resolved role. Convenience for
+      # verbs whose only pre-call boilerplate is resolving the role and
+      # wrapping it in a Call.
       def context_for(store)
-        store.session(role: resolved_role(store)).ctx
+        Textus::Call.build(role: resolved_role(store))
       end
 
-      # Returns a Session instance bound to the resolved role.
+      # Returns a RoleScope bound to the resolved role.
       def session_for(store)
-        store.session(role: resolved_role(store))
+        store.as(resolved_role(store))
       end
     end
   end