textus 0.12.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e14d58006851be5feba9ffa7016f5860b0ea380cef09cbf324a897d24ae56ee8
-  data.tar.gz: f928e250b5c3bc6e072c1ffc1928e68fdf61d2965d1746c121657ad4bd07ac75
+  metadata.gz: 24eda2a2cfec1884eb3c675189493827b6c0f43d5765922dbee06b70fbdc9685
+  data.tar.gz: 84e3850666541900f4c3b99f71c59b73dd142c7001f80fa9e8233d38f984719e
 SHA512:
-  metadata.gz: 6eb5690e16fc78f71b42a5f4308d7698684b5aa9f43a92534f73edca5fc36494be65bfab6df2d8d0832f788e7fe7496638ad23f83ee6f69f5a9950b419237745
-  data.tar.gz: aa3b5903ff1fb44dcc5d1bb3f0676bffb9d8cce99c6e6237f2d947b3486e3d0cfce53271fcf282b927ea1b2e9b1164e721ed0800ddd5ffde1644f85dd660339a
+  metadata.gz: d68ad56bc7891aefda10e47234f1bbd1efbfd75b576f7981c3374641efbd306dc66947b382b74c70da24bc58122090c3e0789c33b1a8291aa1005b9e6c952e2e
+  data.tar.gz: fd1c1cefad648636b4fb5aeba100d81c66472f8e1b50d07ba2239607c19179842902abf0b76925786c66868049acfd507a9a76bd07e39026dd2aa0d261ebfdad

data/ARCHITECTURE.md

@@ -2,73 +2,93 @@
 
 ```
 ┌─ Interface ────────────────────────────────────────────────┐
-│  CLI verbs:  ctx = Composition.context(store, role:)       │
-│              Composition.<use_case>(ctx).call(...)         │
+│  CLI verbs:  ops = Operations.for(store, role:)            │
+│              ops.reads.<name>.call(...)                    │
+│              ops.writes.<name>.call(...)                   │
+│              ops.refresh.<name>.call(...)                  │
 └──────────────────────┬─────────────────────────────────────┘
                        │
 ┌─ Application ────────▼─────────────────────────────────────┐
 │  Context          (per-request: store, role, correlation,  │
-│                    clock, dry_run; can_read?/can_write?)   │
-│  Composition      (factory module)                         │
+│                    clock, dry_run; can_read?/can_write?;   │
+│                    Context.system(store) for infra path)   │
+│  Operations       (facade with .reads/.writes/.refresh)    │
 │                                                            │
-│  reads/get.rb              writes/put.rb                   │
-│  refresh/worker.rb         writes/delete.rb                │
-│  refresh/orchestrator.rb   writes/build.rb                 │
-│  refresh/all.rb            writes/accept.rb                │
-│                            writes/publish.rb               │
+│  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     │
+│  refresh/{worker,orchestrator,all}.rb                      │
 └──────────┬───────────────────────────────┬─────────────────┘
            │ uses domain                   │ uses ports
 ┌─ Domain ─▼─────────────────────────────────────────────────┐
-│  Permission             ← NEW: predicate, not Action       │
-│  Freshness::Policy      Freshness::Verdict                 │
-│  Freshness::Evaluator   Action  Outcome                    │
+│  Permission         (write/read predicate per zone)        │
+│  Freshness::{Policy,Verdict,Evaluator}                     │
+│  Action  Outcome                                           │
+│  Policy::Promotion (proposal accept gates)                 │
 └──────────────────────────────────────────┬─────────────────┘
                                            │ implements
 ┌─ Infrastructure ─────────────────────────▼─────────────────┐
-│  Store              (pure adapter — exposes ports only)    │
-│    Reader#read_envelope         Writer#write_envelope_…    │
-│    AuditLog, Staleness, Validator, Mover                   │
-│  Manifest           (incl. permission_for)                 │
-│  Hooks::Registry    EventBus     Clock                     │
-│  Refresh::Lock      Refresh::Detached                      │
-│  Infra::Publisher   (file copy + sentinel)                 │
+│  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                │
+│  Manifest           (Entry, Rules, Schema, permission_for) │
+│  Hooks::{Registry,Dispatcher,Loader,Dsl,Builtin}           │
+│  Infra::{Publisher,EventBus,Clock,Refresh::Lock,           │
+│          Refresh::Detached}                                │
+│  Entry::{Markdown,Json,Yaml,Text}  (format strategies)     │
 └────────────────────────────────────────────────────────────┘
 
    Dependency rule: arrows point DOWN. Domain has zero outbound
    imports. Application imports Domain + Infra (via ports).
 ```
 
-## Read path (`store.get`)
+## Read path (`ops.reads.get.call(key)`)
 
-1. CLI verb (or any caller) invokes `store.get(key, as:)`.
-2. `Store#get` constructs `Reads::Get(store, orchestrator)` and calls `.call(key, as:)`.
-3. `Reads::Get#call` reads the envelope from disk via `store.reader.read_raw_envelope(key)`.
-4. Resolves `Manifest::Entry#policy` — a `Domain::Freshness::Policy` value.
+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. `Orchestrator.execute(action, key, as)` interprets the Action:
+8. `Refresh::Orchestrator#execute(action, key:)` interprets the `Action`:
    - `Action::Return` → `Outcome::Skipped`
-   - `Action::RefreshSync` → run Worker inline → `Refreshed | Failed`
-   - `Action::RefreshTimed(budget_ms:)` → race Worker thread vs budget; on timeout, kill thread, fire `:refresh_detached`, fork+detach child, return `Outcome::Detached`
+   - `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 (`store.put`)
+## Write path (`ops.writes.put.call(key, ...)`)
 
-1. CLI verb calls `ctx = Composition.context(store, role:)` then `Composition.writes_put(ctx).call(key, ...)`.
-2. `Writes::Put#call` checks `ctx.can_write?(zone)` — raises `write_forbidden` if denied.
-3. Delegates pure I/O to `Store::Writer#write_envelope_to_disk(key, ...)`.
-4. On success, fires `:put` event via the injected `Infra::EventBus`, including `correlation_id` from the Context.
+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:`.
 
-The same pattern applies to `Writes::Delete`, `Writes::Build`, `Writes::Accept`, and `Writes::Publish`: each takes a `Context`, checks permissions at the use-case layer, then delegates raw I/O to the corresponding `Store::Writer` or `Infra::Publisher` primitive.
+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.
 
-## Refresh path (`textus refresh KEY`)
+## Refresh path (`ops.refresh.worker.run(key)`)
 
-1. CLI `Verb::Refresh` calls `Textus::Refresh.call(store, key, as:)`.
-2. That shim instantiates `Application::Refresh::Worker` and runs it.
-3. `Worker#run`:
-   - Resolves the manifest entry, looks up the `:intake` handler.
-   - Publishes `:refresh_began` via the injected `Infra::EventBus`.
+1. CLI `Verb::Refresh` builds `ops = Operations.for(store, role: "runner")` then calls `ops.refresh.worker.run(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 `store.put`, publishes `:refreshed` (unless the etag is unchanged).
+   - 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: [...] }`.
+
+## Infrastructure-side hook dispatch
+
+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).

data/CHANGELOG.md

@@ -9,6 +9,220 @@ 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.14.0 — 2026-05-26
+
+### Breaking (Ruby API only — CLI JSON output unchanged)
+
+- `Operations.reads.get.call(...)` and every other use case that returned
+  an envelope Hash now returns `Textus::Envelope` (a `Data.define`
+  instance). Call `envelope.to_h_for_wire` to recover the previous Hash
+  shape for JSON serialization. The Hash shape itself is byte-identical.
+- `Operations.writes.build.call(...)` return shape no longer includes
+  `published_leaves`. Call `Operations.writes.publish.call(...)`
+  separately for that. The CLI verb `textus build` runs both
+  automatically, so CLI users see no change.
+
+### Added
+
+- `Textus::Application::Writes::Publish` — new use case that copies
+  nested-leaf files to their `publish_each` targets. Fires
+  `:file_published`.
+- `Operations.writes.publish` — factory exposing the new use case.
+- `Textus::Envelope` (now a class, was a module) — typed accessors for
+  `protocol`, `key`, `zone`, `owner`, `path`, `format`, `uid`, `etag`,
+  `schema_ref`, `meta`, `body`, `content`, `freshness`. Methods:
+  `to_h_for_wire`, `stale?`, `refreshing?`.
+
+### Internal
+
+- `Application::Writes::Build` trimmed from 116 LOC to ~50 LOC; now
+  only materializes generator-zone entries.
+- All ~17 internal `env["..."]` call sites migrated to typed access.
+- `Envelope.build` no longer carries `# rubocop:disable
+  Metrics/ParameterLists` (the `Data.define` member list serves the
+  same role more clearly).
+
+### Reference
+
+- See [ADR 0007](docs/architecture/decisions/0007-envelope-data-class.md).
+
+## 0.13.1 — 2026-05-26
+
+### Internal
+
+- `Manifest::Entry` (260 LOC, 11 responsibilities) decomposed into:
+  - `Manifest::Entry::Parser` — raw hash → Entry value object.
+  - `Manifest::Entry::Validators::*` — one file per validation rule
+    (events, publish_each, inject_intro, index_filename, format_matrix).
+  - `Manifest::Entry` (~50 LOC) — value object with attr readers,
+    zone-kind predicates, and `publish_target_for`.
+- Each validation rule is now independently testable. Adding a new
+  rule is one new file under `lib/textus/manifest/entry/validators/`
+  plus one line in `Validators::REGISTERED`.
+- Pattern matches the existing `doctor/check/*` (~15 files, same
+  shape).
+
+### Compatibility
+
+- `Manifest::Entry` keeps all public attribute readers, predicates,
+  and `publish_target_for`. External callers consuming `Entry`
+  instances see no change. Embedders who subclassed `Entry` may
+  need adjustment.
+
+## 0.13.0 — 2026-05-26
+
+### Added
+
+- `Textus::Entry::Base` grows 7 abstract class methods that concrete
+  strategies must implement: `nested_glob`, `inject_uid`,
+  `enforce_name_match!`, `rewrite_name`, `serialize_for_put`,
+  `validate_path_extension`.
+- `Textus::Entry.infer_from_extension(ext)` — registry method
+  replacing the deleted `Manifest::EXT_TO_FORMAT` constant.
+
+### Changed
+
+- Format-specific branches in `Manifest#nested_glob`,
+  `Manifest::Entry#{validate_format_matrix!,resolve_format!,
+  validate_index_filename!}`, `Store::Writer#{ensure_uid,
+  enforce_name_match!,serialize_for_put}`, and
+  `Application::Writes::Mv#rewrite_name_for_mv!` all collapse to
+  single-line delegations to `Entry.for_format(fmt).<method>(...)`.
+- The 3 rubocop `Metrics/*` disable comments in
+  `Manifest::Entry#validate_format_matrix!` are removed; the method
+  is now 3 lines.
+
+### Removed
+
+- `Textus::Manifest::EXT_TO_FORMAT` constant. Use
+  `Textus::Entry.infer_from_extension(ext)` instead.
+
+### Reference
+
+- See [ADR 0006](docs/architecture/decisions/0006-format-strategy-extraction.md).
+
+## 0.12.6 — 2026-05-26
+
+### Examples
+
+- New `examples/project/` — demonstrates textus as the context store
+  for your own project (identity + runbooks + ADR proposal flow,
+  projecting `CLAUDE.md` and `AGENTS.md` at the repo root). Staged as
+  a fictional Rails service (`ledger`) so the entries read like a real
+  codebase, and the pre-staged ADR proposal is `accept`-runnable
+  end-to-end (carries a valid `frontmatter:` payload for its target).
+- Refined `examples/claude-plugin/` — reduced to one entry of each kind
+  (one agent, one skill, one command, one identity entry, one output,
+  one intake recipe). Removed `bin/`, `Rakefile`, `lefthook.yml`, the
+  duplicate `github_folder.rb` recipe, and the per-recipe README.
+- Fixed `examples/claude-plugin/recipes/skill_fanout.rb` — the recipe
+  routed inner writes through `store.list/put/delete`, which were
+  removed in v0.12.2. Now uses `Operations.writes.{put,delete}` against
+  the `Application::Context` that hooks actually receive.
+- Updated `spec/examples/skill_fanout_hook_spec.rb` to test the recipe
+  against a Context-like duck type, matching the runtime contract.
+
+## 0.12.5 — 2026-05-26
+
+### Documentation
+
+- Rewrote `docs/events.md` to use the textus/3 event names from
+  `Hooks::Registry::EVENTS` (`:entry_put`, `:entry_deleted`,
+  `:build_completed`, `:entry_renamed`, `:proposal_accepted`,
+  `:proposal_rejected`, `:file_published`, `:store_loaded`,
+  `:entry_refreshed`, `:refresh_started`, `:refresh_failed`,
+  `:refresh_backgrounded`). All hook examples now register against
+  events that actually exist.
+- Rewrote `docs/zones.md` to use textus/3 vocabulary (`intake` not
+  `inbox`, `write_policy:` not `writable_by:`, `rules:` not
+  `policies:`, `runner` role not `script`). Manifest fixtures bump
+  to `version: textus/3`.
+- Rewrote `ARCHITECTURE.md` to match the v0.12.4 layering:
+  `Operations` facade replaces `Composition`, `Application::Reads/Writes`
+  use cases replace direct `Store#get/#put` calls, `Store` is pure
+  infrastructure.
+- `SPEC.md` Composition → Operations sweep; removed references to
+  deleted Store delegators.
+- `docs/recipe-github-skill-bundle.md` updated to use the
+  `Operations.writes.{put,delete}` inner-write surface.
+
+## [0.12.4] — 2026-05-26
+
+### Breaking
+
+- Removed `Textus::Store#list`, `#where`, `#deps`, `#rdeps`, `#published`,
+  `#stale`, `#validate_all`, `#uid`, `#schema_envelope`, and `#fire_event`.
+  Use `Textus::Operations.for(store).reads.<name>.call(...)` instead.
+- Removed `Textus::Store::Writer#delete`, `#accept`, `#reject`. Use
+  `Textus::Operations.for(store, role:).writes.<verb>.call(...)`.
+- Removed `Textus::Store::Mover`. The mv use case lives entirely in
+  `Textus::Application::Writes::Mv` now.
+
+### Added
+
+- `Textus::Application::Reads::{List,Where,Uid,SchemaEnvelope,Deps,Rdeps,Published,Stale,ValidateAll}`.
+- `Textus::Application::Writes::Reject`.
+- `Textus::Application::Context.system(store)` for infrastructure-side
+  hook dispatch.
+
+### Internal
+
+- Internal call sites (`Projection`, `Schema::Tools`, `Application::Refresh::All`,
+  `Doctor::Check::SchemaViolations`) now route reads through `Operations`.
+
+See [ADR 0005](docs/architecture/decisions/0005-store-facade-final-removal.md).
+
+## [0.12.3] — 2026-05-26
+
+### Added
+- `textus intro` output now includes an `agent_protocol` block: envelope shape, role-resolution rules, and four canonical recipes (`read`, `write`, `propose`, `refresh`). One `textus intro` call is sufficient orientation for a fresh AI agent to operate the store without consulting `SPEC.md`.
+
+### Compatibility
+- Fully additive. All pre-0.12.3 fields on `Textus::Intro.run` retain their existing keys, types, and shapes. The wire `"protocol"` field continues to hold the string `"textus/3"`.
+
+### Examples
+- `examples/claude-plugin/.textus/templates/claude-root.mustache` now projects the new `agent_protocol` recipes into the rendered `CLAUDE.md` via the existing `inject_intro:` mechanism. A plugin's CLAUDE.md auto-projects the four recipes alongside zone authority — agents reading CLAUDE.md get full orientation without a separate `textus intro` call. This is the canonical pattern for plugin authors who want recipes inline.
+- `examples/claude-plugin/` trimmed to one of each surface (one agent, one skill, one command, one identity entry, one JSON output). Removed: the duplicate `fact-checker` variants, the `marketplace.json` projection (the JSON-output lesson is already shown by `plugin.json`), the degenerate `local_file` intake demo (pulled a file from the same store), and unused demo hooks (`rank_by_recency`, `build-stamp`). File count drops from 51 to 33; manifest from 142 to 99 lines.
+
+## [0.12.2] — 2026-05-26
+
+### Breaking changes
+
+- **Removed `Textus::Composition`.** All call sites now go through
+  `Textus::Operations.for(store, role:)`. The new facade groups use-cases
+  by kind: `ops.writes.put`, `ops.reads.get`, `ops.refresh.worker`, etc.
+  No alias, no deprecation warning — internal callers update on upgrade.
+- **Removed `Store#put / #get / #delete / #accept / #reject / #mv`.** These
+  were thin shims over `Composition`. Use `Operations` directly.
+- **Removed `Writer#put`** (the explicit "Backward-compat shim").
+
+### Internal
+
+- Added `Application::Writes::Mv` use-case wrapping `Store::Mover`.
+- Internal Application callers (Accept, Build, Refresh::Worker, Refresh::All,
+  Reads::Blame) no longer re-enter via the top-level facade.
+- Audited `spec/` and removed redundant examples (~-48 LOC; most redundancy
+  was already absorbed by call-site migration in earlier tasks).
+
+See [ADR 0004](docs/architecture/decisions/0004-operations-rename-and-store-facade-removal.md).
+
+### Migration
+
+There is no migration path for `Composition` and the Store facade methods —
+they were internal. External consumers (hooks, custom verbs, gem embedders)
+that referenced these symbols must update:
+
+```ruby
+# Before
+ctx = Textus::Composition.context(store, role: "agent")
+Textus::Composition.writes_put(ctx).call(key, body: "...")
+# or:
+store.put(key, body: "...", as: "agent")
+
+# After
+Textus::Operations.for(store, role: "agent").writes.put.call(key, body: "...")
+```
+
 ## 0.12.1 — textus/2 hint fix (2026-05-26)
 
 ### Fixed

data/README.md

@@ -13,20 +13,12 @@ Reference implementation in Ruby. Wire format `textus/3`. SPEC: [`SPEC.md`](SPEC
 
 Two versions, deliberately independent:
 
-- **Protocol wire string:** `textus/3`. Stable; breaking changes require `textus/4`.
-- **Gem version:** semver, currently `0.11.0`. The gem version is decoupled from the protocol string — internal refactors bump the gem; only wire-format changes bump the protocol.
+- **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.
 
 Envelope payloads carry the `protocol` field. The gem version is irrelevant to the wire format.
 
-### Upgrading from textus/2
-
-textus 0.12.0 does not include a built-in migrator. If you are upgrading from
-a textus/2 store (gem versions ≤ 0.10.x), first install textus 0.11.x and run:
-
-    textus migrate --to=textus/3
-
-Then upgrade to 0.12.0. Pre-0.11.0 audit-log rows with `role: ai|script|build`
-are tolerated verbatim by the reader — no rewrite step required.
+See [CHANGELOG.md](CHANGELOG.md) for per-release notes.
 
 ## Install
 
@@ -87,6 +79,8 @@ For the full shape — Claude plugin with agents, skills, commands, pending walk
 
 - **Per-entry formats.** `format: markdown | json | yaml | text` on a manifest entry. `cat .textus/zones/output/marketplace.json | jq .` works without going through textus — the in-store file *is* the consumer-shaped artifact. Structured outputs carry `_meta` at the top level (`generated_at`, `from`, `template`, `transform`).
 - **Per-leaf publishing.** Nested entries declare `publish_each: "skills/{basename}/SKILL.md"`. Every leaf byte-copies to its consumer location on `textus build`. No more hand-mirrored `agents/` / `skills/` / `commands/` directories.
+- **Split build/publish (v0.14.0).** `Application::Writes::Build` materializes generator-zone entries; `Application::Writes::Publish` copies nested leaves to `publish_each` targets. The `textus build` CLI verb calls both and merges results, so wire output is unchanged.
+- **Typed envelopes (v0.14.0).** `Textus::Envelope` is a `Data.define` value object with typed accessors (`.meta`, `.body`, `.etag`, `.uid`, `.freshness`, …). Ruby API callers get IDE help and `NoMethodError` on typos. The CLI JSON wire format is preserved byte-for-byte via `envelope.to_h_for_wire`.
 - **Stable identity (`uid:`).** 16-char hex, auto-minted on first `put`, preserved across writes and moves. `textus key mv old.key new.key` renames in place — uid survives, audit row records `from_key`, `to_key`, `uid`. Reorganising a tree no longer breaks references.
 - **Strict key grammar.** `/^[a-z0-9][a-z0-9-]*$/`, max 8 segments × 64 chars. `textus key normalize --dry-run|--write` rewrites existing stores with illegal segments deterministically.
 - **`textus intro`.** One-shot store orientation: zones with writers + purposes, entry families with schemas and publish targets, loaded hooks, write flows per role, the full CLI verb table. The boot signal for any agent — one tool call and it knows your store.
@@ -162,7 +156,7 @@ Schemas (`.textus/schemas/<name>.yaml`) declare field shapes, per-field `maintai
 bundle exec rspec
 ```
 
-~490 examples; includes conformance fixtures A–I from SPEC §12.
+~637 examples; includes conformance fixtures A–I from SPEC §12.
 
 ## Code quality
 

data/SPEC.md

@@ -828,7 +828,10 @@ Both read and write paths flow through the application layer:
 - **Reads** flow through `Application::Reads::Get`, which takes a `Context` and dispatches refresh via `Application::Refresh::Orchestrator`.
 - **Writes** flow through `Application::Writes::{Put,Delete,Build,Accept,Publish}`, each taking a `Context`. Permission checks happen at the use-case layer (via `Context#can_write?`); I/O happens at `Store::Writer#write_envelope_to_disk` (pure).
 - `Application::Context` is the universal request object: it carries `store`, `role`, `correlation_id`, `clock`, and `dry_run`. Use cases never thread these as separate kwargs.
-- `Textus::Composition` is the factory module CLI verbs (and future MCP server / HTTP shim) use to construct Contexts and use cases.
+- `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}/`.
 
 See `ARCHITECTURE.md` for an ASCII diagram and the full read-path walkthrough.
 

data/docs/conventions.md

@@ -20,7 +20,7 @@ Recommended top-level layout — the spec allows alternatives, but this is what
   zones/
     identity/     # identity, voice, slow-changing facts — humans only
     working/      # agent-writable working memory
-    inbox/        # script-fed external inputs
+    intake/       # runner-fed external inputs
     review/       # AI proposals awaiting accept
     output/       # generated by build runners — never edit by hand
 ```
@@ -82,25 +82,25 @@ Full contract for both shapes is in [`../SPEC.md` §5.2 and §5.2.1](../SPEC.md)
 
 ## Intake and freshness
 
-External inputs land via `:intake` hooks, not shell commands. Each inbox entry names a registered handler; refresh is on demand:
+External inputs land via `:resolve_intake` hooks, not shell commands. Each intake entry names a registered handler; refresh is on demand:
 
 ```sh
-textus refresh inbox.notion.roadmap --as=script
-textus refresh-stale --zone=inbox --as=script   # everything past its TTL
+textus refresh intake.notion.roadmap --as=runner
+textus refresh-stale --zone=intake --as=runner   # everything past its TTL
 ```
 
-Freshness budgets live in the top-level `policies:` block, matched by glob:
+Freshness budgets live in the top-level `rules:` block, matched by glob:
 
 ```yaml
-policies:
-  - match: inbox.notion.**
+rules:
+  - match: intake.notion.**
     refresh: { ttl: 6h, on_stale: warn }   # warn | sync | timed_sync
 ```
 
 A typical scheduled-refresh integration shells the `refresh-stale` sweep itself:
 
 ```sh
-textus refresh-stale --zone=inbox --as=script   # in cron / CI
+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.

data/lib/textus/application/context.rb

@@ -5,6 +5,10 @@ module Textus
     class Context
       attr_reader :store, :role, :correlation_id
 
+      def self.system(store)
+        new(store: store, role: "human")
+      end
+
       def initialize(store:, role:, correlation_id: nil, clock: Time, dry_run: false)
         @store          = store
         @role           = role.to_s

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

@@ -13,7 +13,7 @@ module Textus
         end
 
         def call(key:, limit: nil)
-          audit_rows = Textus::Composition.audit(@ctx).call(key: key, limit: limit)
+          audit_rows = Textus::Application::Reads::Audit.new(ctx: @ctx).call(key: key, limit: limit)
           path = resolve_path(key)
           return audit_rows.map { |r| r.merge("git" => nil) } unless git_tracked?(path)
 

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

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class Deps
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call(key)
+          @ctx.store.reader.deps(key)
+        end
+      end
+    end
+  end
+end

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

@@ -30,12 +30,12 @@ module Textus
           set = @ctx.store.manifest.rules_for(mentry.key)
           refresh = set.refresh
           envelope = safe_get(mentry.key)
-          last = envelope&.dig("_meta", "last_refreshed_at")
+          last = envelope&.meta&.dig("last_refreshed_at")
 
           return base_row(mentry, last).merge(status: :no_policy) if refresh.nil?
 
           fp = refresh.to_freshness_policy
-          verdict = @evaluator.call(fp, envelope || {}, now: @ctx.now)
+          verdict = @evaluator.call(fp, envelope, now: @ctx.now)
           status = if verdict.fresh? then :fresh
                    elsif last.nil?   then :never_refreshed
                    else                   :stale

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

@@ -40,21 +40,18 @@ module Textus
         private
 
         def annotate(envelope, verdict, refreshing:, refresh_error: nil)
-          envelope = envelope.dup
-          envelope["stale"]         = verdict.stale?
-          envelope["stale_reason"]  = verdict.reason
-          envelope["refreshing"]    = refreshing
-          envelope["refresh_error"] = refresh_error if refresh_error
-          envelope
+          fresh = {
+            "stale" => verdict.stale?,
+            "stale_reason" => verdict.reason,
+            "refreshing" => refreshing,
+          }
+          fresh["refresh_error"] = refresh_error if refresh_error
+          envelope.with(freshness: fresh)
         end
 
         # No refresh policy applies to this key — treat as fresh, skip evaluation/orchestration.
         def annotate_fresh(envelope)
-          envelope = envelope.dup
-          envelope["stale"]        = false
-          envelope["stale_reason"] = nil
-          envelope["refreshing"]   = false
-          envelope
+          envelope.with(freshness: { "stale" => false, "stale_reason" => nil, "refreshing" => false })
         end
       end
     end

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

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class List
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call(prefix: nil, zone: nil)
+          @ctx.store.reader.list(prefix: prefix, zone: zone)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class Published
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call
+          @ctx.store.reader.published
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class Rdeps
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call(key)
+          @ctx.store.reader.rdeps(key)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class SchemaEnvelope
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call(key)
+          @ctx.store.reader.schema_envelope(key)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Textus
+  module Application
+    module Reads
+      class Stale
+        def initialize(ctx:)
+          @ctx = ctx
+        end
+
+        def call(prefix: nil, zone: nil)
+          @ctx.store.reader.stale(prefix: prefix, zone: zone)
+        end
+      end
+    end
+  end
+end