textus 0.29.0 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e8208a516e0a7760953e7c44a74fb459f168192ac4b0a20059b8686285f137a
-  data.tar.gz: 063deb01f793cec399a68620ce23bf1e9daf6d797edb985d919cb3bd6b9a1f87
+  metadata.gz: d84508fac499044df50d5fa793000fbd2249732c6b867f1b0f88535bfab4f083
+  data.tar.gz: 5069218d7c3c1a8360f4507bb99f94951e92a7d345ba4fb44ee72819fb4739e4
 SHA512:
-  metadata.gz: 29d392ea08bbd23f460761c1849c90d144a97b9e9208355818b364acbf72c708e2129c650ecf032a562b62271064094dac96ed5f6497c97128666e004959d47d
-  data.tar.gz: 2260fe709abe9685285cad7171e36def69a6e25047762c2077dcb4c70e670f8232123156b33b5811dfd79393592b563470819c641ff9508ec2b795f3b87065ad
+  metadata.gz: abf8e5e74b77227f34bbc95dd38c1e9b8d716f56f1cda11664f3da284f417d8581a51e4c27accdcb88173c274ff1aa929443bb027b851a95cbced029fdf34852
+  data.tar.gz: bd63c95ae46643c063c1b035fc859957418f185795fc32b54f798b44779d825101d9f71667a85f518dacab6ffbcebe70bc5676c9ae24e80cc9de4fa44e38aa38

data/ARCHITECTURE.md

@@ -48,7 +48,7 @@
 │  Ports::{AuditLog,AuditSubscriber,Publisher,Clock,         │
 │          Refresh::Lock,Refresh::Detached,BuildLock}        │
 │  Hooks::{EventBus,RpcRegistry,Loader,Context,FireReport,   │
-│          Builtin,ErrorLog}                                 │
+│          Signature,Builtin,ErrorLog}                       │
 │  Entry::{Markdown,Json,Yaml,Text}  (format strategies)     │
 └────────────────────────────────────────────────────────────┘
 
@@ -85,6 +85,8 @@ end
 
 Verbs are looked up in a static frozen table (`Textus::Dispatcher::VERBS`) that maps `:get → Textus::Read::Get`, `:put → Textus::Write::Put`, etc. `Store#put` / `Store#get` / `Store#as(role).<verb>(...)` instantiate the use case on `(container:, call:)` and invoke `#call`. Adding a new verb is **one entry in `Dispatcher::VERBS`** plus the class — no metaprogramming.
 
+The instantiate-and-call step itself has one home: `Dispatcher.invoke(verb, container:, call:, args:, kwargs:)` (ADR 0026). `RoleScope` builds the `Call` (request state) and delegates the dispatch to `Dispatcher.invoke`; the convention for invoking a uniform-shape use case lives next to the table that maps the verbs, not re-spelled in the caller. `Store`'s own verb loop is separate — it extracts the `role:` keyword and forwards to `as(role)`, a role-selection job distinct from invocation.
+
 `boot` and `doctor` are read verbs like any other: `Read::Boot` / `Read::Doctor`
 are thin `(container:, call:)` use cases that delegate to the `Textus::Boot` /
 `Textus::Doctor` report-builder libraries (`build(container:, ...)`). They are
@@ -134,6 +136,8 @@ Application use cases access ports only through `Container` fields — never thr
 
 The three public methods are `put`, `delete`, and `move`; all follow the same validate → write → audit sequence.
 
+Both are built from a `Container` via named constructors — `Writer.from(container:, call:)` (which builds its own `Reader.from`) and `Reader.from(container:)` (ADR 0026). Write use cases call `Writer.from` rather than reconstructing the object graph by hand, so a change to the Writer's dependencies is a one-line edit in one place.
+
 ## Manifest carving
 
 Manifest carving means slicing the parsed manifest YAML into four purpose-specific sub-objects. Each consumer sees only the fields it needs; none reach into the full raw document.
@@ -144,7 +148,7 @@ Manifest carving means slicing the parsed manifest YAML into four purpose-specif
 |---|---|---|
 | `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. |
+| `policy` | `Manifest::Policy` | Zone/role authority — `zone_writers`, `zone_kinds`, `permission_for`, `role_kind`, `roles_with_kind`, `propose_zone_for(role)`. Derived from a `Data` snapshot; no filesystem I/O. `propose_zone_for` owns the "first writable zone whose name contains `review`" convention used by `MCP::Server` (ADR 0027). |
 | `rules` | `Manifest::Rules` | Pattern-matched rule engine. `rules.for(key)` returns a `RuleSet(refresh, handler_allowlist, promote, retention)` by evaluating all `match:` blocks against the key. |
 
 Rationale: cleaner test seams — a use case that only needs key resolution constructs a `Manifest::Resolver` from a stub `Data`; one that only needs rule lookup constructs a `Manifest::Rules` directly. No consumer is forced to build the full manifest to exercise one sub-view.
@@ -214,6 +218,8 @@ Manifest drift surfaces as `ContractDrift` (manifest_etag mismatch); audit curso
 
 ## Hooks::EventBus event catalog
 
+`Hooks::Signature` is the single home of callable keyword-introspection — both `EventBus` (pub-sub dispatch) and `RpcRegistry` (RPC dispatch) delegate to it for `accepts_keyrest?`, `declared_keys`, `missing`, and `filter` rather than each maintaining a hand-rolled copy (ADR 0027).
+
 RPC (single handler, declares `caps:`):
 - `resolve_intake(caps:, config:, args:)` — intake fetch handler.
 - `transform_rows(caps:, rows:, config:)` — row transform for intakes.

data/CHANGELOG.md

@@ -9,6 +9,62 @@ 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.30.0 — 2026-05-29
+
+Explicit zone kind (strict) and entry retention (ADR 0028, moves 1 & 4). No wire format (`textus/3`) change.
+
+### Changed (BREAKING)
+
+- Zone `kind:` is now **required** on every zone (`origin | quarantine | queue | derived`); a manifest with a kind-less zone is rejected at load. The kind is authoritative: a zone is `derived` only if it declares `kind: derived`, and proposals route only to the zone declaring `kind: queue`. The previous writers→kind inference, the `"review"`-name proposal fallback, and boot's arbitrary-zone propose default were removed. No `textus/3` wire-format change; existing manifests must add `kind:` to every zone.
+
+### Added
+
+- `Manifest::Policy#declared_kind`, `#queue_zone`, `#derived_zone?`. `propose_zone_for` now resolves through the declared `queue` zone exclusively.
+- `retention:` rule block (`expire_after`, `archive_after`) parsed into `Domain::Policy::Retention`. New `textus retain --as=ROLE` sweep expires (deletes) or archives leaves past their window — `expire_after` deletes, `archive_after` copies to `.textus/archive/` then deletes; age is the leaf's mtime. `--prefix`/`--zone` narrow the sweep; rows whose zone the role can't write surface as failures. Retention appears in `textus rule explain`.
+- `Textus::Domain::Duration.seconds` — shared duration parser (`30s`/`90m`/`12h`/`30d`/bare seconds), now also backing `Refresh#ttl_seconds`.
+
+### Internal
+
+- `Manifest::Entry::Base#in_generator_zone?` and `boot` derived/proposal detection route through `Policy#derived_zone?` / `#propose_zone_for`; all `"review"` substring matches and the `Policy#zone_kinds` inference method are removed.
+- Dead `Policy#zone_kinds` method removed.
+
+## 0.29.2 — 2026-05-29
+
+Hook-registry convergence and MCP transport de-leak (ADR 0027). Every change is additive or internal — no wire format (`textus/3`) or manifest-schema change, no public class renamed or removed.
+
+### Added
+
+- `Textus::Hooks::Signature` — single home of callable keyword-introspection (`accepts_keyrest?`, `declared_keys`, `missing`, `filter`), shared by both `EventBus` and `RpcRegistry`.
+- `Manifest::Policy#propose_zone_for(role)` — owns the "first writable zone whose name contains `review`" convention; `MCP::Server#handle_initialize` delegates to it instead of scanning `manifest.data.zones` inline.
+
+### Internal
+
+- `EventBus` and `RpcRegistry` both delegate callable introspection to `Hooks::Signature`; both `shape_check!` copies and the hand-rolled `filter_kwargs`/`invoke` derivations are deleted.
+- Removed the `store:`→`caps:` legacy shim from `RpcRegistry`: a handler declaring `store:` (instead of `caps:`) is now rejected at registration time with an honest message, not at invoke time. Stale in-repo RPC hook fixtures and the `textus init` scaffold example are migrated to `caps:`.
+- `MCP::Server#handle_initialize` no longer iterates `manifest.data.zones`; it calls `policy.propose_zone_for(proposer)`. No zone-selection logic remains in the JSON-RPC transport handler.
+- `MCP::Session` converted from a hand-rolled immutable class to `Data.define(:role, :cursor, :propose_zone, :manifest_etag)`, matching the house convention used by all other value objects.
+
+### Behavior change (non-breaking in practice)
+
+- RPC handlers declaring `store:` previously registered successfully and failed only at first invocation (with a misleading message). They now fail at registration time with a message naming the correct kwarg (`caps:`). No handler using `store:` was valid before; only the timing and clarity of the error change.
+
+## 0.29.1 — 2026-05-29
+
+Construction-side cleanup of the use-case layer (ADR 0026). Every change is additive or internal — no public class renamed or removed, wire format (`textus/3`) and CLI unchanged.
+
+### Added
+
+- `Envelope::IO::Writer.from(container:, call:)` and `Envelope::IO::Reader.from(container:)` — named constructors that build the envelope IO collaborators from a `Container`. `Writer.new`/`Reader.new` are unchanged.
+- `Write::IntakeFetch.invoke(rpc:, handler:, config:, args:, label:, timeout:)` — the transport-side "invoke a `:resolve_intake` handler under a timeout" kernel; now the canonical home of `FETCH_TIMEOUT_SECONDS`.
+- `Dispatcher.invoke(verb, container:, call:, args:, kwargs:)` — single home for the uniform use-case invocation protocol.
+
+### Internal
+
+- `Write::{Put,Delete,Mv,RefreshWorker}` no longer hand-wire `Envelope::IO::Writer`/`Reader`; they call `Writer.from`. Removed ~60 lines of byte-identical construction boilerplate.
+- `cli/verb/put.rb` (`--fetch`) and `cli/verb/hook_run.rb` no longer inline `Timeout.timeout { store.rpc.invoke(:resolve_intake, …) }`; both route through `Write::IntakeFetch`. No intake-fetch mechanics remain under `lib/textus/cli/`.
+- `RoleScope`'s verb loop delegates the instantiate-and-call step to `Dispatcher.invoke`; it still builds the `Call`. `Store`'s role-selecting verb loop is unchanged.
+- `RefreshWorker::FETCH_TIMEOUT_SECONDS` is now an alias of `IntakeFetch::FETCH_TIMEOUT_SECONDS`.
+
 ## 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.

data/README.md

@@ -21,7 +21,7 @@ Without coordination, they overwrite each other and nothing remembers why. textu
 
 ```
 identity/   human only          — who you are, what you decide, how you sound
-working/    human + agent + runner — day-to-day catalog
+working/    human only          — day-to-day catalog (agents propose via review/, runners feed via intake/)
 intake/     runner only         — declared external inputs
 review/     agent + human       — proposals waiting on a human accept
 output/     builder only        — computed, published artifacts
@@ -37,7 +37,7 @@ That's the load-bearing claim: **coordination is a protocol invariant, not a lib
 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"}' \
+printf '%s' '{"_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
@@ -99,15 +99,15 @@ You get `.textus/` with all five zone directories, baseline schemas, an empty au
     output/           # builder only — computed outputs
 ```
 
-Manifest `path:` fields are relative to `.textus/zones/`. So `working.network.org.jane` lives at `.textus/zones/working/network/org/jane.md`.
+Manifest `path:` fields are relative to `.textus/zones/`. So `working.notes.org.jane` lives at `.textus/zones/working/notes/org/jane.md`.
 
 Read and write:
 
 ```sh
-textus get working.network.org.jane
+textus get working.notes.org.jane
 textus list --zone=working
-echo '{"_meta":{"name":"bob","org":"acme"},"body":"hi\n"}' \
-  | textus put working.network.org.bob --as=human --stdin
+printf '%s' '{"_meta":{"name":"bob","org":"acme"},"body":"hi\n"}' \
+  | textus put working.notes.bob --as=human --stdin
 textus freshness --zone=output       # per-entry fresh/stale/never_refreshed/no_policy
 textus rule list                     # show every rule block
 textus audit --limit=20              # query the audit log
@@ -124,10 +124,10 @@ For the full shape — Claude plugin with agents, skills, commands, pending walk
 - **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.
+- **Strict key grammar.** `/^[a-z0-9][a-z0-9-]*$/`, max 8 segments × 64 chars. `textus doctor` flags any illegal segments with a rename hint; `textus key mv old.key new.key` renames in place (uid survives).
 - **`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.
+- **`textus doctor`.** Health check across 15 checks — among them: 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.
 - **Compute.** Derived entries declare `compute: { kind: projection, ... }` (declarative rows + template) or `compute: { kind: external, ... }` (build runner produces the file; textus tracks sources for staleness). Inside projection computes, `transform:` names the row-shaping hook.
 
@@ -205,7 +205,7 @@ See [`docs/agent-integration.md`](docs/agent-integration.md) for the agent boot
 bundle exec rspec
 ```
 
-~880 examples; includes conformance fixtures A–I from SPEC §12.
+~920 examples; includes conformance fixtures A–I from SPEC §12.
 
 ## Code quality
 

data/SPEC.md

@@ -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:
@@ -201,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:
@@ -606,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 `**`.
 

data/lib/textus/boot.rb

@@ -128,7 +128,7 @@ 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],
@@ -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,

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::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::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::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::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" => {

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.rb

@@ -27,22 +27,25 @@ module Textus
     end
 
     def run(argv)
-      OptionParser.new { |o| o.on("--root=PATH") { |v| @root_arg = v } }.order!(argv)
+      # Define --version/--help ourselves so OptionParser doesn't intercept them
+      # with its built-in handlers (which print "version unknown" and a bare usage
+      # line, then exit before we ever reach the verb dispatch below).
+      show_version = false
+      show_help = false
+      OptionParser.new do |o|
+        o.on("--root=PATH") { |v| @root_arg = v }
+        o.on("--version", "-v") { show_version = true }
+        o.on("--help", "-h") { show_help = true }
+      end.order!(argv)
+
+      return @stdout.puts(VERSION) || 0 if show_version
+      return print_help || 0 if show_help
+
       verb = argv.shift
       raise UsageError.new("missing verb") if verb.nil?
 
-      result =
-        case verb
-        when "--version", "-v" then @stdout.puts(VERSION)
-                                    0
-        when "--help", "-h"    then print_help
-                                    0
-        else
-          klass = self.class.verbs[verb] or raise UsageError.new("unknown verb: #{verb}")
-          dispatch(klass, argv)
-        end
-
-      coerce_exit_code(result)
+      klass = self.class.verbs[verb] or raise UsageError.new("unknown verb: #{verb}")
+      coerce_exit_code(dispatch(klass, argv))
     rescue Textus::Error => e
       emit_error(e)
     end
@@ -94,9 +97,9 @@ module Textus
           textus doctor
           textus boot
 
-          textus key {mv,uid,normalize}
-          textus rule {list,explain}
-          textus schema {show,init,diff,migrate}
+          textus key {delete,mv,uid}
+          textus rule {explain,lint,list}
+          textus schema {diff,init,migrate,show}
           textus hook {list,run}
       HELP
     end

data/lib/textus/dispatcher.rb

@@ -13,6 +13,7 @@ module Textus
       publish: Textus::Write::Publish,
       refresh: Textus::Write::RefreshWorker,
       refresh_all: Textus::Write::RefreshAll,
+      retention_sweep: Textus::Write::RetentionSweep,
 
       # Read
       get: Textus::Read::Get,
@@ -33,6 +34,7 @@ module Textus
       validate_all: Textus::Read::ValidateAll,
       doctor: Textus::Read::Doctor,
       boot: Textus::Read::Boot,
+      retainable: Textus::Read::Retainable,
 
       # Maintenance
       migrate: Textus::Maintenance::Migrate,
@@ -45,5 +47,11 @@ module Textus
     def self.fetch(verb)
       VERBS.fetch(verb.to_sym) { raise UsageError.new("unknown verb: #{verb.inspect}") }
     end
+
+    # Single home for the uniform use-case invocation protocol (ADR 0023):
+    # look up the verb, construct on (container:, call:), and invoke #call.
+    def self.invoke(verb, container:, call:, args: [], kwargs: {})
+      fetch(verb).new(container: container, call: call).call(*args, **kwargs)
+    end
   end
 end

data/lib/textus/doctor/check.rb

@@ -28,11 +28,14 @@ module Textus
       def manifest = @container.manifest
       def rpc      = @container.rpc
 
-      # Dispatch a verb through the static Dispatcher table.
-      def dispatch(verb, *, **)
-        klass = Textus::Dispatcher.fetch(verb)
-        call_value = Textus::Call.build(role: Textus::Role::DEFAULT)
-        klass.new(container: @container, call: call_value).call(*, **)
+      # Dispatch a verb through the single use-case invocation seam (ADR 0026).
+      def dispatch(verb, *args, **kwargs)
+        Textus::Dispatcher.invoke(
+          verb,
+          container: @container,
+          call: Textus::Call.build(role: Textus::Role::DEFAULT),
+          args: args, kwargs: kwargs
+        )
       end
     end
   end

data/lib/textus/domain/duration.rb

@@ -0,0 +1,22 @@
+module Textus
+  module Domain
+    # Parses a duration value into whole seconds. Accepts a bare integer (or
+    # integer-string) of seconds, or `<n><unit>` with unit s/m/h/d. Returns
+    # nil for nil or any unparseable value.
+    module Duration
+      UNIT_SECONDS = { "s" => 1, "m" => 60, "h" => 3600, "d" => 86_400 }.freeze
+
+      def self.seconds(value)
+        return nil if value.nil?
+
+        str = value.to_s.strip
+        return str.to_i if str.match?(/\A\d+\z/)
+
+        m = str.match(/\A(\d+)\s*([smhd])\z/)
+        return nil unless m
+
+        m[1].to_i * UNIT_SECONDS.fetch(m[2])
+      end
+    end
+  end
+end

data/lib/textus/domain/policy/refresh.rb

@@ -21,21 +21,7 @@ module Textus
         end
 
         def ttl_seconds
-          return nil if @ttl.nil?
-
-          str = @ttl.to_s.strip
-          return str.to_i if str.match?(/\A\d+\z/)
-
-          m = str.match(/\A(\d+)\s*([smhd])\z/)
-          return nil unless m
-
-          n = m[1].to_i
-          case m[2]
-          when "s" then n
-          when "m" then n * 60
-          when "h" then n * 3600
-          when "d" then n * 86_400
-          end
+          Textus::Domain::Duration.seconds(@ttl)
         end
 
         def to_freshness_policy

data/lib/textus/domain/policy/retention.rb

@@ -0,0 +1,26 @@
+module Textus
+  module Domain
+    module Policy
+      # Lifetime policy for queue/quarantine leaves. Both windows are optional
+      # durations (see Domain::Duration). `expire_after` deletes; `archive_after`
+      # moves the leaf aside. When both are set, expire wins once its (longer)
+      # window is exceeded.
+      class Retention
+        attr_reader :expire_after, :archive_after
+
+        def initialize(expire_after: nil, archive_after: nil)
+          @expire_after  = Textus::Domain::Duration.seconds(expire_after)
+          @archive_after = Textus::Domain::Duration.seconds(archive_after)
+        end
+
+        # :expire | :archive | nil for a leaf of the given age (seconds).
+        def action_for(age_seconds)
+          return :expire  if @expire_after  && age_seconds > @expire_after
+          return :archive if @archive_after && age_seconds > @archive_after
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/textus/domain/retention.rb

@@ -0,0 +1,44 @@
+module Textus
+  module Domain
+    # Reports leaves whose age (now - file mtime) exceeds a retention window.
+    # Each row is { "key", "path", "action" => "expire"|"archive", "age_seconds" }.
+    class Retention
+      def initialize(manifest:, file_stat:, clock:)
+        @manifest  = manifest
+        @file_stat = file_stat
+        @clock     = clock
+      end
+
+      def call(prefix: nil, zone: nil)
+        @manifest.data.entries
+                 .select { |m| entry_matches?(m, prefix: prefix, zone: zone) }
+                 .flat_map { |m| rows_for(m) }
+      end
+
+      private
+
+      def rows_for(mentry)
+        policy = @manifest.rules.for(mentry.key).retention
+        return [] if policy.nil?
+
+        @manifest.resolver.enumerate(prefix: mentry.key).filter_map do |row|
+          path = row[:path]
+          next unless @file_stat.exists?(path)
+
+          age = (@clock.now - @file_stat.mtime(path)).to_i
+          action = policy.action_for(age)
+          next if action.nil?
+
+          { "key" => row[:key], "path" => path, "action" => action.to_s, "age_seconds" => age }
+        end
+      end
+
+      def entry_matches?(mentry, prefix:, zone:)
+        return false if zone && mentry.zone != zone
+        return false if prefix && !(mentry.key == prefix || mentry.key.start_with?("#{prefix}."))
+
+        true
+      end
+    end
+  end
+end

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

@@ -8,6 +8,10 @@ module Textus
       #
       # No audit, no events, no permission checks — those live one layer up.
       class Reader
+        def self.from(container:)
+          new(file_store: container.file_store, manifest: container.manifest)
+        end
+
         def initialize(file_store:, manifest:)
           @file_store = file_store
           @manifest   = manifest

data/lib/textus/envelope/io/writer.rb

@@ -14,6 +14,14 @@ module Textus
       class Writer
         Payload = Data.define(:meta, :body, :content)
 
+        def self.from(container:, call:)
+          new(
+            file_store: container.file_store, manifest: container.manifest,
+            schemas: container.schemas, audit_log: container.audit_log,
+            call: call, reader: Reader.from(container: container)
+          )
+        end
+
         def initialize(file_store:, manifest:, schemas:, audit_log:, call:, reader:)
           @file_store = file_store
           @manifest   = manifest