textus 0.14.4 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1e2a12b234bfc677ce44ec7b49b3b04b4ac69abbc15f13496911c82d89549c8
-  data.tar.gz: 6b83336a05cb3cee509d3e0b90ce2048ed57fdeb5fbc603f22303e10c2d5c27c
+  metadata.gz: 3d7915be053bc7e858c821e0e8d8e8cebd3de6acde21dcd8f687ff3fa12db3d1
+  data.tar.gz: 792cd40df3e8046c954be84dc32d4e53a2b47cdfd9a21029c74953d39e182a87
 SHA512:
-  metadata.gz: f126d898385e0d0236a1818a741923f8ee9f88f1f13cab8ef37bbb810d14145904186084f72d0fbc5a4d6bfdf53b5e7e68699f56db4f9aa02d22772019a11316
-  data.tar.gz: 054ea4fea78cf26d570319d49f2a0ffbd4023e6355b56b8830650e7d59b1b57ae2de7b158ef0611b465369136e11b292ba9f968113cd425ecd1cfed1bf96633d
+  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,384 @@ 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
+
+- `Application::Reads::Get#call` is now a **pure read**: it returns the
+  on-disk envelope annotated with a freshness verdict, and never
+  triggers refresh. `Reads::Get.new` no longer accepts `orchestrator:`.
+  Callers that relied on refresh-on-read should switch to
+  `Application::Reads::GetOrRefresh` (new), accessible via
+  `ops.reads.get_or_refresh`. The CLI verb `textus get` is migrated
+  internally; users of `textus get` see no behavior change.
+- `Application::Context#bypass_freshness?` and the `bypass_freshness:`
+  kwarg on `Context.new` / `Operations.for` are **removed**. They
+  shipped in 0.14.4 as a workaround; with `Reads::Get` now pure by
+  default, the flag is dead code. Callers passing `bypass_freshness:`
+  will see `ArgumentError`.
+- `Projection.new` signature is **breaking**: now
+  `Projection.new(reader:, spec:, lister:, transform_resolver:, transform_context:)`.
+  `Projection` no longer constructs its own `Operations` chain. Callers
+  inject collaborators. `Builder::Pipeline` is migrated internally.
+- Intake handlers now receive `args: { trigger_key:, leaf_segments: }`
+  instead of `args: {}`. Handlers that destructure `args` should
+  expect the new keys. Handlers that pass `args` through unchanged
+  are unaffected.
+
+### Fixed
+
+- **Bug 1 / single-flight.** `Refresh::Orchestrator#run_timed` now
+  probes the per-leaf lock before forking the detached refresh
+  worker. If the lock is held (by a sibling process or earlier fork),
+  the orchestrator returns `Outcome::Detached` without spawning a
+  redundant worker. Prevents wasted forks when the same key is read
+  concurrently across processes.
+- **Bug 2 / leaf-aware intake.** `Refresh::Worker` now keeps the
+  `remaining` segments from `Manifest#resolve(key)` and passes them
+  to the intake handler as `args: { trigger_key:, leaf_segments: }`.
+  Handlers can scope to one leaf instead of re-processing the full
+  parent `intake_config` for every leaf refresh.
+- **`textus refresh stale` now exits 0 on success.** Previously the
+  verb fell off the end returning `nil`, which propagated up through
+  `CLI.run` to `exe/textus:4`'s `exit nil` and raised `TypeError`,
+  exit-coding 1 on every successful refresh. Fixed by returning an
+  explicit Integer from the verb. The verb return-value contract is
+  now codified: every verb's `#call` returns Integer (or `nil` →
+  treated as 0); `CLI.run` coerces. (#61)
+
+### Added
+
+- `Application::Reads::GetOrRefresh` — explicit composition of pure
+  `Reads::Get` with the refresh orchestrator. Use for interactive
+  reads that want freshest-obtainable envelopes.
+- `ops.reads.get_or_refresh` accessor.
+
+### Migration
+
+If your code (or hook / handler / extension) called:
+
+| Old | New |
+|---|---|
+| `ops.reads.get.call(key)` to get the freshest envelope | `ops.reads.get_or_refresh.call(key)` |
+| `ops.reads.get.call(key)` for pure read | unchanged; now also pure semantics |
+| `Operations.for(store, bypass_freshness: true)` | `Operations.for(store)` |
+| `Projection.new(store, spec)` | `Projection.new(reader:, spec:, lister:, transform_resolver:, transform_context:)` — see `builder/pipeline.rb` for canonical wiring |
+| Handler signature `lambda { \|store:, config:, args:\| ... }` with `args == {}` | unchanged — `args` is now populated with `:trigger_key` and `:leaf_segments`; handlers that ignore them keep working |
+
 ## 0.14.4 — 2026-05-26
 
 ### Fixed

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

@@ -105,6 +105,17 @@ textus refresh-stale --zone=intake --as=runner   # in cron / CI
 
 See [`./zones.md` §6](zones.md) for the full intake contract and [`./events.md`](events.md) for writing custom handlers.
 
+### Read vs. refresh
+
+There are two read operations, and the difference matters in custom code:
+
+| Operation | Triggers refresh? | Use for |
+|-----------|-------------------|---------|
+| `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.
+
 ## Body content
 
 - **Bodies are Markdown.** Headings, lists, code fences — whatever a human or agent finds useful.

data/lib/textus/application/context.rb

@@ -9,13 +9,12 @@ module Textus
         new(store: store, role: "human")
       end
 
-      def initialize(store:, role:, correlation_id: nil, clock: Time, dry_run: false, bypass_freshness: false)
+      def initialize(store:, role:, correlation_id: nil, clock: Time, dry_run: false)
         @store             = store
         @role              = role.to_s
         @correlation_id    = correlation_id || SecureRandom.uuid
         @clock             = clock
         @dry_run           = dry_run
-        @bypass_freshness  = bypass_freshness
         @now               = nil
       end
 
@@ -27,10 +26,6 @@ module Textus
         @dry_run
       end
 
-      def bypass_freshness?
-        @bypass_freshness
-      end
-
       def can_write?(zone)
         store.manifest.permission_for(zone.to_s).allows_write?(role)
       end
@@ -39,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,
@@ -46,7 +65,6 @@ module Textus
           correlation_id: @correlation_id,
           clock: @clock,
           dry_run: @dry_run,
-          bypass_freshness: @bypass_freshness,
         )
       end
     end

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.