textus 0.22.0 → 0.29.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.
 
@@ -138,6 +138,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.
@@ -397,7 +401,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 +443,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 +511,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 +528,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 +542,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 +566,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
@@ -888,10 +926,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 +937,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::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 `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 +951,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

@@ -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 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)`.
+- **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.
+
 ## 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/boot.rb

@@ -26,7 +26,7 @@ module Textus
         "edit files in identity/working zones, then 'textus put KEY --as=#{name}'"
       end,
       proposer: lambda do |name, manifest|
-        authority = manifest.roles_with_kind(:accept_authority).first || "accept_authority"
+        authority = manifest.policy.roles_with_kind(:accept_authority).first || "accept_authority"
         "propose changes by writing review.* entries with --as=#{name} and a 'proposal:' frontmatter block; " \
           "the #{authority} role runs 'textus accept' to apply"
       end,
@@ -39,7 +39,7 @@ module Textus
     }.freeze
 
     def self.write_flows_for(manifest)
-      manifest.role_mapping.each_with_object({}) do |(name, kind), acc|
+      manifest.policy.role_mapping.each_with_object({}) do |(name, kind), acc|
         tmpl = WRITE_FLOW_TEMPLATES[kind]
         acc[name] = tmpl.call(name, manifest) if tmpl
       end
@@ -120,11 +120,11 @@ module Textus
         "summary" => "delta since cursor — changed entries, stale, pending review, doctor summary" },
     ].freeze
 
-    def self.agent_quickstart(manifest, store)
-      proposer_roles = manifest.roles_with_kind(:proposer)
+    def self.agent_quickstart(manifest, audit_log)
+      proposer_roles = manifest.policy.roles_with_kind(:proposer)
       agent_role = proposer_roles.first
 
-      writable_zones = manifest.zones.each_with_object([]) do |(zname, writers), acc|
+      writable_zones = manifest.data.zones.each_with_object([]) do |(zname, writers), acc|
         acc << zname if agent_role && writers.include?(agent_role)
       end
 
@@ -135,7 +135,7 @@ module Textus
         "write_verbs" => agent_role ? ["put KEY --as=#{agent_role} --stdin"] : [],
         "writable_zones" => writable_zones,
         "propose_zone" => propose_zone,
-        "latest_seq" => store.audit_log.latest_seq,
+        "latest_seq" => audit_log.latest_seq,
       }
     end
 
@@ -144,29 +144,30 @@ module Textus
         "role_resolution" => {
           "summary" => "write role is resolved in order: --as flag, TEXTUS_ROLE env var, .textus/role file, " \
                        "default 'human'",
-          "roles" => manifest.role_mapping.keys,
+          "roles" => manifest.policy.role_mapping.keys,
           "ref" => "SPEC.md §5",
         },
       )
     end
 
-    def self.run(store)
+    def self.build(container:)
+      manifest = container.manifest
       {
         "protocol" => PROTOCOL_ID,
-        "store_root" => store.root,
-        "zones" => zones_for(store),
-        "entries" => entries_for(store),
-        "hooks" => hooks_for(store),
-        "write_flows" => write_flows_for(store.manifest),
+        "store_root" => container.root,
+        "zones" => zones_for(manifest),
+        "entries" => entries_for(manifest),
+        "hooks" => hooks_for_container(container),
+        "write_flows" => write_flows_for(manifest),
         "cli_verbs" => CLI_VERBS.map(&:dup),
-        "agent_protocol" => agent_protocol(store.manifest),
-        "agent_quickstart" => agent_quickstart(store.manifest, store),
+        "agent_protocol" => agent_protocol(manifest),
+        "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
         "docs" => { "spec" => "SPEC.md", "example" => "examples/claude-plugin/" },
       }
     end
 
-    def self.zones_for(store)
-      store.manifest.zones.map do |name, writers|
+    def self.zones_for(manifest)
+      manifest.data.zones.map do |name, writers|
         row = { "name" => name, "writers" => Array(writers) }
         purpose = ZONE_PURPOSES[name]
         row["purpose"] = purpose if purpose
@@ -174,9 +175,9 @@ module Textus
       end
     end
 
-    def self.entries_for(store)
-      store.manifest.entries.map do |e|
-        derived = store.manifest.zone_kinds(e.zone).include?(:generator)
+    def self.entries_for(manifest)
+      manifest.data.entries.map do |e|
+        derived = manifest.policy.zone_kinds(e.zone).include?(:generator)
         {
           "key" => e.key,
           "zone" => e.zone,
@@ -192,16 +193,17 @@ module Textus
       end
     end
 
-    def self.hooks_for(store)
-      bus = store.bus
+    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::Bus::EVENTS.each do |event, spec|
-        case spec[:mode]
-        when :rpc
-          sections[event.to_s] = bus.rpc_names(event).map(&:to_s).sort
-        when :pubsub
-          sections[event.to_s] = bus.pubsub_handlers(event).map { |h| h[:name].to_s }.sort
-        end
+      Hooks::RpcRegistry::EVENTS.each_key do |event|
+        sections[event.to_s] = rpc.names(event).map(&:to_s).sort
+      end
+      Hooks::EventBus::EVENTS.each_key do |event|
+        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:, transform_resolver:, 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,
-              transform_resolver: transform_resolver,
-              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, 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/group/mcp.rb

@@ -0,0 +1,9 @@
+module Textus
+  class CLI
+    class Group
+      class MCP < Group
+        command_name "mcp"
+      end
+    end
+  end
+end

data/lib/textus/cli/group/zone.rb

@@ -0,0 +1,9 @@
+module Textus
+  class CLI
+    class Group
+      class Zone < Group
+        command_name "zone"
+      end
+    end
+  end
+end

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

@@ -8,7 +8,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("accept requires a key")
-          emit(operations_for(store).accept(key))
+          emit(session_for(store).accept(key))
         end
       end
     end

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

@@ -14,8 +14,8 @@ module Textus
         option :limit, "--limit=N"
 
         def call(store)
-          ops = operations_for(store)
-          since_time = since && Textus::Application::Reads::Audit.parse_since(since, now: ops.ctx.now)
+          ops = session_for(store)
+          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/blame.rb

@@ -8,7 +8,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("blame requires a key")
-          rows = operations_for(store).blame(key: key, limit: limit&.to_i)
+          rows = session_for(store).blame(key: key, limit: limit&.to_i)
           emit({ "verb" => "blame", "key" => key, "rows" => rows })
         end
       end

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

@@ -5,7 +5,7 @@ module Textus
         command_name "boot"
 
         def call(store)
-          emit(Textus::Boot.run(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
-            role = store.manifest.roles_with_kind(:generator).first || "builder"
-            ops = Textus::Operations.for(store, role: role)
+          Textus::Ports::BuildLock.with(root: store.root) do
+            role = store.manifest.policy.roles_with_kind(:generator).first || "builder"
+            ops = store.as(role)
             result = ops.publish(prefix: prefix)
             emit(result)
           end

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

@@ -9,7 +9,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("delete requires a key")
-          emit(operations_for(store).delete(key, if_etag: if_etag))
+          emit(session_for(store).delete(key, if_etag: if_etag))
         end
       end
     end

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

@@ -6,7 +6,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("deps requires a key")
-          emit({ "key" => key, "deps" => operations_for(store).deps(key) })
+          emit({ "key" => key, "deps" => session_for(store).deps(key) })
         end
       end
     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(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/freshness.rb

@@ -8,7 +8,7 @@ module Textus
         option :zone, "--zone=Z"
 
         def call(store)
-          rows = operations_for(store).freshness(prefix: prefix, zone: zone)
+          rows = session_for(store).freshness(prefix: prefix, zone: zone)
           emit({ "verb" => "freshness", "rows" => rows })
         end
       end

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

@@ -8,7 +8,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("get requires a key")
-          result = operations_for(store).get_or_refresh(key)
+          result = session_for(store).get_or_refresh(key)
           raise Textus::UnknownKey.new(key, suggestions: store.manifest.resolver.suggestions_for(key)) if result.nil?
 
           emit(result.to_h_for_wire)

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

@@ -27,15 +27,14 @@ module Textus
           end
 
           Role.resolve(flag: as_flag, env: ENV, root: store.root)
-          callable = store.bus.rpc_callable(:resolve_intake, name)
 
           begin
-            Timeout.timeout(Textus::Application::Refresh::Worker::FETCH_TIMEOUT_SECONDS) do
-              callable.call(config: {}, store: store, args: args)
+            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::Application::Refresh::Worker::FETCH_TIMEOUT_SECONDS}s timeout",
+              "hook run '#{name}' exceeded #{Textus::Write::RefreshWorker::FETCH_TIMEOUT_SECONDS}s timeout",
             )
           rescue Textus::Error
             raise