textus 0.52.0 → 0.54.0

data/docs/architecture/README.md

@@ -1,110 +1,146 @@
 # Textus architecture
 
 > **Explanation** · for contributors · **read this first** for orientation before SPEC
-> **SSoT for** the Ruby implementation layout (layers, container, ports, read/write/produce paths) · **reviewed** 2026-06 (v0.45)
+> **SSoT for** the Ruby implementation layout (layers, container, ports, dispatch paths) · **reviewed** 2026-06 (v0.54)
 
 ```mermaid
 flowchart TD
-    interface["Interface — CLI verbs · MCP gate (JSON-RPC)"]
-    application["Application — Call · Container · Dispatcher · RoleScope<br/>read/ · write/ · maintenance/ · produce/ use cases · envelope IO"]
-    domain["Domain — Permission · Freshness<br/>Policy (Guard · GuardFactory · BaseGuards · Evaluation · Fetch · Matcher · Predicates)"]
-    infra["Infrastructure — Store · FileStore · Manifest · Schemas<br/>Ports · Hooks · Entry format strategies"]
-    interface --> application
-    application --> domain
-    application --> infra
-    domain -.->|implemented by| infra
+    surfaces["Surfaces — CLI · MCP · RoleScope"]
+    contract["Contract — per-verb DSL (source of truth for public interfaces)"]
+    gate["Gate — routing (VERB_COMMAND) · Auth"]
+    action["Actions — per-verb use cases (action/)"]
+    jobs["Jobs — Worker · Planner · Materialize · Retention · Sweep"]
+    produce["Produce — Engine · Render"]
+    workflow["Workflow — Runner · Registry · Loader · DSL"]
+    manifest["Manifest — declarative config, no IO (policy/, schema/, entry/)"]
+    core["Core — pure value types (Freshness, Retention, Duration, Sentinel)"]
+    ports["Ports — IO adapters (FileStore, AuditLog, JobStore, Publisher…)"]
+    surfaces --> contract
+    contract --> gate
+    gate --> action
+    action --> jobs
+    action --> produce
+    produce --> workflow
+    action --> manifest
+    action --> core
+    action --> ports
+    jobs --> produce
 ```
 
-*Dependency rule: arrows point down.* Domain performs no direct `File`/`Dir`/`Time.now` I/O — all disk and clock access is routed through injected ports; pure path math is allowed. Application imports Domain + Ports. Use cases are plain classes on `(container:, call:)`. Verbs are looked up in the static `Dispatcher::VERBS` table.
+*Dependency rule: inward only.* Surfaces → Contract → Gate → Actions → inner layers. Actions never reference surfaces.
 
 ### What lives in each layer
 
-**Interface**
+**Surfaces**
 
 ```
-CLI verbs:  store.<verb>(..., role:)
-            store.as(role).<verb>(...)    # (put/get/fetch/…)
+surfaces/cli/     CLI command generation from contracts
+surfaces/mcp/     MCP server — stdio JSON-RPC 2.0, tools derived from contracts
+surfaces/role_scope.rb
+                  (Store#as(role)) — holds (container, role, dry_run, correlation_id);
+                  all verb methods injected via define_method in textus.rb
+```
+
+**Contract**
+
+```
+contract/         Per-verb DSL — verb, summary, surfaces, arg, view.
+                  Contract::Binder.inputs_from_ordered splits the uniform inputs hash
+                  into positional/keyword args for every surface.
+```
+
+**Gate + Auth**
+
+```
+gate.rb           VERB_COMMAND  (verb symbol → Command class)
+                  Gate#dispatch(cmd) — Auth → action call
+gate/auth.rb      Authorization engine — FLOOR predicates + rule guards
+```
+
+**Actions**
+
+```
+action/{get,list,put,key_delete,key_mv,accept,reject,propose,
+        drain,enqueue,audit,blame,deps,rdeps,published,boot,doctor,
+        rule_explain,rule_list,rule_lint,pulse,
+        data_mv,key_mv_prefix,key_delete_prefix,
+        schema_envelope,where,uid,jobs}.rb
+```
+
+**Jobs**
 
-MCP gate:   textus mcp serve — same use cases, JSON-RPC.
+```
+jobs/planner.rb   Rules-driven job planning — seeds materialize/refresh/sweep jobs
+jobs/worker.rb    Queue drain — leases and runs jobs from JobStore
+jobs/materialize.rb  Per-key produce job → Produce::Engine.converge
+jobs/refresh.rb   Per-key refresh job (retention-rule-triggered)
+jobs/retention.rb Retention policy check
+jobs/sweep.rb     Lane sweep job
 ```
 
-The CLI is a **projection of the per-verb `Contract`** (ADR 0063), the operator
-mirror of `MCP::Catalog`. The contract now owns the whole request lifecycle —
-`acquire → bind → invoke → render` (ADRs 0066–0068): one `Contract::Binder.bind`
-splits the uniform by-name `inputs` hash into the use-case's positional/keyword
-args for every surface; per-surface `view`s shape the output (`view` for
-MCP/Ruby, `view(:cli)` for the operator envelope); declarative `source:`/
-`coerce:`/`cli_stdin` populate inputs from files and stdin; `around:` resources
-wrap the single dispatch site (`RoleScope#dispatch_bound`) for stateful verbs;
-and `cli_default:` declares a CLI default that diverges from the agent default.
-`CLI::Runner` generates a command per `:cli` contract, dispatching `contract.verb`
-by construction. Only verbs with genuine *behavior* — `put` (entry persistence),
-`get` (UnknownKey + resolver suggestions, CLI-only), and `doctor` (not yet
-generatable) — stay hand-authored, plus commands with no dispatcher verb (`init`,
-`hook`, `mcp serve`, `schema diff/init`). `boot` is auto-generated from its
-contract. Total reconciliation specs make name/dispatch/facet drift unrepresentable.
-
-**Application**
+**Produce**
 
 ```
-Call             (slim Data: role, correlation_id, now,
-                  dry_run — request state only)
-Container        (single record — wired ports + manifest)
-Dispatcher       (static VERBS table: verb → use-case)
-RoleScope        (Store#as(role) — forwards verb calls)
-
-read/{get,list,where,uid,schema_envelope,
-      deps,rdeps,published,validate_all,boot,doctor,
-      freshness,audit,blame,rule_explain,rule_list,pulse}.rb
-write/{put,key_delete,key_mv,accept,reject,propose}.rb
-maintenance/{drain,serve,worker,key_mv_prefix,key_delete_prefix,
-             zone_mv,rule_lint}.rb
-produce/{engine,events,render,
-         acquire/{intake,handler,projection,serializer}}.rb
-envelope/io/{reader,writer}.rb  (split: parse vs persist)
-projection.rb
+produce/engine.rb         Engine.converge(container:, call:, keys:)
+                          For each key: looks up a registered workflow and runs it,
+                          or publishes existing bytes for entries with publish targets.
+produce/render.rb         Mustache template expansion for publish targets
 ```
 
-**Domain**
+**Workflow**
+
+```
+workflow/runner.rb    Runs a Definition: build_context → execute_steps → publish
+workflow/registry.rb  In-memory list of registered Definitions; Registry#for(key)
+workflow/loader.rb    Loads .textus/workflows/*.rb files via Collector DSL
+workflow/dsl.rb       Textus.workflow "name" { match "...", step :fetch { ... }, publish }
+workflow/context.rb   Context passed to each step (key, entry, config, container, call)
+workflow/pattern.rb   Key-matching pattern (glob via File.fnmatch?)
+workflow/errors.rb    NotFound, StepFailed
+```
+
+**Core (pure value types)**
 
 ```
-Permission         (write predicate per zone)
 Freshness::{Verdict,Evaluator}
-Action  Outcome  Sentinel
-Policy::{Guard,GuardFactory,BaseGuards,Evaluation,Fetch,Matcher,HandlerAllowlist,
-         Predicates::{ZoneWritableBy,SchemaValid,AuthorHeld,TargetIsCanon,EtagMatch,FreshWithin}}
+Core::Duration  Core::Sentinel
 ```
 
 **Infrastructure**
 
 ```
-Store              (composition root — wires ports,
-                    vends a Container + dispatches verbs)
-Storage::FileStore (bytes-only port: read/write/delete/
-                    exists?/etag)
+Store              (composition root — wires ports, vends Container)
+Storage::FileStore (bytes-only port: read/write/delete/exists?/etag)
 Manifest           (Data, Resolver, Policy, Rules)
 Schemas            (eager-load cache)
-Ports::{AuditLog,AuditSubscriber,Publisher,Clock,
-        BuildLock,Queue,ProduceOnWriteSubscriber,SentinelStore}
-Hooks::{EventBus,RpcRegistry,Loader,Context,FireReport,
-        Signature,Builtin,ErrorLog}
+Ports::{AuditLog,JobStore,Publisher,Clock,
+        BuildLock,SentinelStore}
 Entry::{Markdown,Json,Yaml,Text}  (format strategies)
 ```
 
 ## How a verb becomes a method
 
-Each application use case is a plain class under `lib/textus/{read,write,maintenance}/`. The shape is uniform:
+All actions live under `lib/textus/action/`. The shape is uniform:
 
 ```ruby
 module Textus
-  module Read
-    class Get
-      def initialize(container:, call:)
-        @container = container
-        @call      = call
+  module Action
+    class Get < Base
+      extend Textus::Contract::DSL
+
+      verb :get
+      summary "Read an entry by key."
+      surfaces :cli, :mcp
+      arg :key, String, required: true, positional: true
+
+      BURN = :sync
+
+      def initialize(key:)
+        super()
+        @key = key
       end
 
-      def call(key)
+      def call(container:, call:)
         ...
       end
     end
@@ -112,19 +148,7 @@ module Textus
 end
 ```
 
-Verbs are looked up in a static frozen table (`Textus::Dispatcher::VERBS`) that maps `:get → Textus::Read::Get`, `:put → Textus::Write::Put`, etc. `Store#put` / `Store#get` / `Store#as(role).<verb>(...)` instantiate the use case on `(container:, call:)` and invoke `#call`. Adding a new verb is **one entry in `Dispatcher::VERBS`** plus the class — no metaprogramming.
-
-The instantiate-and-call step itself has one home: `Dispatcher.invoke(verb, container:, call:, args:, kwargs:)` (ADR 0026). `RoleScope` builds the `Call` (request state) and delegates the dispatch to `Dispatcher.invoke`; the convention for invoking a uniform-shape use case lives next to the table that maps the verbs, not re-spelled in the caller. `Store`'s own verb loop is separate — it extracts the `role:` keyword and forwards to `as(role)`, a role-selection job distinct from invocation.
-
-`boot` and `doctor` are read verbs like any other: `Read::Boot` / `Read::Doctor`
-are thin `(container:, call:)` use cases that delegate to the `Textus::Boot` /
-`Textus::Doctor` report-building libraries (`build(container:, ...)`). They are
-reached through `Dispatcher::VERBS`, not a special method on `RoleScope`.
-
-Two collaborators live outside the dispatcher because they're composed by other use cases, not invoked as verbs:
-
-- `Produce::Engine` — runs the produce pipeline that `drain`/`serve` invoke via the `materialize` job handler; composes `Acquire::Intake` (external pull via handler) with `Produce::Render` (template-driven publish) per entry. Reactive re-produce is enqueued as `materialize` jobs by `Ports::ProduceOnWriteSubscriber` and run by a worker (no in-process thread runner).
-- `Envelope::IO::{Reader,Writer}` — own the parse and persist halves of the write pipeline; the audit-append-as-final-step invariant lives in `Writer`.
+Verbs are looked up in a static frozen table (`Textus::Action::VERBS`) that maps `:get → Action::Get`, `:put → Action::Put`, etc. Adding a new verb is one entry in `VERBS` plus the class — no metaprogramming.
 
 ## Container
 
@@ -133,128 +157,105 @@ Use cases never see the raw `Store`. `Textus::Container` is a single record hold
 ```ruby
 Container = Data.define(
   :manifest, :file_store, :schemas, :root,
-  :audit_log, :events, :rpc
+  :audit_log, :workflows, :gate
 )
 ```
 
-The `Store` builds one `Container` at boot; every use case receives it via `(container:, call:)`. RPC hook callables (`:resolve_handler`, `:transform_rows`, `:validate`) receive `caps: <Container>` — field names match what the prior `WriteCaps` exposed, so handlers reading `caps.manifest`, `caps.events`, etc. continue to work.
+The `Store` builds one `Container` at boot; every action receives it via `(container:, call:)`. Workflow steps receive a `Workflow::Context` (key, entry, config, container, call).
 
 ## Ports
 
-Ports are infrastructure adapters with an interface defined by the domain. Each port is independently replaceable — swap the implementation for tests or alternative runtimes without touching application or domain code.
-
 | Class | Role |
 |---|---|
-| `Ports::Storage::FileStore` | Bytes-only FS I/O — `read`, `write`, `delete`, `exists?`, `etag`. No knowledge of envelopes or schemas. |
-| `Ports::AuditLog` | Append-only structured log (`audit.log`). Owns seq numbering, file-locking, and rotation. |
-| `Ports::Clock` | Supplies `Time.now` — a module-function so tests can swap it without dependency injection boilerplate. |
-| `Ports::Publisher` | Copies a built artifact to a repo-relative consumer path and writes a sentinel so the next publish can confirm the target is managed. |
-| `Ports::BuildLock` | Process-exclusive `flock` guard over the produce pipeline. Raises `BuildInProgress` if a build is already running. |
-| `Ports::ProduceOnWriteSubscriber` | Pub-sub listener on `entry_written`/`entry_deleted`/`entry_renamed`; enqueues `materialize` jobs onto `Ports::Queue` for reactive re-produce after any write/delete/rename. |
-| `Ports::SentinelStore` | Reads and writes the per-target sentinel file that `Publisher` uses to detect unmanaged overwrites. |
+| `Ports::Storage::FileStore` | Bytes-only FS I/O — `read`, `write`, `delete`, `exists?`, `etag`. |
+| `Ports::AuditLog` | Append-only structured log (`audit.log`). Owns seq numbering, file-locking, rotation. |
+| `Ports::Clock` | Supplies `Time.now` — module-function so tests can swap without DI boilerplate. |
+| `Ports::Publisher` | Copies a built artifact to a repo-relative consumer path and writes a sentinel. |
+| `Ports::BuildLock` | Process-exclusive `flock` guard over the produce pipeline. |
+| `Ports::JobStore` | Persistent job queue used by `drain` workers; tracks ready/leased/done/failed jobs. |
+| `Ports::SentinelStore` | Reads and writes per-target sentinel files for managed-file detection. |
 
 Application use cases access ports only through `Container` fields — never through the raw `Store`.
 
-### EnvelopeIO
-
-`Envelope::IO::Reader` and `Envelope::IO::Writer` split the envelope pipeline into read-only parse and write-with-audit halves.
+### Envelope
 
-**Reader** (`lib/textus/envelope/io/reader.rb`) — resolves a key through `manifest.resolver`, reads bytes via `FileStore`, delegates parsing to the format strategy (`Entry.for_format`), and returns an `Envelope`. No audit, no events, no permission checks. Also used by `Writer` for the existing-uid lookup on `put`.
+`Envelope::Reader` and `Envelope::Writer` split the envelope pipeline into read-only parse and write-with-audit halves.
 
-**Writer** (`lib/textus/envelope/io/writer.rb`) — owns the full write pipeline: serialize → schema-validate → etag-check → `FileStore#write` → `AuditLog#append`. The class comment states the invariant directly: every public method's final action is `@audit_log.append(...)`. If the audit append fails, the caller sees the underlying error — the byte write already happened, but the pipeline contract treats audit as the commit step. No permission check, no event firing — those stay in the calling use case (`Write::Put`, `Write::Delete`, `Write::Mv`).
+**Reader** (`lib/textus/envelope/reader.rb`) — resolves a key through `manifest.resolver`, reads bytes via `FileStore`, parses via the format strategy, returns an `Envelope`. No audit, no permissions.
 
-The three public methods are `put`, `delete`, and `move`; all follow the same validate → write → audit sequence.
+**Writer** (`lib/textus/envelope/writer.rb`) — owns the full write pipeline: serialize → schema-validate → etag-check → `FileStore#write` → `AuditLog#append`. The audit append is the commit step.
 
-Both are built from a `Container` via named constructors — `Writer.from(container:, call:)` (which builds its own `Reader.from`) and `Reader.from(container:)` (ADR 0026). Write use cases call `Writer.from` rather than reconstructing the object graph by hand, so a change to the Writer's dependencies is a one-line edit in one place.
+Both are built from a `Container` via named constructors — `Writer.from(container:, call:)` and `Reader.from(container:)`.
 
 ## Manifest carving
 
-Manifest carving means slicing the parsed manifest YAML into four purpose-specific sub-objects. Each consumer sees only the fields it needs; none reach into the full raw document.
-
-`Manifest` itself is a `Data.define` struct — a composition record with four named members:
+`Manifest` is a `Data.define` struct with four named members:
 
 | Member | Class | Responsibility |
 |---|---|---|
-| `data` | `Manifest::Data` | Frozen value: `raw`, `root`, `zones`, `entries`, `audit_config`, `role_caps` (role name → capability set). Structural data only — no behaviour beyond accessors and key validation. |
-| `resolver` | `Manifest::Resolver` | Key → `Resolution(entry, path, remaining)`. Handles nested entry enumeration and fuzzy-match suggestions. |
-| `policy` | `Manifest::Policy` | Zone/capability authority — `verb_for_zone` (zone-kind → required verb), `roles_with_capability(verb)`, `zone_writers` (derived: roles holding the verb the zone's kind requires), `permission_for`, `declared_kind`, `proposer_role`, `propose_zone_for(role)`. Write authority is derived from capabilities × zone-kind (ADR 0030); no filesystem I/O. `propose_zone_for` returns the single `kind: queue` zone when the role can write it (ADR 0027). |
-| `rules` | `Manifest::Rules` | Pattern-matched rule engine. `rules.for(key)` returns a `RuleSet(fetch, handler_allowlist, guard, retention)` by evaluating all `match:` blocks against the key. |
-
-Rationale: cleaner test seams — a use case that only needs key resolution constructs a `Manifest::Resolver` from a stub `Data`; one that only needs rule lookup constructs a `Manifest::Rules` directly. No consumer is forced to build the full manifest to exercise one sub-view.
-
-The four members are wired in `Manifest.build` (`lib/textus/manifest.rb`). `Manifest::Data` constructs `Policy` internally during `initialize`; the others are assembled by the loader and handed in as named arguments.
+| `data` | `Manifest::Data` | Frozen value: raw, root, lanes, entries, audit_config, role_caps. |
+| `resolver` | `Manifest::Resolver` | Key → `Resolution(entry, path, remaining)`. Nested entry enumeration and fuzzy-match suggestions. |
+| `policy` | `Manifest::Policy` | Zone/capability authority — `verb_for_lane`, `roles_with_capability`, `propose_lane_for(role)`. |
+| `rules` | `Manifest::Rules` | Pattern-matched rule engine. `rules.for(key)` → `RuleSet(guard, retention, react)`. |
 
 ## Read path (`store.get(key)`)
 
-`Read::Get` is the single public read verb. It is a **pure read** (ADR 0089): it resolves the path, reads bytes, parses the envelope, and annotates a freshness verdict — it NEVER ingests and NEVER mutates. The read-through that once refreshed a stale entry in-process (ADR 0062) is removed; quarantine freshness is system-pushed via `drain` (scheduled sweep) and `hook run` (event push).
+`Action::Get` is a **pure read** — it resolves the path, reads bytes, parses the envelope, and annotates a freshness verdict. It never ingests and never mutates.
 
-1. CLI verb (or MCP tool) calls `store.get(key, role:)` (or `store.as(role).get(key)`).
-2. `Store#get` looks up `Dispatcher::VERBS[:get] → Read::Get`, builds a `Call`, instantiates `Read::Get.new(container:, call:).call(key)`. The verb takes only `key` — there is no `fetch` flag on any surface.
-3. `Read::Get#call(key)` resolves the path through `container.manifest`, reads bytes via `container.file_store`, parses the envelope, and annotates a freshness verdict (`stale`, `reason`, `fetching: false`). When the key has no `upkeep` rule, the envelope is annotated fresh. A stale entry with `upkeep: { ttl:, action: refresh }` is returned **stale** — the read does not refresh it; the next `drain` does.
+1. CLI/MCP surface calls `store.as(role).get(key)`.
+2. `Gate#dispatch` runs Auth → `Action::Get#call`.
+3. `Get` resolves path via `manifest.resolver`, reads bytes via `file_store`, parses the envelope, annotates `freshness` based on retention-rule TTL (if any).
 
-Because the read is always pure, every caller — interactive reads, dashboards, and the direct in-process callers (accept/reject/publish, materializer, uid, validate_all/validator, schema/tools, hooks/context) — gets the same orchestrator-free, side-effect-free read. The prior read-through path (`get_or_fetch`, then the `fetch:`-flagged `Read::Get`, ADR 0062) and its `Write::FetchOrchestrator` are gone (ADR 0089).
+Staleness is age-based (retention-rule TTL vs file mtime). A stale entry is returned stale — the read does not refresh it; `drain` does.
 
 ## Write path (`store.put(key, ...)`)
 
-1. CLI verb calls `store.put(key, meta:, body:, content:, if_etag:, role:)`.
-2. `Write::Put#call` validates the key, resolves the manifest entry, builds `GuardFactory.for(:put, key)` and calls `Guard#check!(eval)` (topology is predicate #0, `zone_writable_by`) — raises `WriteForbidden` if the topology gate denies, `GuardFailed` if any other predicate fails.
-3. Delegates persistence to `Envelope::IO::Writer#put`, which serializes, schema-validates, etag-checks (raises `EtagMismatch` on conflict), writes via the `FileStore` port, and appends the audit row.
-4. Publishes `:entry_written` via `container.events` with `ctx: <Hooks::Context>`, `key:`, `envelope:`.
-
-`Write::{KeyDelete,KeyMv,Accept,Reject,Propose}` follow the same shape: explicit container, the unified `Guard` for authz (built per transition via `GuardFactory`), `Envelope::IO::Writer` for persistence (where applicable), event published with the `Hooks::Context` handle.
-
-`Write::KeyMv` delegates the file-move + audit to `Envelope::IO::Writer#move`, then publishes `:entry_renamed` itself. UID injection (when the source lacks one) goes through `Envelope::IO::Writer#write` directly — no `Put` bypass.
+1. CLI/MCP surface calls `store.as(role).put(key, meta:, body:)`.
+2. `Gate#dispatch` runs Auth → `Action::Put#call`.
+3. `Put` validates, resolves manifest entry, delegates to `Envelope::Writer#put` (serialize → schema-validate → etag-check → FileStore#write → AuditLog#append).
+4. `WriteVerb#cascade_to_rdeps` enqueues `materialize` jobs for any entries with publish_tree that depend on the written key.
 
-## Produce path (`drain`/`serve` + reactive `entry_written`)
+`Action::{KeyDelete,KeyMv,Accept,Reject,Propose}` follow the same shape.
 
-The produce pipeline handles two concerns — **acquire** (pull live data via an intake handler) and **render** (template-driven artifact publish) — unified under `Produce::Engine`.
+## Workflow path (`drain` + materialize jobs)
 
-`Produce::Engine.converge(container:, call:, keys:)` is the entry point the `materialize` job handler calls. Both the batch path (`drain`/`serve` seed jobs) and the reactive path (`Ports::ProduceOnWriteSubscriber` enqueues `materialize` jobs on `entry_written`/`entry_deleted`/`entry_renamed`) flow through the queue worker into `converge`.
+The workflow system owns the produce pipeline. `Produce::Engine.converge(container:, call:, keys:)` is the entry point that `Jobs::Materialize` calls.
 
 For each key, `Engine#produce_one`:
 
-1. **Acquire phase** — `Produce::Acquire::Intake#run(key)`:
-   - Resolves the manifest entry; looks up the intake handler via `container.rpc.callable(:resolve_handler, mentry.handler)`.
-   - Publishes `:entry_fetch_started` via `Produce::Events`.
-   - Invokes the handler under a timeout deadline.
-   - On error: publishes `:entry_fetch_failed`, re-raises.
-   - On success: normalises the handler result via its own `normalize_action_result` (keyed on the entry's format), checks guard, persists via `Envelope::IO::Writer`, publishes `:entry_fetched` unless the etag is unchanged.
-   - `Acquire::Handler` resolves and invokes the RPC callable under the timeout deadline. (The sibling **projection** sub-path — `from: project` entries — instead runs `Acquire::Projection`, which renders data files through `Acquire::Serializer::{Json,Yaml,Text}` before persisting.)
-2. **Render phase** — `entry.publish_via(context)` calls `Produce::Render#bytes_for(target:, data:, boot:)` to expand the Mustache template and copy the result to the publish target via `Ports::Publisher`. Returns `nil` if no publish is configured (skipped).
+1. Looks up a registered workflow via `container.workflows.for(key)` (Pattern matching against the key).
+2. If a workflow matches: `Workflow::Runner.new(definition, container:, call:).run(key)`.
+   - `Runner` builds a `Workflow::Context`, executes each step in sequence, then publishes.
+   - **Built-in publish**: writes the step output to the entry via `Envelope::Writer`, then calls `entry.publish_via(pctx)` for any `publish_to` or `publish_tree` targets.
+3. If no workflow matches but the entry has publish targets: runs `publish_only` — publishes existing store bytes via `entry.publish_via` without re-fetching.
 
-Reactive produce is enqueued as `materialize` jobs onto `Ports::Queue` when `entry_written`/`entry_deleted`/`entry_renamed` fires; a worker (`drain`/`serve`) runs them through `converge`. A held `BuildLock` is a soft miss — the in-flight build already produces fresh output.
+**Workflow files** live in `.textus/workflows/*.rb`. The DSL:
 
-## Hook payload contract
-
-Pub-sub hooks (`:entry_written`, `:entry_fetched`, …) receive `ctx:` — a `Textus::Hooks::Context` that exposes a narrow surface (`get`, `list`, `put`, `delete`, `audit`, `publish_followup`, plus `role` and `correlation_id`). The raw `Store` is not handed out.
-
-RPC hooks (`:resolve_handler`, `:transform_rows`, `:validate`) receive `caps:` — a `Textus::Container`. They are gem-internal: the framework calls them, not user pub-sub.
+```ruby
+Textus.workflow "my-producer" do
+  match "artifacts.derived.*"
+  step :fetch do |data, ctx|
+    { content: { "key" => ctx.key } }
+  end
+  publish  # uses built-in publish (writes to entry, then to publish targets)
+end
+```
 
 ## Agent surface (boot + pulse + MCP)
 
-Agents and plugins talk to a textus store through three layers:
-
 ```
-soul (skill/agent)  ──▶  gate (CLI | MCP)  ──▶  Store  ──▶  memory (.textus/)
+agent/plugin  ──▶  gate (CLI | MCP)  ──▶  Store  ──▶  memory (.textus/)
 ```
 
 Two transports, one façade:
 
 - **CLI** — human/script surface. `textus boot`, `textus pulse --since=N`, `textus get/put/...`.
-- **MCP** — agent surface. `textus mcp serve` runs a stdio JSON-RPC 2.0 server speaking MCP draft 2024-11-05. Tools are auto-derived from the manifest. Session state (cursor, role, contract_etag) is server-side.
-
-Both transports call `store.<verb>(..., role:)` (or `store.as(role).<verb>(...)`). No duplicate logic.
-
-The agent loop (cadence guide in [`agents-mcp.md`](../how-to/agents-mcp.md)):
-
-1. **Session start:** `boot()` → contract envelope (zones, entries, schemas, write_flows, agent_quickstart with `latest_seq`).
-2. **Per turn:** `pulse(since=cursor)` → `{cursor, changed, stale, pending_review, doctor}`.
-3. **On demand:** `get`, `put`, `propose`, `fetch`, `schema_show`, `rule_explain`.
-
-Contract drift surfaces as `ContractDrift` (contract_etag mismatch — a change to the manifest, hooks, or schemas; ADR 0074); audit cursor falls off the keep window as `CursorExpired`. Both signal "call `boot` again."
+- **MCP** — agent surface. `textus mcp serve` runs a stdio JSON-RPC 2.0 server. Tools are auto-derived from contracts. Session state (cursor, role, contract_etag) is server-side.
 
-## Hooks event catalog
+The agent loop:
 
-`Hooks::Signature` is the single home of callable keyword-introspection — both `EventBus` (pub-sub dispatch) and `RpcRegistry` (RPC dispatch) delegate to it for `accepts_keyrest?`, `declared_keys`, `missing`, and `filter` rather than each maintaining a hand-rolled copy (ADR 0027). RPC handlers declare `caps:` (single handler); pub-sub handlers declare `ctx:` (0..N handlers).
+1. **Session start:** `boot()` → contract envelope (lanes, entries, workflows, write_flows, agent_quickstart).
+2. **Per turn:** `pulse(since=cursor)` → `{cursor, changed, stale, pending_review, doctor, next_due_at}`.
+3. **On demand:** `get`, `put`, `propose`, `schema_show`, `rule_explain`, `drain`.
 
-The event names, payloads, and per-verb firing order are documented once in [`reference/events.md`](../reference/events.md) (the friendly SSoT); the authoritative source is `lib/textus/hooks/catalog.rb` (`Catalog::RPC` and `Catalog::PUBSUB`).
+Contract drift surfaces as `ContractDrift` (contract_etag mismatch — a change to manifest/schemas); audit cursor expiry as `CursorExpired`. Both signal "call `boot` again."

data/exe/textus

@@ -1,4 +1,4 @@
 #!/usr/bin/env ruby
 $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 require "textus"
-exit Textus::CLI.run(ARGV)
+exit Textus::Surfaces::CLI.run(ARGV)

data/lib/textus/action/accept.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Textus
+  module Action
+    class Accept < WriteVerb
+      extend Textus::Contract::DSL
+
+      verb :accept
+      summary "apply a queued proposal to its target zone; requires the author capability"
+      surfaces :cli, :mcp
+      cli "accept"
+      arg :pending_key, String, required: true, positional: true, description: "the queued proposal's key"
+
+      def initialize(pending_key:)
+        super()
+        @pending_key = pending_key
+      end
+
+      def call(container:, call:)
+        env = Textus::Action::Get.new(key: @pending_key).call(container: container, call: call)
+        proposal = env.meta["proposal"] or raise Textus::ProposalError.new("entry has no proposal block: #{@pending_key}")
+        target = proposal["target_key"] or raise Textus::ProposalError.new("proposal missing target_key")
+        action = proposal["action"] || "put"
+
+        case action
+        when "put"
+          Textus::Action::Put.new(
+            key: target,
+            meta: env.meta["_meta"] || {},
+            body: env.body,
+          ).call(container: container, call: call)
+        when "delete"
+          Textus::Action::KeyDelete.new(key: target).call(container: container, call: call)
+        else
+          raise Textus::ProposalError.new("unknown action: #{action}")
+        end
+
+        Textus::Action::KeyDelete.new(key: @pending_key).call(container: container, call: call)
+
+        { "protocol" => Textus::PROTOCOL, "accepted" => @pending_key, "target_key" => target, "action" => action }
+      end
+    end
+  end
+end

data/lib/textus/action/audit.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Textus
+  module Action
+    class Audit < Base
+      extend Textus::Contract::DSL
+
+      verb :audit
+      summary "Query the audit log with optional filters."
+      surfaces :cli
+      cli "audit"
+      arg :key, String, required: false, description: "filter to rows for this key"
+      arg :lane, String, required: false, description: "filter to keys in this lane"
+      arg :role, String, required: false, description: "filter to rows written under this role"
+      arg :verb, String, required: false, description: "filter to rows for this verb"
+      arg :since, String, required: false,
+                          coerce: ->(s) { Textus::Action::Audit.parse_since(s, now: Time.now) },
+                          description: "ISO-8601 timestamp or relative offset (e.g. 1h, 30m)"
+      arg :seq_since, Integer, required: false, description: "return rows with seq > this cursor value"
+      arg :correlation_id, String, required: false, description: "filter to rows with this correlation_id"
+      arg :limit, Integer, required: false, description: "maximum number of rows to return"
+      view(:cli) { |rows, _i| { "verb" => "audit", "rows" => rows } }
+
+      def initialize(**kwargs)
+        super()
+        @query = Query.build(**kwargs.slice(:key, :lane, :role, :verb, :since, :seq_since, :correlation_id, :limit))
+      end
+
+      def args
+        @query.to_h.compact
+      end
+
+      def call(container:, **)
+        @manifest = container.manifest
+        @root = container.root
+        @log_path = Textus::Layout.audit_log(container.root)
+        @audit_log = container.audit_log
+
+        query = @query
+        check_cursor_expiry!(query.seq_since)
+
+        files = all_log_files
+        return [] if files.empty?
+
+        rows = []
+        files.each do |file|
+          File.foreach(file) do |line|
+            parsed = parse_row(line.chomp)
+            next unless parsed
+            next unless query.matches?(parsed)
+            next if query.lane && !key_in_lane?(parsed["key"], query.lane)
+
+            rows << parsed
+            break if limit_reached?(rows, query)
+          end
+          break if limit_reached?(rows, query)
+        end
+
+        rows
+      end
+
+      def self.parse_since(str, now: Time.now.utc)
+        return nil if str.nil? || str.empty?
+        return Time.parse(str) if str =~ /\A\d{4}-\d{2}-\d{2}/
+
+        match = str.match(/\A(\d+)([smhd])\z/) or return nil
+        mult = { "s" => 1, "m" => 60, "h" => 3600, "d" => 86_400 }[match[2]]
+        now - (match[1].to_i * mult)
+      end
+
+      Query = Data.define(:key, :lane, :role, :verb, :since, :seq_since, :correlation_id, :limit) do
+        # rubocop:disable Metrics/ParameterLists
+        def self.build(key: nil, lane: nil, role: nil, verb: nil,
+                       since: nil, seq_since: nil, correlation_id: nil, limit: nil)
+          new(key:, lane:, role:, verb:, since:, seq_since:, correlation_id:, limit:)
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        def matches?(row)
+          return false if key && row["key"] != key
+          return false if role && row["role"] != role
+          return false if verb && row["verb"] != verb
+          return false if since && (row["ts"].nil? || Time.parse(row["ts"]) < since)
+          return false if seq_since && (row["seq"].nil? || row["seq"] <= seq_since)
+          return false if correlation_id && row.dig("extras", "correlation_id") != correlation_id
+
+          true
+        end
+      end
+
+      private
+
+      def limit_reached?(rows, query) = query.limit && rows.length >= query.limit
+
+      def check_cursor_expiry!(seq_since)
+        return unless seq_since
+
+        log = @audit_log || Textus::Ports::AuditLog.new(@root)
+        min = log.min_available_seq
+        raise Textus::CursorExpired.new(requested: seq_since, min_available: min) if min && seq_since < min - 1
+      end
+
+      def all_log_files
+        rotated = Dir.glob(File.join(Textus::Layout.audit_dir(@root), "audit.log.*"))
+                     .reject { |path| path.end_with?(".meta.json") }
+                     .sort_by { |path| -path.scan(/\d+$/).first.to_i }
+        active = File.exist?(@log_path) ? [@log_path] : []
+        rotated + active
+      end
+
+      def parse_row(line)
+        return nil if line.empty?
+        return nil unless line.start_with?("{")
+
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def key_in_lane?(key, lane)
+        mentry = @manifest.resolver.resolve(key).entry
+        mentry && mentry.lane == lane
+      rescue Textus::Error
+        false
+      end
+    end
+  end
+end