textus 0.15.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54b9e7266b017d02abba0f6daeba977c580c07f1bdab798ebc7a9b943be555cd
-  data.tar.gz: 47ebf2a56523dbf33058fe95c45163899a6f7b91500a2f749ce3d731e60ab502
+  metadata.gz: 3d7915be053bc7e858c821e0e8d8e8cebd3de6acde21dcd8f687ff3fa12db3d1
+  data.tar.gz: 792cd40df3e8046c954be84dc32d4e53a2b47cdfd9a21029c74953d39e182a87
 SHA512:
-  metadata.gz: 76abb1c22c3f519574dfd310a7ff2162b023bbbc8667b2e4dc2c32edbb94d432bf507620116dbcbc1f7ce3328964515ee8eded62abe1c833249b3b2bb1bd9fce
-  data.tar.gz: a405b5d81159c8dd0638e9ca6f4fca419358792c7a3a29f64cb0b19386553f37aa091f913c65ad078a039205ad6ac0368af681eba455fcb4c1787bcfb213ac05
+  metadata.gz: 457d079d8ebf25922f9389086ec2de99b96808f23fba7f600655fb2ef055a5a987dd1ea63924aaf9904c7f4e600b4aee33a8c2082028bbb9025068aa00de3b0e
+  data.tar.gz: a1192a6027b80582723b0cb4679b870ed78101864e22700ba7630308912f46000e774dbd69c589418516047dff2f8cdbf7a26e69e47d3a7ffcef89f917397a23

data/ARCHITECTURE.md

@@ -3,16 +3,16 @@
 ```
 ┌─ Interface ────────────────────────────────────────────────┐
 │  CLI verbs:  ops = Operations.for(store, role:)            │
-│              ops.reads.<name>.call(...)                    │
-│              ops.writes.<name>.call(...)                   │
-│              ops.refresh.<name>.call(...)                  │
+│              ops.<name>(...)   # flat methods, one per use │
+│                                # case (put/get/refresh/…)  │
 └──────────────────────┬─────────────────────────────────────┘
                        │
 ┌─ Application ────────▼─────────────────────────────────────┐
 │  Context          (per-request: store, role, correlation,  │
 │                    clock, dry_run; can_read?/can_write?;   │
+│                    authorize_read!/authorize_write!; bus;  │
 │                    Context.system(store) for infra path)   │
-│  Operations       (facade with .reads/.writes/.refresh)    │
+│  Operations       (flat facade — memoized use cases)       │
 │                                                            │
 │  reads/{get,list,where,uid,schema_envelope,deps,rdeps,     │
 │         published,stale,validate_all,freshness,audit,      │
@@ -48,10 +48,10 @@
    imports. Application imports Domain + Infra (via ports).
 ```
 
-## Read path (`ops.reads.get.call(key)`)
+## Read path (`ops.get(key)`)
 
-1. CLI verb (or any external caller) builds `ops = Textus::Operations.for(store, role:)` then `ops.reads.get.call(key)`.
-2. `Operations::Reads#get` returns an `Application::Reads::Get.new(ctx:, orchestrator:)` instance bound to the request context.
+1. CLI verb (or any external caller) builds `ops = Textus::Operations.for(store, role:)` then `ops.get(key)`.
+2. `Operations#get` delegates to a memoized `Application::Reads::Get.new(ctx:, orchestrator:)` instance bound to the request context.
 3. `Reads::Get#call(key)` reads the bare envelope from disk via `@ctx.store.reader.read_raw_envelope(key)`.
 4. Resolves the manifest rules for the key via `@ctx.store.manifest.rules_for(key)` and extracts the `refresh` policy.
 5. `Domain::Freshness::Evaluator.call(policy, envelope, now:)` returns a `Verdict`.
@@ -63,10 +63,10 @@
    - `Action::RefreshTimed(budget_ms:)` → race Worker thread vs budget; on timeout, kill thread, fire `:refresh_backgrounded`, fork+detach child, return `Outcome::Detached`
 9. Map outcome → envelope annotations (`stale`, `refreshing`, `refresh_error`) and return.
 
-## Write path (`ops.writes.put.call(key, ...)`)
+## Write path (`ops.put(key, ...)`)
 
-1. CLI verb calls `ops = Operations.for(store, role:)` then `ops.writes.put.call(key, meta:, body:, content:, if_etag:, suppress_events:)`.
-2. `Writes::Put#call` validates the key, resolves the manifest entry, and checks `@ctx.can_write?(mentry.zone)` — raises `WriteForbidden` if denied.
+1. CLI verb calls `ops = Operations.for(store, role:)` then `ops.put(key, meta:, body:, content:, if_etag:, suppress_events:)`.
+2. `Writes::Put#call` validates the key, resolves the manifest entry, and calls `@ctx.authorize_write!(mentry)` — raises `WriteForbidden` (carrying the zone's writers list) if denied.
 3. Delegates raw I/O to `Store::Writer#write_envelope_to_disk(key, mentry:, payload:, ctx:, if_etag:)`, which:
    - Resolves the path via `Manifest#resolve`
    - Serializes via `Entry.for_format(...).serialize(...)`
@@ -74,13 +74,13 @@
    - Etag-checks if `if_etag:` provided (raises `EtagMismatch` on conflict)
    - Writes to disk via `File.binwrite`
    - Appends the audit row
-4. On success, publishes `:entry_put` via the bus, with `store: @ctx.with_role(@ctx.role)`, `key:`, `envelope:`, `correlation_id:`.
+4. On success, publishes `:entry_put` via `@ctx.bus`, with `store: @ctx.with_role(@ctx.role)`, `key:`, `envelope:`, `correlation_id:`.
 
-The same pattern applies to `Writes::{Delete,Mv,Accept,Reject,Build,Publish}`: each takes a `Context`, checks permissions at the use-case layer, delegates raw I/O to `Store::Writer` or `Infra::Publisher`, and fires the matching event.
+The same pattern applies to `Writes::{Delete,Mv,Accept,Reject,Build,Publish}`: each takes a `Context`, calls `ctx.authorize_write!` (Mv authorizes both source and destination zones), delegates raw I/O to `Store::Writer` or `Infra::Publisher`, and fires the matching event through `ctx.bus`.
 
-## Refresh path (`ops.refresh.worker.run(key)`)
+## Refresh path (`ops.refresh(key)`)
 
-1. CLI `Verb::Refresh` builds `ops = Operations.for(store, role: "runner")` then calls `ops.refresh.worker.run(key)`.
+1. CLI `Verb::Refresh` builds `ops = Operations.for(store, role: "runner")` then calls `ops.refresh(key)`.
 2. `Refresh::Worker#run(key)`:
    - Resolves the manifest entry, looks up the intake handler via `store.registry.rpc_callable(:resolve_intake, mentry.intake_handler)`.
    - Publishes `:refresh_started` via the bus.

data/CHANGELOG.md

@@ -9,6 +9,319 @@ 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.18.0 — 2026-05-27
+
+Port extraction finishes the hexagonal trajectory. `Store::Reader` and
+`Store::Writer` were disguised application code under an infra
+namespace; this release replaces them with a true I/O port
+(`Infra::Storage::FileStore`, bytes only) and lifts their orchestration
+into `Application::Writes::EnvelopeIO` and the existing
+`Application::Reads::*`. `Store` becomes a composition root: nothing
+else. Wire format (`textus/3`) and audit log NDJSON line format are
+byte-identical to 0.17.0 — every change is gem-side.
+
+### Breaking (Ruby API)
+
+- **`Store::Reader` and `Store::Writer` are deleted.** Both classes
+  were doing application work (serialize, UID inject, name-match,
+  schema validate, etag negotiate, audit append, event publish) under
+  an infra label. Their methods move to flat `Operations` calls:
+  ```
+  store.reader.get(key)                  →  Textus::Operations#get(key)
+  store.reader.read_raw_envelope(key)    →  Textus::Operations#get(key)
+  store.reader.list(prefix:, zone:)      →  Textus::Operations#list(prefix:, zone:)
+  store.reader.where(key)                →  Textus::Operations#where(key)
+  store.reader.uid(key)                  →  Textus::Operations#uid(key)
+  store.reader.schema_envelope(key)      →  Textus::Operations#schema_envelope(key)
+  store.reader.published                 →  Textus::Operations#published
+  store.reader.stale(...)                →  Textus::Operations#stale(...)
+  store.reader.deps(key)                 →  Textus::Operations#deps(key)
+  store.reader.rdeps(key)                →  Textus::Operations#rdeps(key)
+  store.reader.validate_all              →  Textus::Operations#validate_all
+
+  store.writer.write_envelope_to_disk    →  Textus::Operations#put(key, ...)
+  store.writer.delete_envelope_from_disk →  Textus::Operations#delete(key, ...)
+  ```
+- **`Store#schema_for(name)` is deleted.** Schemas live on a dedicated
+  cache:
+  ```
+  store.schema_for(name)                 →  store.schemas.fetch(name)
+  ```
+- **Infra/Domain relocations.** Files that were `Store::*` because the
+  namespace was a catch-all now live in the layer they belong to:
+  ```
+  Textus::Store::AuditLog                →  Textus::Infra::AuditLog
+  Textus::Store::Sentinel                →  Textus::Domain::Sentinel
+  Textus::Store::Staleness               →  Textus::Domain::Staleness
+  Textus::Store::Validator               →  Textus::Application::Reads::Validator
+  ```
+- **Write use-case constructors take `envelope_io:`.**
+  `Application::Writes::Put.new(ctx:, envelope_io:)` — same for
+  `Delete` and `Mv`. External code that constructed write use cases
+  directly adds the kwarg.
+- **Note.** Most embedders construct use cases via
+  `Textus::Operations.for(store)`. That constructor still works
+  without changes — `Operations#for` wires `envelope_io:` from the
+  store. Embedders on the recommended path see no breakage.
+
+### Added
+
+- **`Textus::Infra::Storage::FileStore`** — pure I/O port. `read`,
+  `write`, `delete`, `exists?`, `etag` — bytes in, bytes out. No
+  serialization, no schema, no manifest, no events. The seam that
+  makes non-file storage backends possible.
+- **`Textus::Schemas`** — eager-loading schema cache. Reads the
+  `_schemas/**` zone at boot, exposes `fetch(name)` and `each`.
+  Replaces the on-demand `Store#schema_for` lookup.
+- **`Textus::Application::Writes::EnvelopeIO`** — the write pipeline
+  collaborator. Serializes the envelope, validates against its
+  schema, negotiates etag, writes via `FileStore`, appends to audit,
+  publishes the event. The shared orchestration that `Put`,
+  `Delete`, and `Mv` previously duplicated through `Store::Writer`.
+
+### Internal
+
+- **`Store` is a composition root.** Its responsibilities are
+  construction and exposure: `manifest`, `schemas`, `file_store`,
+  `audit_log`, `bus`, `registry`, `root`. No `reader`, no `writer`,
+  no `schema_for`. Hook loading (`load_hooks`) and operations
+  exposure (`operations`) remain — both delegate to dedicated
+  collaborators.
+- **Read use cases read from `file_store`/`manifest`/`schemas`
+  directly.** `Reads::Get`, `Reads::List`, `Reads::Where`,
+  `Reads::Stale`, `Reads::Deps`, etc., no longer route through a
+  reader facade. The path is `Operations → use case → ports`.
+
+### Wire format / audit format
+
+Unchanged. `textus/3` envelopes written by 0.17.0 round-trip through
+0.18.0 byte-for-byte; audit log NDJSON lines are bidirectionally
+compatible.
+
+### Migrating from 0.17
+
+Mechanical for embedders; transparent for CLI users.
+
+```
+# Reads
+store.reader.get(key)        →  ops.get(key)
+store.reader.list(prefix: x) →  ops.list(prefix: x)
+store.reader.stale(...)      →  ops.stale(...)
+# (and the rest of the table above)
+
+# Writes — recommended path stays the same
+ops.put(key, body: x)        # unchanged
+
+# Schemas
+store.schema_for(name)       →  store.schemas.fetch(name)
+
+# Renames
+Textus::Store::AuditLog      →  Textus::Infra::AuditLog
+Textus::Store::Sentinel      →  Textus::Domain::Sentinel
+Textus::Store::Staleness     →  Textus::Domain::Staleness
+Textus::Store::Validator     →  Textus::Application::Reads::Validator
+```
+
+## 0.17.0 — 2026-05-27
+
+API and policy reshape. The public Ruby surface flattens, authorization
+moves from seven duplicated blocks into one helper on `Application::Context`,
+and the only thread-local in the library is gone. Wire format (`textus/3`)
+and CLI JSON output are byte-identical to 0.16.0. Every change is gem-side.
+
+### Breaking (Ruby API)
+
+- **`Operations` is flat.** The `Operations#reads`, `Operations#writes`,
+  and `Operations#refresh` namespace shells are removed; every use case
+  is now a directly-named method on `Operations` itself. Callers that
+  typed three levels of indirection plus `.call` switch to a single
+  method call:
+  ```ruby
+  ops.writes.put.call(key, body: x)   →   ops.put(key, body: x)
+  ops.reads.get.call(key)             →   ops.get(key)
+  ops.reads.get_or_refresh.call(key)  →   ops.get_or_refresh(key)
+  ops.refresh.worker.call(key)        →   ops.refresh(key)
+  ops.refresh.all.call(prefix:, …)    →   ops.refresh_all(prefix:, …)
+  ```
+  Internal use-case instances are memoized via `||=`. `Operations#with_role`
+  returns a fresh `Operations` with no shared memoization.
+- **`Operations::Reads`, `Operations::Writes`, `Operations::Refresh`** —
+  the shell classes — are deleted. External code that named them
+  directly (rare) must move to the flat methods on `Operations`.
+- **Top-level `Textus.on(event, name) { ... }` is removed.** Hook files
+  now wrap registration in a `Textus.hook` block that receives the
+  store's registry:
+  ```ruby
+  # before
+  Textus.on(:entry_put, "audit") { |store:, key:, **| ... }
+  # after
+  Textus.hook do |reg|
+    reg.on(:entry_put, "audit") { |store:, key:, **| ... }
+  end
+  ```
+  Multiple `reg.on` lines under one `Textus.hook` block is idiomatic.
+- **`Textus.with_registry` is removed.** Tests instantiate
+  `Textus::Hooks::Registry.new` and call `reg.on(...)` directly — no
+  `around` block, no thread-local cleanup.
+- **`Textus::Hooks::Loader.current_registry` is removed.** It was the
+  thread-local read accessor; nothing replaces it because no thread-
+  local remains.
+- **Write use-case constructors lose `bus:`.** `Application::Writes::*`
+  classes pull the bus from `@ctx.bus` instead of taking it as a kwarg.
+  External code that constructed `Writes::Put.new(ctx:, bus:)` directly
+  drops the `bus:` argument.
+
+### Added
+
+- **`Application::Context#authorize_write!(mentry)`** — raises
+  `WriteForbidden` (with the zone's writers list in `details`) when the
+  bound role lacks write permission. Returns `nil` on success. Replaces
+  the seven duplicated `unless can_write? ... raise WriteForbidden`
+  blocks across `Writes::{Put,Delete,Mv,Accept,Reject,Build,Publish}`.
+- **`Application::Context#authorize_read!(mentry)`** — mirror of
+  `authorize_write!`. Raises a new `ReadForbidden` (code `read_forbidden`,
+  exit 1, details: `key`, `zone`, `readers`).
+- **`Application::Context#bus`** — returns `store.bus`. Use cases publish
+  events through `@ctx.bus`; the prior `@ctx.store.bus` reach-through is
+  no longer used in-tree.
+- **`Textus::ReadForbidden`** error class. Symmetric with `WriteForbidden`.
+- **`Textus.hook(&blk)`** — appends the supplied block to a mutex-
+  guarded module-level queue. The store-scoped loader drains and invokes
+  each block with its registry.
+- **`Textus.drain_hook_blocks`** — public for tests; returns and clears
+  the queued blocks under the same mutex.
+- **`Textus::Hooks::Registry#on`** — already the canonical instance API
+  since 0.11; explicitly documented as the registration primitive now
+  that the top-level shim is gone.
+
+### Internal
+
+- **`Application::Writes::Mv`** now authorizes both source and
+  destination zones. The prior code authorized only the source; the
+  centralized `authorize_write!` made the second call a one-liner and
+  the gap obvious.
+- **`Hooks::Builtin.register_all`** takes a `registry:` argument and
+  calls `registry.on(...)` directly. No thread-local read.
+- **`Hooks::Loader`** is now a per-store class constructed with
+  `registry:`. `#load_dir(path)` walks the directory, `load`s each
+  `.rb`, then drains `Textus.drain_hook_blocks` and invokes each with
+  the registry. Two threads loading two stores concurrently are safe
+  because each `load_dir` drains around its own file walk under the
+  module-level mutex.
+- **`Doctor::Check::Hooks`** reads `store.registry` directly; no
+  thread-local indirection.
+- **`Store#load_hooks`** is a two-liner: construct a `Loader` with
+  `@registry`, call `load_dir` against `.textus/hooks/`.
+- **Reads/refresh paths** use `@ctx.bus` instead of `@ctx.store.bus`.
+  Same object; the indirection is gone.
+
+### Migrating from 0.16
+
+Mechanical, sed-friendly. The CLI shape is unchanged — only embedders
+and hook authors need to do anything.
+
+```
+# Operations: flat surface
+ops.writes.put.call(key, body: x)   →   ops.put(key, body: x)
+ops.reads.get.call(key)             →   ops.get(key)
+ops.reads.get_or_refresh.call(key)  →   ops.get_or_refresh(key)
+ops.refresh.worker.call(key)        →   ops.refresh(key)        # via Operations#refresh
+ops.refresh.all.call(...)           →   ops.refresh_all(...)
+
+# Hooks: explicit registration
+Textus.on(:entry_put, "x") { |e| ... }
+  →
+Textus.hook do |reg|
+  reg.on(:entry_put, "x") { |e| ... }
+end
+
+# Tests: no more thread-local scope
+around { |ex| Textus.with_registry(reg) { ex.run } }   # delete
+Textus.on(:resolve_intake, :x) { ... }                 # → reg.on(:resolve_intake, :x) { ... }
+```
+
+If you constructed `Writes::Put` (or any other write use case)
+directly, drop the `bus:` kwarg from the constructor call. If you
+constructed `Hooks::Loader` directly, the new signature is
+`Loader.new(registry:)` and the API is `loader.load_dir(path)`.
+
+### ADRs
+
+- [ADR 0010 — Flat Operations API](docs/architecture/decisions/0010-flat-operations-api.md)
+- [ADR 0011 — Authorize-bang in Context](docs/architecture/decisions/0011-authorize-bang-in-context.md)
+- [ADR 0012 — Explicit hook registration](docs/architecture/decisions/0012-explicit-hook-registration.md)
+
+## 0.16.0 — 2026-05-26
+
+Type cleanup and infra glue. Wire format (`textus/3`) and CLI JSON output
+are byte-identical to 0.15.0. Every change is gem-side.
+
+### Breaking (Ruby API)
+
+- **`Envelope#freshness`** is now a `Textus::Domain::Freshness` value (a
+  `Data.define(:stale, :refreshing, :reason, :refresh_error, :checked_at,
+  :ttl_remaining_ms)`), not a `Hash`. Field access replaces string-key
+  lookup: `env.freshness.stale` (was `env.freshness["stale"]`). The
+  field formerly emitted as `"stale_reason"` on the wire is named
+  `:reason` on the value object; `Freshness#to_h_for_wire` still emits
+  `"stale_reason"`, so JSON output is unchanged. New fields
+  (`:checked_at`, `:ttl_remaining_ms`) are gem-side only and not on the
+  wire.
+- **`Manifest#resolve(key)`** now returns a `Textus::Manifest::Resolution`
+  value (`Data.define(:entry, :path, :remaining)`) instead of an
+  `[entry, path, remaining]` tuple. Callers that destructured the array
+  must switch to field access: `res = manifest.resolve(key); res.entry`.
+  Raises `UnknownKey` on miss (unchanged).
+- **`Textus::Store.mint_uid`** is removed. Use `Textus::Uid.mint`. A
+  companion `Textus::Uid.valid?(str)` predicate is added.
+- **`Hooks::Dispatcher.new(audit_log:)`** no longer accepts
+  `audit_log:`. The dispatcher is now a pure pub/sub. Hook-error audit
+  rows are written by `Textus::Infra::AuditSubscriber`, which `Store`
+  attaches at boot. The NDJSON audit line format is unchanged
+  byte-for-byte.
+
+### Added
+
+- `Textus::Domain::Freshness` — typed envelope-annotation value object.
+- `Textus::Manifest::Resolution` — typed key-resolution value object.
+- `Textus::Uid` — `.mint` / `.valid?` for the 16-hex UID format.
+- `Textus::Infra::AuditSubscriber` — attaches to the event bus and
+  writes the `verb: "event_error"` audit row when a user hook raises.
+- `CLI::Verb.command_name "X"` and `CLI::Verb.parent_group Group::Y`
+  DSL. Adding a new CLI verb is now a single declaration in the verb's
+  own file; the top-level `VERBS` table and group subcommand maps are
+  auto-derived from descendants. Help-output ordering is alphabetical
+  by command name.
+
+### Changed
+
+- `CLI::Group` no longer exposes the `cli_name` writer — use
+  `command_name` (the prior `cli_name` reader is removed).
+- `Application::Reads::Get` and `Reads::GetOrRefresh` construct
+  `Freshness` values directly; their public signatures are unchanged.
+
+### Deprecated
+
+- `Textus::CLI::VERBS` constant. Still resolves (via `const_missing` to
+  the auto-derived table) for backward compatibility; will be removed
+  in a future minor. Prefer `Textus::CLI.verbs`.
+
+### Notes for embedders
+
+- Group subcommand error messages now list subcommands alphabetically
+  (e.g., `key requires a subcommand: mv, normalize, uid` rather than
+  `mv, uid, normalize`).
+- Lifecycle audit appends for `verb: "put"` / `"delete"` / `"rename"`
+  still flow through `Store::Writer` and `Application::Writes::Mv`.
+  Centralizing those in a lifecycle subscriber is deferred to 0.18
+  port-extraction; it requires event payloads to carry
+  `etag_before`/`etag_after`, which they don't yet.
+
+### ADRs
+
+- [ADR 0008 — Freshness and Resolution value objects](docs/architecture/decisions/0008-freshness-and-resolution-types.md)
+- [ADR 0009 — AuditSubscriber split from Hooks::Dispatcher](docs/architecture/decisions/0009-audit-subscriber-split.md)
+
 ## 0.15.0 — 2026-05-26
 
 ### Breaking

data/README.md

@@ -14,7 +14,7 @@ Reference implementation in Ruby. Wire format `textus/3`. SPEC: [`SPEC.md`](SPEC
 Two versions, deliberately independent:
 
 - **Protocol wire string:** `textus/3`. Breaking changes require `textus/4`.
-- **Gem version:** semver, currently `0.14.0`. Decoupled from the protocol string — internal refactors bump the gem; only wire-format changes bump the protocol.
+- **Gem version:** semver, currently `0.18.0`. Decoupled from the protocol string — internal refactors bump the gem; only wire-format changes bump the protocol.
 
 Envelope payloads carry the `protocol` field. The gem version is irrelevant to the wire format.
 
@@ -119,18 +119,22 @@ textus exposes a hook DSL. Drop `.rb` files into `.textus/hooks/` (subdirectorie
 
 ```ruby
 # Inside .textus/hooks/local_file.rb
-Textus.on(:resolve_intake, :local_file) do |config:, args:, **|
-  path = config["path"] or raise "local-file requires intake.config.path"
-  {
-    _meta: { "last_refreshed_at" => Time.now.utc.iso8601, "source_path" => path },
-    body: File.read(File.expand_path(path)),
-  }
+Textus.hook do |reg|
+  reg.on(:resolve_intake, :local_file) do |config:, args:, **|
+    path = config["path"] or raise "local-file requires intake.config.path"
+    {
+      _meta: { "last_refreshed_at" => Time.now.utc.iso8601, "source_path" => path },
+      body: File.read(File.expand_path(path)),
+    }
+  end
 end
 ```
 
 ```ruby
-Textus.on(:transform_rows, :rank_by_recency) do |rows:, **|
-  rows.sort_by { |r| r["updated_at"].to_s }.reverse
+Textus.hook do |reg|
+  reg.on(:transform_rows, :rank_by_recency) do |rows:, **|
+    rows.sort_by { |r| r["updated_at"].to_s }.reverse
+  end
 end
 ```
 

data/SPEC.md

@@ -450,7 +450,7 @@ Row transforms are RPC hooks on the `:transform_rows` event. See §5.10.
 
 ### 5.10 Hooks
 
-textus has a single hook registration verb: `Textus.on(event, name, **opts) { ... }`. The EVENTS table below defines every extension point. Files in `.textus/hooks/**/*.rb` are `load`ed at `Store#initialize` in alphabetical order by full path.
+textus has a single hook registration verb: `Textus.hook { |reg| reg.on(event, name, **opts) { ... } }`. The EVENTS table below defines every extension point. Files in `.textus/hooks/**/*.rb` are `load`ed at `Store#initialize` in alphabetical order by full path; the store-scoped loader drains the queued blocks and invokes each with its own registry.
 
 The subdirectory layout under `hooks/` is organizational only; the registered event and name come from the DSL call, not the file path.
 
@@ -458,14 +458,16 @@ The subdirectory layout under `hooks/` is organizational only; the registered ev
 
 ```ruby
 # Canonical form — works for every event:
-Textus.on(:resolve_intake,  :my_source)              { |config:, args:, **|  … }
-Textus.on(:transform_rows,  :rank_by_recency)         { |rows:, **|            … }
-Textus.on(:validate,        :storage_writable)        { |store:|               … }
-Textus.on(:entry_put,       :audit, keys: ["working.*"]) { |key:, envelope:, **| … }
-Textus.on(:file_published,  :git_add, keys: ["derived.*"]) { |target:, **| `git add #{target.shellescape}` }
+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}` }
+end
 ```
 
-`Textus.on` is the sole entry point; there is no separate `Textus.hook` primitive.
+`Textus.hook` is the sole entry point. The block receives the store's `Hooks::Registry`; `reg.on` is the only registration primitive.
 
 #### Event table
 
@@ -821,7 +823,7 @@ Textus internals are organized into four layers. The dependency rule is one-way
 
 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.
 
-Plugin authors interact only with the Hook DSL (`Textus.on(:resolve_intake, ...)`, `Textus.on(:entry_refreshed, ...)`, etc.) and the manifest YAML schema. The layering is internal and may evolve.
+Plugin authors interact only with the Hook DSL (`Textus.hook { |reg| reg.on(:resolve_intake, ...) }`, `reg.on(:entry_refreshed, ...)`, etc.) and the manifest YAML schema. The layering is internal and may evolve.
 
 Both read and write paths flow through the application layer:
 
@@ -830,8 +832,9 @@ Both read and write paths flow through the application layer:
 - `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 memoized facade with `.reads`, `.writes`, and `.refresh` namespaces mirroring the
-  files under `lib/textus/application/{reads,writes,refresh}/`.
+  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}/`.
 
 See `ARCHITECTURE.md` for an ASCII diagram and the full read-path walkthrough.
 

data/docs/conventions.md

@@ -111,8 +111,8 @@ There are two read operations, and the difference matters in custom code:
 
 | Operation | Triggers refresh? | Use for |
 |-----------|-------------------|---------|
-| `ops.reads.get` | No — pure read of on-disk envelope + freshness verdict | build / materialization paths, schema tooling, any context where a side-effecting read would surprise the caller |
-| `ops.reads.get_or_refresh` | Yes — composes `get` with the orchestrator per the rule's `on_stale` policy | interactive reads (`textus get`, dashboards) where the caller wants the freshest envelope obtainable |
+| `ops.get` | No — pure read of on-disk envelope + freshness verdict | build / materialization paths, schema tooling, any context where a side-effecting read would surprise the caller |
+| `ops.get_or_refresh` | Yes — composes `get` with the orchestrator per the rule's `on_stale` policy | interactive reads (`textus get`, dashboards) where the caller wants the freshest envelope obtainable |
 
 Build always uses the pure path; injecting refresh into materialization caused the cascading-staleness incident behind issue #59. Pick `get_or_refresh` only when you genuinely want side effects on read.
 

data/lib/textus/application/context.rb

@@ -34,6 +34,30 @@ module Textus
         store.manifest.permission_for(zone.to_s).allows_read?(role)
       end
 
+      def bus
+        @store.bus
+      end
+
+      def manifest   = @store.manifest
+      def schemas    = @store.schemas
+      def file_store = @store.file_store
+      def audit_log  = @store.audit_log
+
+      def authorize_write!(mentry)
+        return if can_write?(mentry.zone)
+
+        writers = @store.manifest.zone_writers(mentry.zone)
+        raise WriteForbidden.new(mentry.key, mentry.zone, writers: writers)
+      end
+
+      def authorize_read!(mentry)
+        return if can_read?(mentry.zone)
+
+        readers = @store.manifest.zone_readers[mentry.zone]
+        readers = nil if readers == :all
+        raise ReadForbidden.new(mentry.key, mentry.zone, readers: readers)
+      end
+
       def with_role(new_role)
         self.class.new(
           store: @store,

data/lib/textus/application/reads/audit.rb

@@ -58,7 +58,7 @@ module Textus
         end
 
         def key_in_zone?(key, zone)
-          mentry, = @ctx.store.manifest.resolve(key)
+          mentry = @ctx.store.manifest.resolve(key).entry
           mentry && mentry.zone == zone
         rescue Textus::Error
           false

data/lib/textus/application/reads/blame.rb

@@ -23,7 +23,9 @@ module Textus
         private
 
         def resolve_path(key)
-          mentry, path, = @ctx.store.manifest.resolve(key)
+          res = @ctx.store.manifest.resolve(key)
+          mentry = res.entry
+          path = res.path
           # Nested entries resolve to a file under the entry path; leaf entries
           # already have a fully-resolved path. Either way `path` is what git
           # needs to know about.

data/lib/textus/application/reads/deps.rb

@@ -7,7 +7,7 @@ module Textus
         end
 
         def call(key)
-          @ctx.store.reader.deps(key)
+          Dependencies.deps_of(@ctx.manifest, key)
         end
       end
     end

data/lib/textus/application/reads/freshness.rb

@@ -15,7 +15,7 @@ module Textus
 
         def call(prefix: nil, zone: nil)
           rows = []
-          @ctx.store.manifest.entries.each do |mentry|
+          @ctx.manifest.entries.each do |mentry|
             next if prefix && !mentry.key.start_with?(prefix)
             next if zone && mentry.zone != zone
 
@@ -27,7 +27,7 @@ module Textus
         private
 
         def row_for(mentry)
-          set = @ctx.store.manifest.rules_for(mentry.key)
+          set = @ctx.manifest.rules_for(mentry.key)
           refresh = set.refresh
           envelope = safe_get(mentry.key)
           last = envelope&.meta&.dig("last_refreshed_at")
@@ -61,7 +61,16 @@ module Textus
         # Returns the raw envelope or nil. Nested entries (mentry.key is a
         # prefix, not a leaf) and missing files both resolve to nil.
         def safe_get(key)
-          @ctx.store.reader.read_raw_envelope(key)
+          res = @ctx.manifest.resolve(key)
+          return nil unless @ctx.file_store.exists?(res.path)
+
+          raw = @ctx.file_store.read(res.path)
+          parsed = Entry.for_format(res.entry.format).parse(raw, path: res.path)
+          Envelope.build(
+            key: key, mentry: res.entry, path: res.path,
+            meta: parsed["_meta"], body: parsed["body"],
+            etag: Etag.for_bytes(raw), content: parsed["content"]
+          )
         rescue Textus::Error
           nil
         end