textus 0.18.0 → 0.20.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d7915be053bc7e858c821e0e8d8e8cebd3de6acde21dcd8f687ff3fa12db3d1
-  data.tar.gz: 792cd40df3e8046c954be84dc32d4e53a2b47cdfd9a21029c74953d39e182a87
+  metadata.gz: 35d3b6540fc043048133df0874e76b36e522d844da783b69a5e8993418157ae4
+  data.tar.gz: e0293b87efb32c1edf2d6c0103dcd94289d91031a4be570f8fdd40fb681c1e79
 SHA512:
-  metadata.gz: 457d079d8ebf25922f9389086ec2de99b96808f23fba7f600655fb2ef055a5a987dd1ea63924aaf9904c7f4e600b4aee33a8c2082028bbb9025068aa00de3b0e
-  data.tar.gz: a1192a6027b80582723b0cb4679b870ed78101864e22700ba7630308912f46000e774dbd69c589418516047dff2f8cdbf7a26e69e47d3a7ffcef89f917397a23
+  metadata.gz: '039b6f44941ea52ac8d956297d9619c4cc8b2346e7d8bced24bc5671506726a44348da66791aa6d032e56dd403353d1b34e9b2fee37eaec05cd6c83d5defc715'
+  data.tar.gz: e6e5e8f97f5f9a07a03813d61f9efa2088fb8f1338af89ba1298bf307c6c72e89f1028aa5a67ffdf8f97f2151c0af1273f82ff80751c59c11aa93ef2953323a9

data/ARCHITECTURE.md

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

data/CHANGELOG.md

@@ -9,6 +9,244 @@ The **gem version** (`0.x.y`) is distinct from the **protocol version**
 bump is a breaking change that requires a store migration; the gem version
 tracks both additive improvements and breaking protocol bumps independently.
 
+## 0.20.2 — 2026-05-27
+
+### Fixed
+- Promotion predicate `accept_authority_signed` now checks the role's *kind*
+  via `manifest.role_kind`, so manifests with a renamed authority role (e.g.
+  `owner` instead of `human`) pass the promotion gate. The internal class
+  `Predicates::HumanAccept` was renamed to `Predicates::AcceptAuthoritySigned`.
+- `textus schema migrate` now writes as the manifest's declared
+  `accept_authority` role instead of the literal `"human"`, and raises a
+  clear `UsageError` (with a YAML hint) when no `accept_authority` role is
+  declared.
+- `textus accept` / `textus reject` no longer claim "only human role can
+  accept" when the manifest declares zero `accept_authority` roles — the
+  error now says "no role with accept_authority kind is declared in this
+  manifest; accept/reject is disabled".
+- `textus build` now resolves the build role from the manifest's declared
+  `generator` kind instead of hardcoding `"builder"`, so renamed generator
+  roles work correctly.
+- Manifest validator's "exactly one accept_authority" error message now
+  matches what the schema actually enforces.
+
+### Removed
+- Legacy `human_accept` promotion-predicate alias (string and symbol forms).
+  Manifests using `rules[].promotion.requires: [human_accept]` must change
+  to `[accept_authority_signed]`. The error on the old form is actionable:
+  `unknown promotion predicate: 'human_accept' (known: schema_valid,
+  accept_authority_signed)`.
+- `textus key normalize` verb and the underlying
+  `Textus::Application::Tools::MigrateKeys` module. Files dropped into nested
+  zones with illegal basenames are still reported by `textus doctor` with a
+  `key.illegal` finding; fix them by hand. The `--upgrade-manifest` flag and
+  its `Textus::Application::Tools::MigrateManifestToKinds` module (one-shot
+  0.19→0.20 manifest upgrader) are removed for the same reason — dead weight.
+- The `migrate-keys` audit-log payload string is no longer emitted (no writer
+  produces it).
+
+### Internal
+- Final cleanup of role-name leaks identified by the 0.20.2 architecture
+  audit (follow-on to 0.20.1 role-kinds refactor).
+
+## 0.20.1 — 2026-05-27
+
+### Added
+- Optional `roles:` block in `manifest.yaml` lets users rename roles without
+  breaking engine semantics. Each declared role maps to one of four engine
+  kinds: `accept_authority`, `generator`, `proposer`, `runner`. (#72)
+- `Manifest#role_kind`, `Manifest#roles_with_kind`, `Manifest#zone_kinds`
+  accessors for engine integrations.
+
+### Changed
+- `accept` / `reject` now gate on `accept_authority` kind, not the literal
+  `"human"` role. Error messages cite the configured role name.
+- `validator` last-writer trust check uses `accept_authority` kind.
+- Entry `in_generator_zone?` / `in_proposal_zone?` query `zone_kinds`.
+- `Intro` derives `write_flows` and `agent_protocol.role_resolution.roles`
+  from the manifest's role mapping.
+- Promote DSL predicate `:human_accept` renamed to `:accept_authority_signed`;
+  the old symbol still works as an alias.
+- Schema rejects zone writers that reference an undeclared role when `roles:`
+  is declared.
+
+### Compatibility
+- No wire protocol change (`textus/3`).
+- Existing manifests without a `roles:` block behave identically to 0.20.0.
+
+## 0.20.0 — architecture redesign (2026-05-27)
+
+**BREAKING (pre-1.0):** Public top-level utility modules removed,
+`Manifest` routing methods extracted into a dedicated resolver,
+`Hooks::Dispatcher`/`Hooks::Registry` collapsed into a single bus, and
+pubsub hook payloads now ship `ctx:` (a `Textus::Hooks::Context`)
+instead of the raw store. External hook files written against the 0.19
+`register(event, name, ...)` API continue to work unchanged; pubsub
+hook bodies must update signatures from `|store:, ...|` to `|ctx:, ...|`
+and use `ctx.put`/`ctx.get`/`ctx.audit`/`ctx.publish_followup` in place
+of direct `store.*` access. RPC events (`transform_rows`, `resolve_intake`,
+`validate`) keep `store:`.
+
+### Added
+- `Textus::Hooks::Context` — narrow handle for user pubsub hooks. Exposes
+  `role`, `correlation_id`, `get`, `list`, `deps`, `freshness`, `put`,
+  `delete`, `audit`, and `publish_followup`. All writes route back through
+  `Operations` so authorization, audit, and validation cannot be bypassed.
+
+### Removed
+- `Textus::Dependencies` — use `Operations#deps`, `#rdeps`, `#published`.
+- `Textus::Refresh` — use `Operations#refresh`. The `normalize_action_result`
+  helper is now a private class method on `Application::Refresh::Worker`.
+- `Textus::Hooks::Dispatcher` and `Textus::Hooks::Registry` classes.
+
+### Changed
+- `Textus::Projection` moved to `Textus::Application::Projection`.
+- `Textus::MigrateKeys` moved to `Textus::Application::Tools::MigrateKeys`.
+- `Manifest#resolve`, `#enumerate`, and `#suggestions_for` removed from
+  the public `Manifest` API. Use `manifest.resolver.resolve(key)` etc.
+  via the new `Manifest::Resolver`. `Manifest` retains the data accessors
+  (`entries`, `zones`, `rules`, `permissions`, `validate_key!`).
+- `Store` constructs one `Hooks::Bus`; `Store#registry` removed (use
+  `Store#bus`). `Hooks::Builtin.register_all(bus)` and
+  `Hooks::Loader.new(bus:)` now take a Bus instead of a Registry.
+  `Operations.for` no longer accepts `registry:`. Use cases
+  (`Refresh::Worker`, `Refresh::All`) take `bus:`.
+- All pubsub events declare `ctx:` instead of `store:` in their kwargs
+  schema. Every `bus.publish` call site passes `ctx: hook_context`.
+  `Operations#hook_context` builds the per-`Operations` `Hooks::Context`.
+- Manifest entries gain a required `kind:` field
+  (`leaf | nested | derived | intake`). Run
+  `textus key normalize --upgrade-manifest` to add it to existing
+  manifests — the inference is deterministic and lossless.
+- Internal: `Manifest::Entry` is now an abstract namespace; concrete
+  classes are `Entry::Leaf`, `Entry::Nested`, `Entry::Derived`,
+  `Entry::Intake`. The fields `projection`, `generator`, `compute`,
+  `intake_handler`, `intake_config` are removed from the entry
+  interface; `Entry::Derived` carries a typed `source`
+  (`Projection` or `External`) and `Entry::Intake` carries `handler`
+  / `config`. Use-case code dispatches on entry type rather than
+  probing optional fields.
+- `Application::Writes::Build` removed. `Application::Writes::Publish` now
+  materializes derived entries (template + projection + external runner)
+  AND copies leaf/nested entries to their publish targets in a single pass.
+  `Operations#build` is gone; use `Operations#publish` — the `textus build`
+  CLI verb is unchanged and produces the same
+  `{protocol, built, published_leaves}` JSON shape.
+
+## 0.19.1 — drop textus/2 migration hint (2026-05-27)
+
+**BREAKING (pre-1.0):** Users on gem ≤0.10 (manifest protocol `textus/2`)
+no longer receive a stepping-stone hint pointing at 0.11.x. The manifest
+parser and `textus doctor` now emit the generic "unsupported version"
+error. Users on ≤0.10 should install 0.11.x first (still on RubyGems)
+to run the migrator, then upgrade to 0.19.1+.
+
+### Changed
+- `Textus::Manifest` no longer special-cases `textus/2`; `TEXTUS_2_HINT`
+  and `version_hint_for` removed.
+- `Doctor::Check::ProtocolVersion` hint/fix text simplified; no longer
+  links to the 0.11.x CHANGELOG anchor.
+
+### Removed
+- Two redundant manifest specs (the `Manifest.load` duplicate and the
+  `textus/2`-specific hint assertion) collapsed into one generic case.
+
+## 0.19.0 — 2026-05-27
+
+### Breaking
+
+- `Application::Context` is now a slim value object (`role`,
+  `correlation_id`, `now`, `dry_run`). Migration table:
+
+  | Was | Now |
+  |-----|-----|
+  | `Application::Context.new(store:, role:)` | `Operations.for(store, role:)` (common case) or `Application::Context.build(role:)` (pure call state) |
+  | `Application::Context.system(store)` | Pass `store` directly to hooks |
+  | `ctx.store` / `ctx.manifest` / `ctx.file_store` etc. | Construct use cases with the explicit port kwargs |
+  | `ctx.authorize_write!(mentry)` | `Domain::Authorizer.new(manifest:).authorize_write!(mentry, role:)` |
+  | `Put.new(ctx:).call(..., suppress_events: true)` | Use `EnvelopeIO#write` directly |
+  | `store.role` inside a hook | Read `role:` from the event payload |
+
+- `Operations.new(ctx:, manifest:, file_store:, schemas:, audit_log:, bus:, registry:, root:, store:)`
+  is the primary constructor. `Operations.for(store, role:)` remains
+  a convenience.
+
+- `Application::Writes::Put#call` no longer accepts `suppress_events:`.
+
+- `Domain::Policy::Predicates::*` moved to `Application::Policy::Predicates::*`.
+  `Domain::Policy::Promotion` moved to `Application::Policy::Promotion`.
+  `Promotion#evaluate` now takes `entry:, schemas:, manifest:, role:`
+  instead of `store:`.
+
+- Hooks/intakes/transforms receive the actual `Store` as `store:`
+  (previously a Context impersonating one). Event payloads
+  (`:entry_put`, `:entry_deleted`, `:entry_renamed`, `:proposal_accepted`,
+  `:proposal_rejected`, `:entry_refreshed`, `:refresh_started`,
+  `:refresh_failed`, `:refresh_backgrounded`, `:file_published`,
+  `:build_completed`) now carry `role:` directly so hooks can observe
+  the actor without reaching through the `store:` handle.
+
+- `Application::Refresh::All` is a class, not a module function. Callers
+  go through `Operations#refresh_all`.
+
+### Added
+
+- `Domain::Authorizer` — single source of truth for permission checks.
+- `Application::Policy::Promotion` and `Application::Policy::Predicates::*` —
+  the policy evaluator and predicates now live with the Application code
+  that loads envelope bytes off disk to evaluate them.
+- `Application::Writes::EnvelopeIO#move` — full move pipeline (replaces
+  the in-`Mv` file move + audit).
+- `Application::Writes::EnvelopeIO#read_envelope(key)` — internal
+  convenience for callers that need to inspect a pre-move envelope.
+
+### Internal
+
+- `Builder::Pipeline` no longer re-enters `Operations.for(store)`; it
+  takes reader/lister callables from the caller.
+- CLI verbs construct `Operations`, never `Context` directly.
+- `Operations` no longer memoizes per-use-case factories; only
+  `envelope_io`, `refresh_worker`, and `orchestrator` are shared.
+- Wire format `textus/3` unchanged. Audit-log NDJSON unchanged.
+
+### Known follow-ups
+
+- CLI verbs `hook run`, `put --fetch`, `hooks list`, and `rule list`
+  still reach into `store.manifest` / `store.registry` directly. A
+  future release adds `Operations` projections (e.g. `manifest_view`,
+  `hooks_view`, `run_intake`) so these verbs route through the
+  Operations boundary.
+- `Application::Writes::Delete#call` retains a `suppress_events:` kwarg
+  (used internally by `Reject`). A future release either lifts the
+  suppression into `EnvelopeIO`-direct usage (matching the `Mv` path)
+  or formalizes per-event suppression as part of the public hook API.
+
+## 0.18.1 — 2026-05-27
+
+### Fixed
+
+- `Hooks::Dispatcher` no longer uses `Timeout.timeout`, which can interrupt a
+  hook mid-syscall or mid-`ensure` and leave Ruby state corrupted. Each
+  subscriber now runs in a worker thread joined with a deadline; on overrun
+  the thread is killed and the hook is recorded as `timed_out` (distinct
+  from `errored`).
+
+### Added
+
+- `Hooks::FireReport` — value object returned from `bus.publish`. Lists
+  `fired`, `errored`, and `timed_out` subscriber names; exposes `#ok?` and
+  `#failures`. Backwards-compatible: callers that ignore the return value
+  (the entire current codebase) keep working.
+- `Hooks::Dispatcher#publish` accepts `strict: true`, which re-raises the
+  first failure after every subscriber has been attempted. Intended for
+  test setups that want loud hooks; default remains `false`.
+
+### Internal
+
+- No public API surface changes. CLI behavior, `Operations` methods, wire
+  format `textus/3`, and the audit-log NDJSON shape are unchanged. Stores
+  written by 0.18.0 round-trip through 0.18.1 byte-for-byte.
+
 ## 0.18.0 — 2026-05-27
 
 Port extraction finishes the hexagonal trajectory. `Store::Reader` and

data/SPEC.md

@@ -229,6 +229,40 @@ Unknown role values are rejected with `invalid_role`.
 
 Every successful write records the resolved role and a wall-clock timestamp in `.textus/audit.log`, so reviewers can later distinguish a human edit from an agent edit even though both live in the same file.
 
+#### 5.1.1 Role kinds (engine semantics)
+
+Internally the engine recognizes four **role kinds** — abstract capability
+markers — rather than the four default role names. A manifest may declare a
+`roles:` block to map any role name to a kind:
+
+```yaml
+roles:
+  - { name: owner,    kind: accept_authority }
+  - { name: compiler, kind: generator }
+  - { name: proposer, kind: proposer }
+  - { name: fetcher,  kind: runner }
+```
+
+Kind allow-list: `accept_authority`, `generator`, `proposer`, `runner`.
+At most one role may have `accept_authority`. When `roles:` is declared,
+every entry in `zones[*].write_policy` must be a declared role name.
+
+When the `roles:` block is omitted, the default mapping applies:
+
+| Default name | Kind |
+|---|---|
+| `human`   | `accept_authority` |
+| `agent`   | `proposer` |
+| `builder` | `generator` |
+| `runner`  | `runner` |
+
+This means existing manifests continue to work byte-for-byte. Wire protocol
+`textus/3` is unchanged — kinds are an internal-semantics concept and never
+appear on the wire.
+
+The promotion DSL predicate `:human_accept` is now `:accept_authority_signed`;
+the old symbol works as an alias for backwards compatibility.
+
 ### 5.2 Compute layer (derived entries)
 
 Derived entries live in a zone whose `write_policy:` list includes `builder` — `output` in the default scaffold. They are not authored by hand; their body is produced by projecting over other entries. A derived entry declares a `compute:` block with a `kind:` discriminator.
@@ -399,7 +433,7 @@ Schema (one JSON object per line, no interior whitespace):
 {"ts":"<iso8601-utc>","role":"<role>","verb":"<verb>","key":"<key>","etag_before":<etag-or-null>,"etag_after":<etag-or-null>}
 ```
 
-`ts` is the wall-clock timestamp in UTC with second precision. `role` is the resolved role for the invocation. `verb` is the audit-log payload string identifying the operation (`put`, `delete`, `accept`, `compute`, `migrate-keys`, `mv`, ...). Note that `migrate-keys` here is the on-disk payload key — the CLI surface is `textus key migrate`; the payload string is retained for log stability. `key` is the affected entry key. `etag_before` and `etag_after` are the entry etags before and after the write, or JSON `null` when not applicable (e.g. create has no before-etag, delete has no after-etag). `key migrate --write` emits one line per renamed file (with payload `verb: "migrate-keys"`) using the new key as `key` and the file's pre- and post-rename etags.
+`ts` is the wall-clock timestamp in UTC with second precision. `role` is the resolved role for the invocation. `verb` is the audit-log payload string identifying the operation (`put`, `delete`, `accept`, `compute`, `mv`, ...). `key` is the affected entry key. `etag_before` and `etag_after` are the entry etags before and after the write, or JSON `null` when not applicable (e.g. create has no before-etag, delete has no after-etag).
 
 For `mv`, the structural fields `from_key`, `to_key`, and `uid` appear at the top level of the JSON object. Remaining verb-specific data (e.g. `from_path`, `to_path`) is nested under an `extras` key. The `extras` key is omitted entirely when empty.
 
@@ -705,7 +739,6 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 | `init` | write | `human` |
 | `schema {show,init,diff,migrate}` | read/write | `human` for writes |
 | `key mv OLD NEW [--as=R] [--dry-run]` | write | per zone (same-zone only) |
-| `key normalize [--dry-run\|--write]` | write (with `--write`) | `human` |
 | `key uid K` | read | any |
 
 **`put` input** (read from stdin when `--stdin` is given):

data/lib/textus/application/context.rb

@@ -2,69 +2,31 @@ require "securerandom"
 
 module Textus
   module Application
-    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
-        @correlation_id    = correlation_id || SecureRandom.uuid
-        @clock             = clock
-        @dry_run           = dry_run
-        @now               = nil
-      end
-
-      def now
-        @now ||= @clock.now
-      end
-
-      def dry_run?
-        @dry_run
-      end
-
-      def can_write?(zone)
-        store.manifest.permission_for(zone.to_s).allows_write?(role)
-      end
-
-      def can_read?(zone)
-        store.manifest.permission_for(zone.to_s).allows_read?(role)
-      end
-
-      def bus
-        @store.bus
-      end
-
-      def manifest   = @store.manifest
-      def schemas    = @store.schemas
-      def file_store = @store.file_store
-      def audit_log  = @store.audit_log
-
-      def authorize_write!(mentry)
-        return if can_write?(mentry.zone)
-
-        writers = @store.manifest.zone_writers(mentry.zone)
-        raise WriteForbidden.new(mentry.key, mentry.zone, writers: writers)
+    # A Context describes the call: who is acting (role), what request this
+    # is part of (correlation_id), what time it is (now), and whether
+    # writes should be suppressed (dry_run).
+    #
+    # Collaborators (manifest, file_store, bus, audit log, authorizer) are
+    # never read from Context — use cases declare them as explicit
+    # constructor ports, and Operations wires them in from the Store.
+    Context = Data.define(:role, :correlation_id, :now, :dry_run) do
+      def self.build(role:, correlation_id: nil, now: nil, dry_run: false)
+        new(
+          role: role.to_s,
+          correlation_id: correlation_id || SecureRandom.uuid,
+          now: now || Time.now,
+          dry_run: dry_run,
+        )
       end
 
-      def authorize_read!(mentry)
-        return if can_read?(mentry.zone)
-
-        readers = @store.manifest.zone_readers[mentry.zone]
-        readers = nil if readers == :all
-        raise ReadForbidden.new(mentry.key, mentry.zone, readers: readers)
-      end
+      def dry_run? = dry_run
 
       def with_role(new_role)
         self.class.new(
-          store: @store,
-          role: new_role,
-          correlation_id: @correlation_id,
-          clock: @clock,
-          dry_run: @dry_run,
+          role: new_role.to_s,
+          correlation_id: correlation_id,
+          now: now,
+          dry_run: dry_run,
         )
       end
     end

data/lib/textus/application/policy/predicates/accept_authority_signed.rb

@@ -0,0 +1,33 @@
+module Textus
+  module Application
+    module Policy
+      module Predicates
+        # Promotion predicate: the role driving the promotion must have
+        # role_kind == :accept_authority in the active manifest.
+        #
+        # Accept/Reject already gate on this kind before reaching the
+        # promotion policy, so in the default control-flow this predicate
+        # trivially passes. It is kept so manifests can express the
+        # requirement explicitly in `rules[].promotion.requires`.
+        class AcceptAuthoritySigned
+          attr_reader :reason
+
+          def name
+            "accept_authority_signed"
+          end
+
+          def call(role:, manifest:, entry: nil) # rubocop:disable Lint/UnusedMethodArgument
+            role_str = role&.to_s
+            return true if role_str.nil? || role_str.empty?
+
+            kind = manifest.role_kind(role_str)
+            return true if kind == :accept_authority
+
+            @reason = "role '#{role_str}' has kind '#{kind.inspect}', expected ':accept_authority'"
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/{domain → application}/policy/predicates/schema_valid.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Domain
+  module Application
     module Policy
       module Predicates
         class SchemaValid
@@ -9,17 +9,17 @@ module Textus
             "schema_valid"
           end
 
-          def call(entry:, store:) # rubocop:disable Metrics/PerceivedComplexity
-            return true if entry.nil? || store.nil?
+          def call(entry:, schemas:, manifest:) # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
+            return true if entry.nil? || manifest.nil? || schemas.nil?
 
             target_key = entry.meta&.dig("proposal", "target_key")
             return true unless target_key
 
-            mentry = store.manifest.resolve(target_key).entry
+            mentry = manifest.resolver.resolve(target_key).entry
             schema_ref = mentry&.schema
             return true unless schema_ref
 
-            schema = store.schemas.fetch_or_nil(schema_ref)
+            schema = schemas.fetch_or_nil(schema_ref)
             return true unless schema
 
             frontmatter = entry.meta&.dig("frontmatter") || {}