textus 0.15.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54b9e7266b017d02abba0f6daeba977c580c07f1bdab798ebc7a9b943be555cd
-  data.tar.gz: 47ebf2a56523dbf33058fe95c45163899a6f7b91500a2f749ce3d731e60ab502
+  metadata.gz: 613e04300389a5f5bf058f4e75c15b5ff19f813fb7ef6102ba38ce53ecd43043
+  data.tar.gz: 97d121b40ac753af1e04893429db1abfe4044f791fff5ea02de33910a4cfa00c
 SHA512:
-  metadata.gz: 76abb1c22c3f519574dfd310a7ff2162b023bbbc8667b2e4dc2c32edbb94d432bf507620116dbcbc1f7ce3328964515ee8eded62abe1c833249b3b2bb1bd9fce
-  data.tar.gz: a405b5d81159c8dd0638e9ca6f4fca419358792c7a3a29f64cb0b19386553f37aa091f913c65ad078a039205ad6ac0368af681eba455fcb4c1787bcfb213ac05
+  metadata.gz: 13d11e92b35b952fc9974293544ab49d50dc6055f7ee80771b33a82f511ba534f6cf3fa8c26a84e886778f6b5ee662a3a540d36c7072c23f2b366540a365e066
+  data.tar.gz: 7cbf43d42e37271b73122d5db10a463a1936c39696cc6a5e7eee56646ccdb1c503a645e63b3b40e09bfc911ae531e2258b02d4e715458bcd54a193d9e7ca5b0d

data/ARCHITECTURE.md

@@ -3,92 +3,87 @@
 ```
 ┌─ 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/…)  │
+│                                                            │
+│  Or, for embedders bringing their own ports:               │
+│              Operations.new(ctx:, manifest:, file_store:,  │
+│                             schemas:, audit_log:, bus:,    │
+│                             registry:, root:, store:)      │
 └──────────────────────┬─────────────────────────────────────┘
                        │
 ┌─ Application ────────▼─────────────────────────────────────┐
-│  Context          (per-request: store, role, correlation,  │
-│                    clock, dry_run; can_read?/can_write?;   │
-│                    Context.system(store) for infra path)   │
-│  Operations       (facade with .reads/.writes/.refresh)    │
+│  Context          (slim Data: role, correlation_id, now,   │
+│                    dry_run — request state only)           │
+│  Operations       (flat facade; inline use-case factories) │
 │                                                            │
 │  reads/{get,list,where,uid,schema_envelope,deps,rdeps,     │
 │         published,stale,validate_all,freshness,audit,      │
-│         blame,policy_explain}.rb                           │
-│  writes/{put,delete,mv,accept,reject,build,publish}.rb     │
+│         blame,policy_explain,get_or_refresh}.rb            │
+│  writes/{put,delete,mv,accept,reject,build,publish,        │
+│          envelope_io}.rb                                   │
 │  refresh/{worker,orchestrator,all}.rb                      │
+│  policy/{promotion,predicates/{schema_valid,human_accept}} │
 └──────────┬───────────────────────────────┬─────────────────┘
            │ uses domain                   │ uses ports
 ┌─ Domain ─▼─────────────────────────────────────────────────┐
+│  Authorizer         (manifest + role → allow / deny)       │
 │  Permission         (write/read predicate per zone)        │
 │  Freshness::{Policy,Verdict,Evaluator}                     │
 │  Action  Outcome                                           │
-│  Policy::Promotion (proposal accept gates)                 │
+│  Policy::{Promote,Refresh,Matcher,HandlerAllowlist}        │
 └──────────────────────────────────────────┬─────────────────┘
                                            │ implements
 ┌─ Infrastructure ─────────────────────────▼─────────────────┐
-│  Store              (pure adapter — filesystem + hooks)    │
-│    Reader#{get,list,where,uid,deps,rdeps,published,        │
-│            stale,validate_all,read_raw_envelope,           │
-│            schema_envelope}                                │
-│    Writer#{write_envelope_to_disk,delete_envelope_from_    │
-│            disk,existing_uid_for,ensure_uid,               │
-│            enforce_name_match!,serialize_for_put}          │
-│    AuditLog, Staleness, Validator, Sentinel                │
+│  Store              (composition root — wires ports)       │
+│  Storage::FileStore (bytes-only port: read/write/delete/   │
+│                      exists?/etag)                         │
 │  Manifest           (Entry, Rules, Schema, permission_for) │
-│  Hooks::{Registry,Dispatcher,Loader,Dsl,Builtin}           │
+│  Schemas            (eager-load cache)                     │
+│  AuditLog                                                  │
+│  Hooks::{Registry,Dispatcher,Loader,FireReport}            │
 │  Infra::{Publisher,EventBus,Clock,Refresh::Lock,           │
-│          Refresh::Detached}                                │
+│          Refresh::Detached,BuildLock,AuditSubscriber}      │
 │  Entry::{Markdown,Json,Yaml,Text}  (format strategies)     │
 └────────────────────────────────────────────────────────────┘
 
    Dependency rule: arrows point DOWN. Domain has zero outbound
    imports. Application imports Domain + Infra (via ports).
+   Use cases declare their real ports in their constructor.
 ```
 
-## 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.get(key)`.
+2. `Operations#get` constructs `Application::Reads::Get.new(ctx:, manifest:, file_store:)` and calls it.
+3. `Reads::Get#call(key)` resolves the path through `@manifest`, reads bytes via `@file_store`, parses the envelope.
+4. Looks up the refresh policy via `@manifest.rules_for(key)`. If absent, returns the envelope annotated fresh.
+5. Otherwise `Domain::Freshness::Evaluator.call(policy, envelope, now:)` returns a `Verdict`; the envelope is annotated with `stale`, `reason`, `refreshing: false`.
+
+`ops.get_or_refresh(key)` composes `Reads::Get` with `Refresh::Orchestrator` to optionally refresh on stale — same as 0.18.x.
 
-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.
-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`.
-6. If fresh → annotate envelope (`stale: false`, `refreshing: false`) and return.
-7. Otherwise `policy.decide(verdict) → Action` (data, not behavior).
-8. `Refresh::Orchestrator#execute(action, key:)` interprets the `Action`:
-   - `Action::Return` → `Outcome::Skipped`
-   - `Action::RefreshSync` → run `Refresh::Worker` inline → `Refreshed | Failed`
-   - `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.put(key, ...)`)
 
-## Write path (`ops.writes.put.call(key, ...)`)
+1. CLI verb calls `ops = Operations.for(store, role:)` then `ops.put(key, meta:, body:, content:, if_etag:)`.
+2. `Writes::Put#call` validates the key, resolves the manifest entry, and calls `@authorizer.authorize_write!(mentry, role: @ctx.role)` — raises `WriteForbidden` if denied.
+3. Delegates persistence to `EnvelopeIO#write`, which serializes, schema-validates, etag-checks (raises `EtagMismatch` on conflict), writes via the `FileStore` port, and appends the audit row.
+4. Publishes `:entry_put` via `@bus` with `store: @store`, `key:`, `envelope:`, `role: @ctx.role`, `correlation_id: @ctx.correlation_id`.
 
-1. CLI verb calls `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.
-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(...)`
-   - Validates against schema if declared
-   - 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:`.
+`Writes::{Delete,Mv,Accept,Reject,Build,Publish}` follow the same shape: explicit ports, `Authorizer` for authz, `EnvelopeIO` for persistence (where applicable), event published with `store: real Store + role:` in payload.
 
-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.
+`Writes::Mv` delegates the file-move + audit to `EnvelopeIO#move`, then publishes `:entry_renamed` itself. UID injection (when the source lacks one) goes through `EnvelopeIO#write` directly — no `Put` bypass.
 
-## 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.
-   - Invokes the handler under a 30s `Timeout.timeout` budget.
-   - On any error: publishes `:refresh_failed`, then re-raises (or wraps in `UsageError`).
-   - On success: normalizes the return shape, persists via `Application::Writes::Put` with `suppress_events: true`, publishes `:entry_refreshed` (unless the etag is unchanged).
-3. The batch entry point is `Application::Refresh::All.call(ctx, prefix:, zone:)` which lists stale entries via `Application::Reads::Stale`, then runs `Worker#run` per entry, returning a summary envelope `{ refreshed: [...], failed: [...], skipped: [...] }`.
+   - Resolves the manifest entry, looks up the intake handler via `@registry.rpc_callable(:resolve_intake, mentry.intake_handler)`.
+   - Publishes `:refresh_started` with `role:` in the payload.
+   - Invokes the handler under a 30s thread-join deadline.
+   - On any error: publishes `:refresh_failed`, then re-raises.
+   - On success: applies `@authorizer.authorize_write!` and persists via `EnvelopeIO#write` directly (no `Put` round-trip); publishes `:entry_refreshed` unless etag is unchanged.
+3. `ops.refresh_all(prefix:, zone:)` lists stale entries via `Reads::Stale` and runs `Worker#run` per entry; returns `{ refreshed:, failed:, skipped: }`.
 
-## Infrastructure-side hook dispatch
+## Hook payload contract
 
-The hook bus needs an `Application::Context` even when fired from inside `Store#initialize` or other infrastructure-side code paths. `Application::Context.system(store)` returns a Context with `role: "human"` and a fresh correlation_id, designed for exactly this case — see `lib/textus/store.rb` (the `:store_loaded` publish), `lib/textus/doctor.rb` (the doctor-check view), and `lib/textus/projection.rb` (the transform_rows view).
+Hooks/intakes/transforms receive the actual `Textus::Store` (the composition root) as `store:`. Every write/refresh event payload carries `role:` directly so hook authors observe the actor without reaching through `store:`.

data/CHANGELOG.md

@@ -9,6 +9,492 @@ 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.20.0 — architecture redesign (2026-05-27)
+
+**BREAKING (pre-1.0):** Public top-level utility modules removed,
+`Manifest` routing methods extracted into a dedicated resolver,
+`Hooks::Dispatcher`/`Hooks::Registry` collapsed into a single bus, and
+pubsub hook payloads now ship `ctx:` (a `Textus::Hooks::Context`)
+instead of the raw store. External hook files written against the 0.19
+`register(event, name, ...)` API continue to work unchanged; pubsub
+hook bodies must update signatures from `|store:, ...|` to `|ctx:, ...|`
+and use `ctx.put`/`ctx.get`/`ctx.audit`/`ctx.publish_followup` in place
+of direct `store.*` access. RPC events (`transform_rows`, `resolve_intake`,
+`validate`) keep `store:`.
+
+### Added
+- `Textus::Hooks::Context` — narrow handle for user pubsub hooks. Exposes
+  `role`, `correlation_id`, `get`, `list`, `deps`, `freshness`, `put`,
+  `delete`, `audit`, and `publish_followup`. All writes route back through
+  `Operations` so authorization, audit, and validation cannot be bypassed.
+
+### Removed
+- `Textus::Dependencies` — use `Operations#deps`, `#rdeps`, `#published`.
+- `Textus::Refresh` — use `Operations#refresh`. The `normalize_action_result`
+  helper is now a private class method on `Application::Refresh::Worker`.
+- `Textus::Hooks::Dispatcher` and `Textus::Hooks::Registry` classes.
+
+### Changed
+- `Textus::Projection` moved to `Textus::Application::Projection`.
+- `Textus::MigrateKeys` moved to `Textus::Application::Tools::MigrateKeys`.
+- `Manifest#resolve`, `#enumerate`, and `#suggestions_for` removed from
+  the public `Manifest` API. Use `manifest.resolver.resolve(key)` etc.
+  via the new `Manifest::Resolver`. `Manifest` retains the data accessors
+  (`entries`, `zones`, `rules`, `permissions`, `validate_key!`).
+- `Store` constructs one `Hooks::Bus`; `Store#registry` removed (use
+  `Store#bus`). `Hooks::Builtin.register_all(bus)` and
+  `Hooks::Loader.new(bus:)` now take a Bus instead of a Registry.
+  `Operations.for` no longer accepts `registry:`. Use cases
+  (`Refresh::Worker`, `Refresh::All`) take `bus:`.
+- All pubsub events declare `ctx:` instead of `store:` in their kwargs
+  schema. Every `bus.publish` call site passes `ctx: hook_context`.
+  `Operations#hook_context` builds the per-`Operations` `Hooks::Context`.
+- Manifest entries gain a required `kind:` field
+  (`leaf | nested | derived | intake`). Run
+  `textus key normalize --upgrade-manifest` to add it to existing
+  manifests — the inference is deterministic and lossless.
+- Internal: `Manifest::Entry` is now an abstract namespace; concrete
+  classes are `Entry::Leaf`, `Entry::Nested`, `Entry::Derived`,
+  `Entry::Intake`. The fields `projection`, `generator`, `compute`,
+  `intake_handler`, `intake_config` are removed from the entry
+  interface; `Entry::Derived` carries a typed `source`
+  (`Projection` or `External`) and `Entry::Intake` carries `handler`
+  / `config`. Use-case code dispatches on entry type rather than
+  probing optional fields.
+- `Application::Writes::Build` removed. `Application::Writes::Publish` now
+  materializes derived entries (template + projection + external runner)
+  AND copies leaf/nested entries to their publish targets in a single pass.
+  `Operations#build` is gone; use `Operations#publish` — the `textus build`
+  CLI verb is unchanged and produces the same
+  `{protocol, built, published_leaves}` JSON shape.
+
+## 0.19.1 — drop textus/2 migration hint (2026-05-27)
+
+**BREAKING (pre-1.0):** Users on gem ≤0.10 (manifest protocol `textus/2`)
+no longer receive a stepping-stone hint pointing at 0.11.x. The manifest
+parser and `textus doctor` now emit the generic "unsupported version"
+error. Users on ≤0.10 should install 0.11.x first (still on RubyGems)
+to run the migrator, then upgrade to 0.19.1+.
+
+### Changed
+- `Textus::Manifest` no longer special-cases `textus/2`; `TEXTUS_2_HINT`
+  and `version_hint_for` removed.
+- `Doctor::Check::ProtocolVersion` hint/fix text simplified; no longer
+  links to the 0.11.x CHANGELOG anchor.
+
+### Removed
+- Two redundant manifest specs (the `Manifest.load` duplicate and the
+  `textus/2`-specific hint assertion) collapsed into one generic case.
+
+## 0.19.0 — 2026-05-27
+
+### Breaking
+
+- `Application::Context` is now a slim value object (`role`,
+  `correlation_id`, `now`, `dry_run`). Migration table:
+
+  | Was | Now |
+  |-----|-----|
+  | `Application::Context.new(store:, role:)` | `Operations.for(store, role:)` (common case) or `Application::Context.build(role:)` (pure call state) |
+  | `Application::Context.system(store)` | Pass `store` directly to hooks |
+  | `ctx.store` / `ctx.manifest` / `ctx.file_store` etc. | Construct use cases with the explicit port kwargs |
+  | `ctx.authorize_write!(mentry)` | `Domain::Authorizer.new(manifest:).authorize_write!(mentry, role:)` |
+  | `Put.new(ctx:).call(..., suppress_events: true)` | Use `EnvelopeIO#write` directly |
+  | `store.role` inside a hook | Read `role:` from the event payload |
+
+- `Operations.new(ctx:, manifest:, file_store:, schemas:, audit_log:, bus:, registry:, root:, store:)`
+  is the primary constructor. `Operations.for(store, role:)` remains
+  a convenience.
+
+- `Application::Writes::Put#call` no longer accepts `suppress_events:`.
+
+- `Domain::Policy::Predicates::*` moved to `Application::Policy::Predicates::*`.
+  `Domain::Policy::Promotion` moved to `Application::Policy::Promotion`.
+  `Promotion#evaluate` now takes `entry:, schemas:, manifest:, role:`
+  instead of `store:`.
+
+- Hooks/intakes/transforms receive the actual `Store` as `store:`
+  (previously a Context impersonating one). Event payloads
+  (`:entry_put`, `:entry_deleted`, `:entry_renamed`, `:proposal_accepted`,
+  `:proposal_rejected`, `:entry_refreshed`, `:refresh_started`,
+  `:refresh_failed`, `:refresh_backgrounded`, `:file_published`,
+  `:build_completed`) now carry `role:` directly so hooks can observe
+  the actor without reaching through the `store:` handle.
+
+- `Application::Refresh::All` is a class, not a module function. Callers
+  go through `Operations#refresh_all`.
+
+### Added
+
+- `Domain::Authorizer` — single source of truth for permission checks.
+- `Application::Policy::Promotion` and `Application::Policy::Predicates::*` —
+  the policy evaluator and predicates now live with the Application code
+  that loads envelope bytes off disk to evaluate them.
+- `Application::Writes::EnvelopeIO#move` — full move pipeline (replaces
+  the in-`Mv` file move + audit).
+- `Application::Writes::EnvelopeIO#read_envelope(key)` — internal
+  convenience for callers that need to inspect a pre-move envelope.
+
+### Internal
+
+- `Builder::Pipeline` no longer re-enters `Operations.for(store)`; it
+  takes reader/lister callables from the caller.
+- CLI verbs construct `Operations`, never `Context` directly.
+- `Operations` no longer memoizes per-use-case factories; only
+  `envelope_io`, `refresh_worker`, and `orchestrator` are shared.
+- Wire format `textus/3` unchanged. Audit-log NDJSON unchanged.
+
+### Known follow-ups
+
+- CLI verbs `hook run`, `put --fetch`, `hooks list`, and `rule list`
+  still reach into `store.manifest` / `store.registry` directly. A
+  future release adds `Operations` projections (e.g. `manifest_view`,
+  `hooks_view`, `run_intake`) so these verbs route through the
+  Operations boundary.
+- `Application::Writes::Delete#call` retains a `suppress_events:` kwarg
+  (used internally by `Reject`). A future release either lifts the
+  suppression into `EnvelopeIO`-direct usage (matching the `Mv` path)
+  or formalizes per-event suppression as part of the public hook API.
+
+## 0.18.1 — 2026-05-27
+
+### Fixed
+
+- `Hooks::Dispatcher` no longer uses `Timeout.timeout`, which can interrupt a
+  hook mid-syscall or mid-`ensure` and leave Ruby state corrupted. Each
+  subscriber now runs in a worker thread joined with a deadline; on overrun
+  the thread is killed and the hook is recorded as `timed_out` (distinct
+  from `errored`).
+
+### Added
+
+- `Hooks::FireReport` — value object returned from `bus.publish`. Lists
+  `fired`, `errored`, and `timed_out` subscriber names; exposes `#ok?` and
+  `#failures`. Backwards-compatible: callers that ignore the return value
+  (the entire current codebase) keep working.
+- `Hooks::Dispatcher#publish` accepts `strict: true`, which re-raises the
+  first failure after every subscriber has been attempted. Intended for
+  test setups that want loud hooks; default remains `false`.
+
+### Internal
+
+- No public API surface changes. CLI behavior, `Operations` methods, wire
+  format `textus/3`, and the audit-log NDJSON shape are unchanged. Stores
+  written by 0.18.0 round-trip through 0.18.1 byte-for-byte.
+
+## 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