textus 0.9.2 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca479a6c2f4282b97184aee5c65bc94c3607d18ae0a608756737c70ef53407b5
-  data.tar.gz: 2294eaa31b51276d48f1a7bc850464c3351a2c93b5d273100192fec4d89561d9
+  metadata.gz: da7bc5c1fbc90ea76df8adb279491b3a94b4b093f014281ca28c317366539cad
+  data.tar.gz: 92b35dab2a95f81d93e45a467652ee840ed06617a3df587d66a170884b99b81f
 SHA512:
-  metadata.gz: 6a6c5a434cf90e8e417faed9034e6ea653f1f94b3e373ea00b47045297e73b9e0f58d4619a84f497b45cb3078930da9b4327d7e179540369af7bf7297db2bd05
-  data.tar.gz: 4cbcd09254c93d94d1fd06c766ceefb5125990851422db6f6b3af4ad716b7754d71e432ebc88161d938aa5177ec26d6e1f43b7577daa80210e7a493e0266f6ea
+  metadata.gz: f84bf665d8aa002bfac744ada1e43b6993d9209f8997cafdfc441f74c758edb8ef28b5b3d45e70f8ccb58cc3c82c05a3238a40940142a35d25fd1807ed237324
+  data.tar.gz: cd2326ee626d90217aaf9f9e91b10441d6b397af3bf3bb8c54dde00e5bfa37eca56ca7011175f58168a1b0365a484de76e9ebac3022f035833974442a73e9f1e

data/ARCHITECTURE.md

@@ -0,0 +1,74 @@
+# Textus architecture
+
+```
+┌─ Interface ────────────────────────────────────────────────┐
+│  CLI verbs:  ctx = Composition.context(store, role:)       │
+│              Composition.<use_case>(ctx).call(...)         │
+└──────────────────────┬─────────────────────────────────────┘
+                       │
+┌─ Application ────────▼─────────────────────────────────────┐
+│  Context          (per-request: store, role, correlation,  │
+│                    clock, dry_run; can_read?/can_write?)   │
+│  Composition      (factory module)                         │
+│                                                            │
+│  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               │
+└──────────┬───────────────────────────────┬─────────────────┘
+           │ uses domain                   │ uses ports
+┌─ Domain ─▼─────────────────────────────────────────────────┐
+│  Permission             ← NEW: predicate, not Action       │
+│  Freshness::Policy      Freshness::Verdict                 │
+│  Freshness::Evaluator   Action  Outcome                    │
+└──────────────────────────────────────────┬─────────────────┘
+                                           │ 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)                 │
+└────────────────────────────────────────────────────────────┘
+
+   Dependency rule: arrows point DOWN. Domain has zero outbound
+   imports. Application imports Domain + Infra (via ports).
+```
+
+## Read path (`store.get`)
+
+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.
+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:
+   - `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`
+9. Map outcome → envelope annotations (`stale`, `refreshing`, `refresh_error`) and return.
+
+## Write path (`store.put`)
+
+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.
+
+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.
+
+## Refresh path (`textus refresh 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`.
+   - 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).

data/CHANGELOG.md

@@ -8,6 +8,129 @@ The **gem version** (`0.x.y`) is distinct from the **protocol version**
 (currently `textus/2`, embedded in every envelope as `protocol`). The protocol
 is additive within a major; a new major would change the wire string.
 
+## 0.10.1 — Documentation refresh and spec hygiene (2026-05-22)
+
+Lightweight maintenance release: documentation refresh plus spec-suite hygiene. No `lib/` changes; no CLI, wire-protocol, or behavioral changes.
+
+### Changed
+
+- `docs/architecture.md` deleted. `ARCHITECTURE.md` is now the single source of truth for the layered architecture. Inbound links in `docs/zones.md`, `docs/events.md`, and `textus.gemspec` updated.
+- `SPEC.md` examples and CLI snippets refer to the post-0.9.2 default zone names (`identity` / `inbox` / `review` / `output`) instead of the pre-rename `canon` / `intake` / `pending` / `derived`. Prose that explicitly explains the 0.9.2 rename — including the v0.1 back-compat manifest example and the zone-rename table — is preserved.
+- `README.md` `refresh-stale` examples switched to `--zone=inbox`; the `cat .textus/zones/...` example points at the `output` zone.
+- `ARCHITECTURE.md` layer diagram references `Infra::Publisher` instead of bare `Publisher`.
+- `docs/zones.md` references `Textus::Infra::Publisher` instead of bare `Publisher`.
+
+### Testing
+
+- Deleted redundant `spec/proposal_spec.rb` (the same `"2026-05-19-add-bob"` fixture is covered more thoroughly by `spec/application/writes/accept_spec.rb`, the canonical post-0.9.1 home for Application-layer write tests).
+- Extracted `shared_context "textus_store_fixture"` into `spec/support/fixtures.rb`; 28 specs adopt it, replacing the repeated `let(:tmp)` / `let(:root)` / `after { FileUtils.remove_entry(tmp) }` triplet. `spec/spec_helper.rb` now autoloads `spec/support/**/*.rb`.
+- Fixed an `instance_variable_set(:@intake_handler, nil)` anti-pattern in `spec/refresh_spec.rb` — the "no intake declared" case now uses a manifest entry that was never given an intake handler, instead of mutating a private ivar after construction.
+
+## 0.10.0 — Shim removal, signal-based zone detection, Builder extraction (2026-05-22)
+
+### Breaking — Ruby API
+
+- `Textus::Publisher` constant removed. Use `Textus::Infra::Publisher`.
+- `Textus::Store::View` class removed. Use `Textus::Application::Context`
+  (constructed via `Composition.context(store, role:)`).
+- `Textus::Builder` class removed as a public entry point. Build logic lives
+  in `Textus::Application::Writes::Build`. External callers should use
+  `Textus::Composition.writes_build(ctx).call` instead of
+  `Textus::Builder.new(store).build`. The `Textus::Builder` namespace is
+  retained internally only for nested helpers (`Builder::Pipeline`,
+  `Builder::Renderer::*`).
+- `Application::Context` no longer exposes `put` / `delete` / `get` / `list`
+  / `where` shim methods. Hook callers that receive a Context via the
+  `store:` hook keyword must call `ctx.store.put(...)` etc., and explicitly
+  pass `as: ctx.role` for write operations.
+- Intake handler return values must use `_meta:` for frontmatter. The
+  previous `frontmatter:` legacy key is no longer accepted.
+
+### Fixed
+
+- `textus reject` and `textus refresh-stale` now work correctly for stores
+  that use the post-0.9.2 default zone names (`review`, `output`).
+  Zone-kind detection is now signal-based (driven by `writable_by:`
+  membership), not name-based. Stores using the pre-0.9.2 names (`pending`,
+  `derived`) continue to work.
+- Event payloads' `store:` keyword now carries a Context whose
+  `correlation_id` matches the event payload's top-level `correlation_id`
+  key. Previously the `store:` Context received a fresh, unrelated
+  `correlation_id`.
+
+### Added
+
+- `Textus::Manifest::Entry#in_generator_zone?` and `#in_proposal_zone?`
+  predicates. Internal `derived?` retained as an alias of
+  `in_generator_zone?`.
+- `:built` and `:published` events now carry `correlation_id` in the
+  payload, matching the existing pattern on `:put` / `:deleted` /
+  `:accepted`.
+
+### Removed
+
+- Legacy zone-purpose annotations for `canon` / `intake` / `pending` /
+  `derived` removed from `Textus::Intro::ZONE_PURPOSES`. Custom-named zones
+  continue to get no purpose annotation (existing behavior). Stores still
+  using the pre-rename default names will simply not get purpose
+  annotations on those zones in `textus intro` output.
+- Dead code: `Textus::Manifest#validate_keys!` removed (had no callers).
+
+### Internal
+
+- Builder logic fully extracted into `Application::Writes::Build`.
+- CLI verbs now share `context_for(store)` / `resolved_role(store)`
+  helpers on `CLI::Verb`.
+- Internal helpers in `Manifest`, `Doctor`, and `Manifest::Entry` are
+  properly marked private.
+
+### Unchanged
+
+- Wire protocol stays `textus/2`. Envelope shape unchanged.
+- CLI verbs, their flags, and their JSON output shape — unchanged.
+- Manifest YAML schema — unchanged.
+- Event names — unchanged (payload gains `correlation_id` on `:built` /
+  `:published`, but no existing key is removed or renamed).
+- Hook DSL — unchanged in shape. The `store:` keyword still passes an
+  object that responds to `.get`, `.list`, `.where`. The Context's
+  role-aware `with_role` is the recommended construction site for hook
+  contexts now.
+
+### Migration recipe
+
+```ruby
+# Hook handlers — before 0.10.0
+Textus.hook(:intake, :my_hook) do |store:, config:, args:|
+  store.put("inbox.foo", meta: { ... }, body: "...")  # used Context shim
+end
+
+# Hook handlers — 0.10.0+
+Textus.hook(:intake, :my_hook) do |store:, config:, args:|
+  ctx = store  # rename for clarity if desired
+  ctx.store.put("inbox.foo", meta: { ... }, body: "...", as: ctx.role)
+end
+
+# Intake handler returns — before 0.10.0
+{ frontmatter: { ... }, body: "..." }  # legacy key
+
+# Intake handler returns — 0.10.0+
+{ _meta: { ... }, body: "..." }  # _meta is the canonical key
+```
+
+If you imported the removed constants directly:
+
+```ruby
+# Before
+Textus::Publisher        # removed
+Textus::Store::View      # removed
+Textus::Builder.new(store).build(key, ...)  # removed
+
+# After
+Textus::Infra::Publisher
+Textus::Application::Context  # via Composition.context(store, role:)
+Textus::Composition.writes_build(ctx).call(key, ...)
+```
+
 ## 0.9.2 — Policies, audit verbs, zone rename (2026-05-22)
 
 ### Breaking — manifest YAML

data/README.md

@@ -77,7 +77,7 @@ For the full shape — Claude plugin with agents, skills, commands, pending walk
 
 ## What ships today
 
-- **Per-entry formats.** `format: markdown | json | yaml | text` on a manifest entry. `cat .textus/zones/derived/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`, `reducer`).
+- **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`, `reducer`).
 - **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.
 - **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 migrate --dry-run|--write` rewrites existing stores with illegal segments deterministically.
@@ -186,9 +186,9 @@ end
 To keep a batch of stale intake entries current in one shot:
 
 ```sh
-textus refresh-stale --prefix=working --zone=intake --as=script
-# or just refresh everything stale in the intake zone:
-textus refresh-stale --zone=intake --as=script
+textus refresh-stale --prefix=working --zone=inbox --as=script
+# or just refresh everything stale in the inbox zone:
+textus refresh-stale --zone=inbox --as=script
 ```
 
 The primitive `Textus.hook(event, name, **opts) { ... }` is also supported. See SPEC.md §5.10 for the full contract.

data/SPEC.md

@@ -23,7 +23,7 @@ textus is organized as five composable layers. Each layer has a single responsib
 | Layer | Name | Responsibility |
 |---|---|---|
 | L1 | **Store** | Plain-file backend: `.textus/zones/<zone>/...` with YAML frontmatter + Markdown body, addressed by dotted keys, schema-validated, etag-versioned. |
-| L2 | **Sources** | Declared external inputs (`intake` zone): URLs, files, feeds with declared parsers and TTLs. textus *describes* sources; external runners fetch and pipe results through `textus put`. |
+| L2 | **Sources** | Declared external inputs (the `inbox` zone in the default scaffold; any zone writable by `script`): URLs, files, feeds with declared parsers and TTLs. textus *describes* sources; external runners fetch and pipe results through `textus put`. |
 | L3 | **Compute** | Pure transforms from store entries to derived entries. Projections (select/pluck/sort/limit/format) plus a vendored Mustache template subset. No shell execution. |
 | L4 | **Publish** | Byte-for-byte file copy from derived entries to repo-relative paths declared via `publish_to:`. The in-store artifact is the consumer-shaped output; the published file is an identical copy. A sentinel under `.textus/sentinels/<target-rel-path>.textus-managed.json` records the source, sha256, and `mode: "copy"`. |
 | L5 | **Consumers** | Anything that reads the published files or calls the CLI — editors, LLM tools, MCP servers, CI jobs, dashboards. textus is agnostic about who consumes; the envelope is the contract. |
@@ -213,11 +213,11 @@ Every successful write records the resolved role and a wall-clock timestamp in `
 
 ### 5.2 Compute layer (derived entries)
 
-Derived entries live in the `derived` zone. They are not authored by hand; their body is produced by projecting over other entries. A derived entry's frontmatter declares a `projection` block:
+Derived entries live in a zone whose `writable_by:` list includes `build` — `output` in the default scaffold. They are not authored by hand; their body is produced by projecting over other entries. A derived entry's frontmatter declares a `projection` block:
 
 ```yaml
-- key: derived.catalogs.people
-  zone: derived
+- key: output.catalogs.people
+  zone: output
   projection:
     select: working.network.org    # prefix OR [list of prefixes]
     pluck:  [name, relationship, org]
@@ -250,7 +250,7 @@ publish_to:
   - .ai/instructions.md
 ```
 
-When the entry is recomputed, textus copies the in-store file byte-for-byte to each destination. The in-store artifact under `.textus/zones/derived/…` is already the consumer-shaped output (per the format strategy — see §5.x), so publish is a verbatim file copy with no parsing or stripping.
+When the entry is recomputed, textus copies the in-store file byte-for-byte to each destination. The in-store artifact under `.textus/zones/<output-zone>/…` is already the consumer-shaped output (per the format strategy — see §5.x), so publish is a verbatim file copy with no parsing or stripping.
 
 A sentinel is written for each published file at `<store_root>/sentinels/<target-relative-to-repo>.textus-managed.json`, recording `source`, `target`, the target's sha256, and `mode: "copy"`. Sentinels live under the store rather than beside the consumer file so target directories stay clean. The sentinel exists so out-of-band edits can be detected on the next publish — textus refuses to clobber a destination that is not either missing or marked as managed. Legacy sibling sentinels (`<target>.textus-managed.json`) are still recognised as managed and are migrated to the new location on the next publish.
 
@@ -301,13 +301,13 @@ In intake mode the handler MUST return one of three shapes, all normalized by th
 **Refresh paths.** Two are supported:
 
 1. **In-process** — `textus refresh KEY --as=script` resolves the entry's `intake.handler`, invokes the registered `:intake` hook with `(config:, store:, args: {})`, and writes the result under role `script`.
-2. **External runner** — a cron job or agent harness reads `textus list --zone=intake --stale --format=json`, fetches the source out of band, and pipes bytes back through `textus put KEY --as=script --stdin`. The CLI verb `textus refresh-stale [--prefix=K] [--zone=Z]` drives this loop in one shot.
+2. **External runner** — a cron job or agent harness reads `textus list --zone=inbox --stale --format=json`, fetches the source out of band, and pipes bytes back through `textus put KEY --as=script --stdin`. The CLI verb `textus refresh-stale [--prefix=K] [--zone=Z]` drives this loop in one shot.
 
 Both paths share the same role gate, audit-log entry, and `:refreshed` event. User-supplied hooks live in `.textus/hooks/**/*.rb` and auto-load at `Store#initialize` — see §5.10 for the full hook contract.
 
 ### 5.5 Pending / accept workflow
 
-Pending entries are full proposal patches authored into the `pending` zone, typically by agents or scripts. A pending entry's frontmatter describes the patch it proposes against another zone:
+Proposal entries are full patches authored into a zone whose `writable_by:` list includes `ai` — `review` in the default scaffold — typically by agents or scripts. The entry's frontmatter describes the patch it proposes against another zone:
 
 ```yaml
 ---
@@ -324,7 +324,7 @@ Proposed body content.
 
 `proposal.target_key` names the entry the patch would create or modify, and `proposal.action` is `put` or `delete`. The remaining frontmatter and body are the proposed new content.
 
-`textus accept <pending-key>` is **human-only**: the resolved role must be `human`. It copies the patch into the target zone, records provenance (originating pending key, original role, original timestamp) in the audit log, and removes the pending entry. Agents and scripts can propose but cannot accept.
+`textus accept <proposal-key>` is **human-only**: the resolved role must be `human`. It copies the patch into the target zone, records provenance (originating proposal key, original role, original timestamp) in the audit log, and removes the proposal entry. Agents and scripts can propose but cannot accept.
 
 ### 5.6 Audit log
 

data/docs/conventions.md

@@ -18,7 +18,7 @@ Recommended top-level layout — the spec allows alternatives, but this is what
   manifest.yaml
   schemas/        # YAML schema definitions
   zones/
-    identity/     # identity, voice, canon — humans only
+    identity/     # identity, voice, slow-changing facts — humans only
     working/      # agent-writable working memory
     inbox/        # script-fed external inputs
     review/       # AI proposals awaiting accept

data/lib/textus/application/context.rb

@@ -39,30 +39,6 @@ module Textus
           dry_run: @dry_run,
         )
       end
-
-      # Backward-compat for intake handlers receiving a Context (was Store::View)
-      # that call store.put/get/delete on it. Slated for removal in 0.10.0.
-      def put(key, **opts)
-        opts[:as] ||= role
-        store.put(key, **opts)
-      end
-
-      def delete(key, **opts)
-        opts[:as] ||= role
-        store.delete(key, **opts)
-      end
-
-      def get(key, **)
-        store.get(key, **)
-      end
-
-      def list(*, **)
-        store.list(*, **)
-      end
-
-      def where(*, **)
-        store.where(*, **)
-      end
     end
   end
 end

data/lib/textus/application/refresh/orchestrator.rb

@@ -2,11 +2,12 @@ module Textus
   module Application
     module Refresh
       class Orchestrator
-        def initialize(worker:, bus:, store_root:, store: nil, detached_spawner: nil)
+        def initialize(worker:, bus:, store_root:, store: nil, role: "human", detached_spawner: nil)
           @worker = worker
           @bus = bus
           @store_root = store_root
           @store = store
+          @role = role
           @detached_spawner = detached_spawner || default_spawner
         end
 
@@ -46,7 +47,7 @@ module Textus
 
           if thread.alive?
             thread.kill
-            store_view = @store ? Textus::Store::View.new(@store) : nil
+            store_view = @store ? Textus::Application::Context.new(store: @store, role: @role) : nil
             payload = { key: key, started_at: Time.now.utc.iso8601, budget_ms: budget_ms }
             payload[:store] = store_view if store_view
             @bus.publish(:refresh_detached, **payload)

data/lib/textus/application/refresh/worker.rb

@@ -23,7 +23,7 @@ module Textus
         private
 
         def read_view
-          Store::View.new(@ctx.store)
+          Application::Context.new(store: @ctx.store, role: @ctx.role)
         end
 
         def fetch_with_bus(key, mentry)

data/lib/textus/application/writes/accept.rb

@@ -17,6 +17,8 @@ module Textus
 
           case action
           when "put"
+            # Nested proposal "frontmatter" — the meta to write to the accepted
+            # target. Not related to the removed intake-handler legacy bridge.
             target_meta = env["_meta"]["frontmatter"] || {}
             target_body = env["body"]
             Composition.writes_put(@ctx).call(target, meta: target_meta, body: target_body)
@@ -28,9 +30,8 @@ module Textus
 
           Composition.writes_delete(@ctx).call(pending_key)
 
-          store_view = Store::View.new(@ctx.store)
           @bus.publish(:accepted,
-                       store: store_view,
+                       store: @ctx.with_role(@ctx.role),
                        key: pending_key,
                        target_key: target,
                        correlation_id: @ctx.correlation_id)

data/lib/textus/application/writes/build.rb

@@ -1,6 +1,12 @@
+require "fileutils"
+
 module Textus
   module Application
     module Writes
+      # Materializes generator-zone entries (template + projection) onto disk
+      # and copies the result to any configured `publish_to` / `publish_each`
+      # targets. Fires `:built` and `:published` events on the bus, tagged with
+      # the request's correlation_id for traceability.
       class Build
         def initialize(ctx:, bus:)
           @ctx = ctx
@@ -8,15 +14,101 @@ module Textus
         end
 
         def call(prefix: nil)
-          # Delegate to legacy Builder for the materialization/projection logic.
-          # Builder fires its own events through @store.fire_event; we do NOT
-          # double-fire from here. Full extraction of Builder internals into
-          # Writes::Build is deferred to 0.10.0.
-          #
-          # TODO(0.10.0): propagate @ctx.correlation_id through :built/:published
-          # events once Builder internals are extracted into this use case.
-          legacy = Textus::Builder.new(@ctx.store)
-          legacy.build(prefix: prefix)
+          built = []
+          manifest.entries.each do |mentry|
+            next unless mentry.in_generator_zone?
+            next unless mentry.projection || mentry.template
+            next if prefix && !mentry.key.start_with?(prefix)
+
+            built << materialize(mentry)
+          end
+          published_leaves = publish_leaves(prefix: prefix)
+          { "protocol" => Textus::PROTOCOL, "built" => built, "published_leaves" => published_leaves }
+        end
+
+        private
+
+        def store = @ctx.store
+        def manifest = store.manifest
+        def root = store.root
+
+        def publish_leaves(prefix: nil)
+          repo_root = File.dirname(root)
+          out = []
+          manifest.entries.each do |mentry|
+            next unless mentry.nested && mentry.publish_each
+            next if prefix && !mentry.key.start_with?(prefix) && !prefix.start_with?("#{mentry.key}.")
+
+            manifest.enumerate(prefix: mentry.key).each do |row|
+              next unless row[:manifest_entry].equal?(mentry)
+              next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
+
+              out << publish_leaf(mentry, row, repo_root)
+            end
+          end
+          out
+        end
+
+        def publish_leaf(mentry, row, repo_root)
+          target_rel = mentry.publish_target_for(row[:key])
+          target_abs = File.expand_path(File.join(repo_root, target_rel))
+          unless target_abs.start_with?(File.expand_path(repo_root) + File::SEPARATOR)
+            raise PublishError.new(
+              "entry '#{mentry.key}': publish_each target '#{target_rel}' for key '#{row[:key]}' escapes repo root",
+            )
+          end
+
+          Textus::Infra::Publisher.publish(source: row[:path], target: target_abs, store_root: root)
+          publish_event(:published,
+                        key: row[:key],
+                        envelope: store.get(row[:key]),
+                        source: row[:path],
+                        target: target_abs)
+          { "key" => row[:key], "source" => row[:path], "target" => target_abs }
+        end
+
+        def materialize(mentry)
+          target_path = Builder::Pipeline.run(
+            store: store,
+            mentry: mentry,
+            template_loader: ->(name) { read_template(name) },
+          )
+          publish_and_fire(mentry, target_path)
+          { "key" => mentry.key, "path" => target_path, "published_to" => mentry.publish_to }
+        end
+
+        def read_template(name)
+          tpl_path = File.join(root, "templates", name)
+          raise TemplateError.new("template not found: #{tpl_path}", template_name: name) unless File.exist?(tpl_path)
+
+          File.read(tpl_path)
+        end
+
+        def publish_and_fire(mentry, target_path)
+          envelope = store.get(mentry.key)
+          repo_root = File.dirname(root)
+
+          mentry.publish_to.each do |rel|
+            target_abs = File.join(repo_root, rel)
+            Textus::Infra::Publisher.publish(source: target_path, target: target_abs, store_root: root)
+            publish_event(:published,
+                          key: mentry.key,
+                          envelope: envelope,
+                          source: target_path,
+                          target: target_abs)
+          end
+
+          publish_event(:built,
+                        key: mentry.key,
+                        envelope: envelope,
+                        sources: Array(mentry.projection&.fetch("select", nil)).compact)
+        end
+
+        def publish_event(event, **payload)
+          # `with_role` returns a Context that preserves the original
+          # correlation_id, so hooks reading `store.correlation_id` see the
+          # same value as the event's top-level correlation_id key.
+          @bus.publish(event, store: @ctx.with_role(@ctx.role), correlation_id: @ctx.correlation_id, **payload)
         end
       end
     end

data/lib/textus/application/writes/delete.rb

@@ -22,9 +22,8 @@ module Textus
           )
 
           unless suppress_events
-            store_view = Store::View.new(@ctx.store)
             @bus.publish(:deleted,
-                         store: store_view,
+                         store: @ctx.with_role(@ctx.role),
                          key: key,
                          correlation_id: @ctx.correlation_id)
           end

data/lib/textus/application/writes/put.rb

@@ -28,9 +28,8 @@ module Textus
           )
 
           unless suppress_events
-            store_view = Store::View.new(@ctx.store)
             @bus.publish(:put,
-                         store: store_view,
+                         store: @ctx.with_role(@ctx.role),
                          key: key,
                          envelope: envelope,
                          correlation_id: @ctx.correlation_id)

data/lib/textus/builder/pipeline.rb

@@ -2,7 +2,7 @@ require "fileutils"
 require "time"
 
 module Textus
-  class Builder
+  module Builder
     module InjectMeta
       # Returns a new hash with _meta as the first key, per SPEC §6 ordering.
       def self.call(content_hash, mentry)

data/lib/textus/builder/renderer/json.rb

@@ -1,7 +1,7 @@
 require "json"
 
 module Textus
-  class Builder
+  module Builder
     class Renderer
       class Json < Renderer
         def call(mentry:, data:)

data/lib/textus/builder/renderer/markdown.rb

@@ -1,7 +1,7 @@
 require "time"
 
 module Textus
-  class Builder
+  module Builder
     class Renderer
       class Markdown < Renderer
         def call(mentry:, data:)

data/lib/textus/builder/renderer/text.rb

@@ -1,5 +1,5 @@
 module Textus
-  class Builder
+  module Builder
     class Renderer
       class Text < Renderer
         def call(mentry:, data:)

data/lib/textus/builder/renderer/yaml.rb

@@ -1,7 +1,7 @@
 require "yaml"
 
 module Textus
-  class Builder
+  module Builder
     class Renderer
       class Yaml < Renderer
         def call(mentry:, data:)

data/lib/textus/builder/renderer.rb

@@ -1,5 +1,5 @@
 module Textus
-  class Builder
+  module Builder
     # Abstract base for output renderers. Each concrete renderer owns
     # producing the bytes for one manifest format (markdown/json/yaml/text).
     class Renderer

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

@@ -6,8 +6,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("accept requires a key")
-          role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-          ctx = Textus::Composition.context(store, role: role)
+          ctx = context_for(store)
           emit(Textus::Composition.writes_accept(ctx).call(key))
         end
       end

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

@@ -11,8 +11,7 @@ module Textus
         option :limit, "--limit=N"
 
         def call(store)
-          role = Role.resolve(flag: nil, env: ENV, root: store.root)
-          ctx = Textus::Composition.context(store, role: role)
+          ctx = context_for(store)
           since_time = since && Textus::Application::Reads::Audit.parse_since(since, now: ctx.now)
           rows = Textus::Composition.audit(ctx).call(
             key: key_filter,

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

@@ -6,8 +6,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("blame requires a key")
-          role = Role.resolve(flag: nil, env: ENV, root: store.root)
-          ctx = Textus::Composition.context(store, role: role)
+          ctx = context_for(store)
           rows = Textus::Composition.blame(ctx).call(key: key, limit: limit&.to_i)
           emit({ "verb" => "blame", "key" => key, "rows" => rows })
         end

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

@@ -7,8 +7,7 @@ module Textus
 
         def call(store)
           key = positional.shift or raise UsageError.new("delete requires a key")
-          role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-          ctx = Textus::Composition.context(store, role: role)
+          ctx = context_for(store)
           emit(Textus::Composition.writes_delete(ctx).call(key, if_etag: if_etag))
         end
       end