textus 0.20.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 613e04300389a5f5bf058f4e75c15b5ff19f813fb7ef6102ba38ce53ecd43043
-  data.tar.gz: 97d121b40ac753af1e04893429db1abfe4044f791fff5ea02de33910a4cfa00c
+  metadata.gz: 38a9a929bb63f94d5a3cdc4708f09ce5c8e0eca28928d5733b8d842d90ece8b8
+  data.tar.gz: 26a8aeb22666788cd30e949eb25c7336db1de9ef7f4110aaf700f7abecdec644
 SHA512:
-  metadata.gz: 13d11e92b35b952fc9974293544ab49d50dc6055f7ee80771b33a82f511ba534f6cf3fa8c26a84e886778f6b5ee662a3a540d36c7072c23f2b366540a365e066
-  data.tar.gz: 7cbf43d42e37271b73122d5db10a463a1936c39696cc6a5e7eee56646ccdb1c503a645e63b3b40e09bfc911ae531e2258b02d4e715458bcd54a193d9e7ca5b0d
+  metadata.gz: 9b4ce0da2828f2623f60601cdd0ac8a69e51cc9670c5de80b92e3b41e0f955361154664b8cb0a7de0e838b5403336ff26589698201885b44001a83cfcd2c3f21
+  data.tar.gz: 672d948ab0ccdea1470dcb38c87c233ed717a538d4e4902191a32224dac8475fe1269b4569be00e5eb1f40e9c6146f8867d557d6455601c13fc2e0ce2c381cae

data/CHANGELOG.md

@@ -9,6 +9,163 @@ 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.22.0 — 2026-05-28
+
+### Changed (internal — no manifest-schema impact)
+- **Entry polymorphism pass.** Behavior-preserving refactor that
+  consolidates cross-cutting fields on `Manifest::Entry::Base` and
+  replaces case-statement dispatch with polymorphic methods. Adding
+  a new entry kind now costs ~1 file edit instead of ~5–10.
+  - `publish_to` is now owned by `Base` (was declared four separate
+    times across Leaf/Derived/Nested/Intake).
+  - `Base` exposes nil-returning stubs for `template`, `inject_boot`,
+    `events`, `publish_each`, `index_filename` — validators and
+    serializers no longer need `respond_to?` guards.
+  - `Publish#call` dispatches via `entry.publish_via(context)` instead
+    of a 4-branch case-statement. The byte-identical
+    `publish_leaf_entry` / `publish_intake_entry` helpers are gone.
+  - Each `Entry` subclass declares a `KIND` constant and a
+    `self.from_raw(common, raw)` factory; `Parser` dispatches via
+    `Entry::REGISTRY` instead of a closed `case kind`.
+  - Dead `Base#kind` method removed.
+
+No public API or manifest YAML changes. All existing manifests load
+identically.
+
+Remaining `is_a?(Entry::Derived)` callsites in `builder/`, `renderer/`,
+`application/reads/`, and `domain/staleness/` are out of scope for this
+pass — they touch a different polymorphism axis (what data the entry
+contributes to a build) and will be addressed in a follow-up.
+
+Known follow-up: `Intake#nested?` still reads `@raw["nested"]` to
+preserve the `kind: intake, nested: true` YAML overlay used by nested
+intake handlers. This dual discriminator (`kind:` + `nested:`) is a
+design tension worth revisiting alongside the broader is_a? cleanup.
+
+## 0.21.1 — 2026-05-27
+
+### Fixed
+- **Intake entries can now act as builder outputs.** Two related gaps closed:
+  - `FormatMatrix` validator no longer rejects `kind: intake` entries in
+    generator zones for missing a template. Intake bodies come from a
+    `:resolve_intake` handler, so the "derived format requires template"
+    rule never applied. (Error message widened from "derived #{format}"
+    to "#{format} entries in a generator zone require a template".)
+  - `Manifest::Entry::Intake` now parses `publish_to:` from YAML (was
+    hardcoded to `[]`).
+  - `textus publish` / `textus build` now fan out intake bodies to each
+    `publish_to` target, mirroring the Leaf fan-out path. Refresh-time
+    fan-out is unchanged — bodies still publish on the next publish/build
+    run.
+
+  Closes #80. Lets consumers replace `kind: derived, compute: { kind:
+  external }` runner glue with `kind: intake` + `Textus.on(:resolve_intake)`
+  hooks for builder-produced outputs.
+
+## 0.21.0 — 2026-05-27
+
+### BREAKING
+- `textus intro` is removed. Use `textus boot` instead — same envelope, same
+  use case, better name (pairs with the new `pulse` verb to form the agent
+  lifecycle: `boot` for static contract, `pulse` for dynamic state).
+- The `Textus::Intro` module is now `Textus::Boot`. The manifest entry field
+  `inject_intro:` is now `inject_boot:`. Builder template variable
+  `{{intro.*}}` is now `{{boot.*}}`. Pre-1.0; no compatibility alias.
+
+### Added
+- **`textus pulse [--since=N]`** — agent heartbeat verb. Returns an envelope
+  with `cursor` (current `latest_seq`), `changed` (audit rows since N),
+  `stale` (entries past refresh policy), `pending_review` (keys in review
+  zone), and `doctor` (ok/warn/fail counts). One round-trip replaces what
+  was previously four separate verbs.
+- **`agent_quickstart` block in `textus boot`** — names the read verbs,
+  write verbs, writable zones, default propose zone, and current
+  `latest_seq` (the starting cursor for `pulse`). Lets an agent boot once
+  and immediately know how to talk and where to start polling.
+- **Audit log rotation.** Active `audit.log` rotates to `audit.log.1` when
+  it exceeds `audit.max_size` (default 10MB), keeping the last
+  `audit.keep` files (default 5). Each rotated file has a sidecar
+  `audit.log.N.meta.json` with `min_seq`/`max_seq`/`rotated_at`. Configure
+  via the new top-level `audit:` block in `manifest.yaml`.
+- **Monotonic `seq` on every audit row.** Foundation for cursor-based
+  queries; `audit --seq-since=N` and `pulse --since=N` both use it.
+- **`Textus::CursorExpired`** error class, raised by `pulse` and
+  `audit --seq-since` when the requested seq has rotated off disk. The
+  message names the oldest still-available seq and tells the agent to
+  re-orient via `textus boot`.
+- `docs/agent-integration.md` — boot → pulse → work loop reference, with
+  an example agent loop and cursor-expiry handling.
+
+### Changed
+- Audit rows now include a `seq` integer field (existing fields unchanged).
+- `textus boot` envelope gains `agent_quickstart` (additive — existing
+  consumers unaffected).
+
+## 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,

data/README.md

@@ -5,7 +5,7 @@
 [![Ruby](https://img.shields.io/badge/ruby-%E2%89%A53.3-CC342D.svg)](https://www.ruby-lang.org/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-A context store for codebases that humans and AI agents both have to read and write. Dotted keys, schema-validated entries, role-gated writes, byte-copy publish, an audit log of every change. Built so an agent landing in your repo can run one command (`textus intro`) and know what to read, what to write, and what's off-limits.
+A context store for codebases that humans and AI agents both have to read and write. Dotted keys, schema-validated entries, role-gated writes, byte-copy publish, an audit log of every change. Built so an agent landing in your repo can run one command (`textus boot`) and know what to read, what to write, and what's off-limits.
 
 Reference implementation in Ruby. Wire format `textus/3`. SPEC: [`SPEC.md`](SPEC.md). Implementation notes: [`docs/`](docs/).
 
@@ -83,7 +83,8 @@ For the full shape — Claude plugin with agents, skills, commands, pending walk
 - **Typed envelopes (v0.14.0).** `Textus::Envelope` is a `Data.define` value object with typed accessors (`.meta`, `.body`, `.etag`, `.uid`, `.freshness`, …). Ruby API callers get IDE help and `NoMethodError` on typos. The CLI JSON wire format is preserved byte-for-byte via `envelope.to_h_for_wire`.
 - **Stable identity (`uid:`).** 16-char hex, auto-minted on first `put`, preserved across writes and moves. `textus key mv old.key new.key` renames in place — uid survives, audit row records `from_key`, `to_key`, `uid`. Reorganising a tree no longer breaks references.
 - **Strict key grammar.** `/^[a-z0-9][a-z0-9-]*$/`, max 8 segments × 64 chars. `textus key normalize --dry-run|--write` rewrites existing stores with illegal segments deterministically.
-- **`textus intro`.** One-shot store orientation: zones with writers + purposes, entry families with schemas and publish targets, loaded hooks, write flows per role, the full CLI verb table. The boot signal for any agent — one tool call and it knows your store.
+- **`textus boot`.** One-shot store orientation: zones with writers + purposes, entry families with schemas and publish targets, loaded hooks, write flows per role, the full CLI verb table, and an `agent_quickstart` block (read/write verbs, writable zones, propose zone, latest audit seq). The boot signal for any agent — one tool call and it knows your store.
+- **`textus pulse [--since=N]`.** Per-turn heartbeat for agents: changed entries since cursor N, stale keys, pending review proposals, and a doctor summary. Cursor is a monotonic seq stamped on every audit row; rotation keeps the last 5 files (configurable via `audit:` in the manifest) and raises `CursorExpired` when the requested cursor has fallen off disk.
 - **`textus doctor`.** Health check across 9 categories: missing schemas/templates, broken hooks, illegal nested keys, sentinel drift, audit log readability, unowned schema fields, schema violations, and missing manifest files. Returns `ok: true` only when nothing is wrong; warnings and info don't flip the bit.
 - **Actionable hints on every error.** `UnknownKey` carries ranked "did you mean" suggestions. `WriteForbidden` names the role that *would* be allowed. `BadFrontmatter` tells you exactly what to rename. Printed to stderr alongside the JSON envelope on stdout.
 - **Compute.** Derived entries declare `compute: { kind: projection, ... }` (declarative rows + template) or `compute: { kind: external, ... }` (build runner produces the file; textus tracks sources for staleness). Inside projection computes, `transform:` names the row-shaping hook.
@@ -97,7 +98,7 @@ All verbs accept `--output=json` and return the envelope defined in [SPEC §8](S
 - Full verb table — read, write, health, scaffolding — is in [SPEC §9](SPEC.md).
 - Zone semantics and the role/`write_policy` mapping live in [SPEC §5](SPEC.md), with a tutorial expansion in [`docs/zones.md`](docs/zones.md).
 
-`textus intro` prints the same information for the current store: zones, entry families with schemas, registered hooks, write flows, and the verb catalog. Run it inside a store and you get the live picture; reach for the SPEC when you want the contract.
+`textus boot` prints the same information for the current store: zones, entry families with schemas, registered hooks, write flows, and the verb catalog. Run it inside a store and you get the live picture; reach for the SPEC when you want the contract.
 
 ## Compute and publish
 
@@ -150,9 +151,11 @@ See SPEC.md §5.10 for the full hook contract.
 
 Schemas (`.textus/schemas/<name>.yaml`) declare field shapes, per-field `maintained_by:` ownership, and an `evolution:` block (`added_in`, `deprecated_at`, `migrate_from`). Full contract in SPEC §5.8.
 
+See [`docs/agent-integration.md`](docs/agent-integration.md) for the agent boot → pulse loop.
+
 ## Examples
 
-[`examples/claude-plugin/`](examples/claude-plugin/) — a Claude Code plugin (`voice-tools`) whose entire content surface — agents, skills, commands, `CLAUDE.md`, `plugin.json`, `marketplace.json` — is textus-managed. Demonstrates per-entry formats, `publish_each`, intake actions, in-process transforms and hooks, the agent-propose / human-accept loop, and the `inject_intro:` flag that puts an orientation preamble at the top of `CLAUDE.md`.
+[`examples/claude-plugin/`](examples/claude-plugin/) — a Claude Code plugin (`voice-tools`) whose entire content surface — agents, skills, commands, `CLAUDE.md`, `plugin.json`, `marketplace.json` — is textus-managed. Demonstrates per-entry formats, `publish_each`, intake actions, in-process transforms and hooks, the agent-propose / human-accept loop, and the `inject_boot:` flag that puts an orientation preamble at the top of `CLAUDE.md`.
 
 ## Tests
 

data/SPEC.md

@@ -189,7 +189,7 @@ Validation at manifest load: any unknown variable raises `UsageError`; the templ
 
 A leaf at `working.skills.writing.voice-writer` (authored at `.textus/zones/working/skills/writing/voice-writer.md`) publishes to `skills/voice-writer/SKILL.md`.
 
-**`inject_intro:`.** A derived entry with a `template:` MAY declare `inject_intro: true`. When the builder materializes the entry, it merges the `textus intro` envelope (§9) into the projection data under the key `intro`, so the template can render orientation content (zones, write flows, CLI catalog) alongside its projected rows. The flag is rejected at manifest load on (a) non-derived entries or (b) derived entries without a `template:` — agents reading the rendered file should be able to trust the preamble was produced by the same source of truth `textus intro` exposes.
+**`inject_boot:`.** A derived entry with a `template:` MAY declare `inject_boot: true`. When the builder materializes the entry, it merges the `textus boot` envelope (§9) into the projection data under the key `boot`, so the template can render orientation content (zones, write flows, CLI catalog) alongside its projected rows. The flag is rejected at manifest load on (a) non-derived entries or (b) derived entries without a `template:` — agents reading the rendered file should be able to trust the preamble was produced by the same source of truth `textus boot` exposes.
 
 **Lookup rule:** to resolve a key, find the entry with the longest `key:` prefix that matches. If that entry has `nested: true`, the remaining segments map to subdirectories under its `path`. Otherwise the key must equal an entry exactly. The resolved filesystem path is `<.textus root>/zones/<entry.path>[/<remaining>...].md` — implementations MUST prepend `zones/` to the manifest `path:` when constructing the filesystem location.
 
@@ -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.
@@ -396,10 +430,12 @@ Every successful write appends one compact JSON object (NDJSON) to `.textus/audi
 Schema (one JSON object per line, no interior whitespace):
 
 ```json
-{"ts":"<iso8601-utc>","role":"<role>","verb":"<verb>","key":"<key>","etag_before":<etag-or-null>,"etag_after":<etag-or-null>}
+{"seq":<integer>,"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.
+`seq` is a monotonic integer counter, auto-incremented on each append. It is the foundation for cursor-based queries: `textus audit --seq-since=N` returns only rows with `seq > N`, and `textus pulse --since=N` builds its `changed` array from the same cursor. When an agent's cursor falls below the oldest available seq (due to log rotation), the operation raises `CursorExpired`.
+
+`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.
 
@@ -695,7 +731,8 @@ All verbs accept `--output=json` and emit a canonical envelope (success or error
 | `hook list` | read | any |
 | `hook run NAME` | write | any |
 | `doctor [--check=NAME[,NAME]] [--output=json]` | read | any |
-| `intro [--output=json]` | read | any |
+| `boot [--output=json]` | read | any |
+| `pulse [--since=N]` | read | any |
 | `put K --stdin --as=R [--fetch=NAME]` | write | per zone |
 | `delete K --if-etag=E --as=R` | write | per zone |
 | `refresh KEY --as=runner` | write | per zone (typically `runner`) |
@@ -705,9 +742,38 @@ 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 |
 
+**`textus boot` envelope extras.** In addition to zones, entries, hooks, write flows, and the `cli_verbs` catalog, the boot envelope includes an `agent_quickstart` block synthesized from the manifest's role-kind declarations:
+
+```json
+{
+  "agent_quickstart": {
+    "read_verbs":     ["boot", "get", "list", "audit", "pulse", "freshness", "doctor"],
+    "write_verbs":    ["put KEY --as=<proposer-role> --stdin"],
+    "writable_zones": ["review"],
+    "propose_zone":   "review",
+    "latest_seq":     1842
+  }
+}
+```
+
+`latest_seq` is the current high-water mark of the audit log; agents should use it as the starting cursor for `pulse`.
+
+**`textus pulse` output shape:**
+
+```json
+{
+  "cursor":         1845,
+  "changed":        [ { "seq": 1843, "key": "working.x", "verb": "put", "role": "human", "ts": "..." } ],
+  "stale":          [ "output.marketplace" ],
+  "pending_review": [ "review.proposal.123" ],
+  "doctor":         { "ok": true, "warn": 0, "fail": 0 }
+}
+```
+
+`cursor` is the new high-water mark; pass it as `--since` on the next call. `changed` is sourced from `audit --seq-since`. `stale` is sourced from `freshness`. `pending_review` lists all keys in the review zone. `doctor` is an `{ok, warn, fail}` count summary. When `--since` is below the oldest available seq (due to audit log rotation), pulse returns `CursorExpired`.
+
 **`put` input** (read from stdin when `--stdin` is given):
 
 ```json
@@ -765,6 +831,12 @@ Every `Textus::Error` exposes `code`, `message`, and an optional `hint:`. The hi
 
 The reference Ruby gem follows semver independently and speaks `textus/3`.
 
+## 11.1 Agent integration
+
+Agents interact with a textus store through two verbs: `boot` (once per session, for orientation) and `pulse` (per turn, for deltas). The `boot` envelope's `agent_quickstart` block gives the agent its starting cursor (`latest_seq`), its writable zones, and its propose zone. The `pulse` verb returns a delta envelope keyed on that cursor. When audit log rotation expires a cursor, `CursorExpired` signals the agent to call `boot` again.
+
+For the full boot → pulse loop with pseudocode and cursor-expiry handling, see [`docs/agent-integration.md`](docs/agent-integration.md).
+
 ## 12. Conformance fixtures
 
 A conformant implementation MUST pass these fixtures (the reference test suite ships a YAML file listing inputs and expected envelopes):

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/application/policy/promotion.rb

@@ -1,19 +1,15 @@
+require_relative "predicates/schema_valid"
+require_relative "predicates/accept_authority_signed"
+
 module Textus
   module Application
     module Policy
-      # Promotion evaluates a list of named predicates against a pending-proposal
-      # entry and returns a Result indicating whether all requirements are met.
-      #
-      # Lives in Application because the predicates it wires up read live state
-      # from explicit ports (schemas, manifest, role). The Domain-side rule
-      # statement ("this policy requires predicates X and Y") is captured by
-      # Textus::Domain::Policy::Promote.
       class Promotion
         Result = Struct.new(:ok?, :reasons, keyword_init: true)
 
         REGISTRY = {
           "schema_valid" => -> { Predicates::SchemaValid.new },
-          "human_accept" => -> { Predicates::HumanAccept.new },
+          "accept_authority_signed" => -> { Predicates::AcceptAuthoritySigned.new },
         }.freeze
 
         def self.from_names(names)
@@ -49,10 +45,9 @@ module Textus
 
         def invoke(pred, entry:, schemas:, manifest:, role:)
           case pred.name
-          when "human_accept"
-            pred.call(role: role, entry: entry)
+          when "accept_authority_signed"
+            pred.call(role: role, manifest: manifest, entry: entry)
           else
-            # Default shape: schema-style predicates that need entry + schemas + manifest.
             pred.call(entry: entry, schemas: schemas, manifest: manifest)
           end
         end

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

@@ -8,27 +8,36 @@ module Textus
       # correlation_id, limit. Reads the log file as JSON-Lines (legacy TSV
       # rows produce nil and are skipped).
       class Audit
-        def initialize(manifest:, root:)
-          @manifest = manifest
-          @log_path = File.join(root, "audit.log")
+        def initialize(manifest:, root:, audit_log: nil)
+          @manifest  = manifest
+          @root      = root
+          @log_path  = File.join(root, "audit.log")
+          @audit_log = audit_log
         end
 
         # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-        def call(key: nil, zone: nil, role: nil, verb: nil, since: nil, correlation_id: nil, limit: nil)
-          return [] unless File.exist?(@log_path)
+        def call(key: nil, zone: nil, role: nil, verb: nil, since: nil, seq_since: nil, correlation_id: nil, limit: nil)
+          check_cursor_expiry!(seq_since)
+
+          files = all_log_files
+          return [] if files.empty?
 
           rows = []
-          File.foreach(@log_path) do |line|
-            parsed = parse_row(line.chomp)
-            next unless parsed
-            next if key   && parsed["key"]  != key
-            next if role  && parsed["role"] != role
-            next if verb  && parsed["verb"] != verb
-            next if zone  && !key_in_zone?(parsed["key"], zone)
-            next if since && (parsed["ts"].nil? || Time.parse(parsed["ts"]) < since)
-            next if correlation_id && parsed.dig("extras", "correlation_id") != correlation_id
+          files.each do |file|
+            File.foreach(file) do |line|
+              parsed = parse_row(line.chomp)
+              next unless parsed
+              next if key && parsed["key"] != key
+              next if role && parsed["role"] != role
+              next if verb && parsed["verb"] != verb
+              next if zone && !key_in_zone?(parsed["key"], zone)
+              next if since && (parsed["ts"].nil? || Time.parse(parsed["ts"]) < since)
+              next if seq_since && (parsed["seq"].nil? || parsed["seq"] <= seq_since)
+              next if correlation_id && parsed.dig("extras", "correlation_id") != correlation_id
 
-            rows << parsed
+              rows << parsed
+              break if limit && rows.length >= limit
+            end
             break if limit && rows.length >= limit
           end
           rows
@@ -48,6 +57,22 @@ module Textus
 
         private
 
+        def check_cursor_expiry!(seq_since)
+          return unless seq_since
+
+          log = @audit_log || Textus::Infra::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(@root, "audit.log.*"))
+                       .reject { |p| p.end_with?(".meta.json") }
+                       .sort_by { |p| -p.scan(/\d+$/).first.to_i } # .5 .4 .3 .2 .1 → oldest first
+          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?("{")

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

@@ -0,0 +1,63 @@
+module Textus
+  module Application
+    module Reads
+      # Aggregator over audit + freshness + review + doctor. One round-trip
+      # for an agent's per-turn heartbeat. All component reads are existing
+      # APIs; pulse is sugar with a stable envelope shape and a monotonic
+      # cursor (seq).
+      class Pulse
+        def initialize(ctx:, manifest:, file_store:, audit_log:, root:, store:)
+          @ctx        = ctx
+          @manifest   = manifest
+          @file_store = file_store
+          @audit_log  = audit_log
+          @root       = root
+          @store      = store
+        end
+
+        def call(since: 0)
+          changed = audit_changes_since(since)
+          {
+            "cursor" => @audit_log.latest_seq,
+            "changed" => changed,
+            "stale" => stale_keys,
+            "pending_review" => review_keys,
+            "doctor" => doctor_summary,
+          }
+        end
+
+        private
+
+        def audit_changes_since(seq)
+          Reads::Audit.new(manifest: @manifest, root: @root, audit_log: @audit_log)
+                      .call(seq_since: seq)
+        end
+
+        def stale_keys
+          # Freshness rows use symbol keys: { key: "x.y", status: :stale, ... }
+          rows = Reads::Freshness.new(ctx: @ctx, manifest: @manifest, file_store: @file_store).call
+          rows.select { |r| r[:status] == :stale }.map { |r| r[:key] }
+        end
+
+        def review_keys
+          # List constructor takes only manifest:; returns hashes with string keys.
+          # Guard: zones is a Hash keyed by name string.
+          return [] unless @manifest.zones.key?("review")
+
+          rows = Reads::List.new(manifest: @manifest).call(zone: "review")
+          rows.map { |r| r.is_a?(Hash) ? (r["key"] || r[:key]) : r }
+        end
+
+        def doctor_summary
+          result  = Textus::Doctor.run(@store)
+          issues  = result["issues"] || []
+          {
+            "ok" => result["ok"],
+            "warn" => issues.count { |i| i["level"] == "warning" },
+            "fail" => issues.count { |i| i["level"] == "error" },
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -55,9 +55,11 @@ module Textus
           last_writer = @audit_log.last_writer_for(key)
           return if last_writer.nil?
 
+          last_writer_is_authority = @manifest.role_kind(last_writer) == :accept_authority
+
           env.meta.each_key do |field|
             owner = schema.maintained_by(field)
-            next if owner.nil? || last_writer == owner || last_writer == "human"
+            next if owner.nil? || last_writer == owner || last_writer_is_authority
 
             violations << { "key" => key, "code" => "role_authority",
                             "field" => field, "expected" => owner, "last_writer" => last_writer }

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

@@ -1,7 +1,11 @@
+require_relative "authority_gate"
+
 module Textus
   module Application
     module Writes
       class Accept
+        include AuthorityGate
+
         def initialize(ctx:, manifest:, file_store:, schemas:, envelope_io:, bus:, authorizer:, hook_context:) # rubocop:disable Metrics/ParameterLists
           @ctx          = ctx
           @manifest     = manifest
@@ -14,7 +18,7 @@ module Textus
         end
 
         def call(pending_key)
-          raise ProposalError.new("only human role can accept proposals; got '#{@ctx.role}'") unless @ctx.role == "human"
+          assert_accept_authority!("accept")
 
           env = Textus::Application::Reads::Get.new(
             ctx: @ctx, manifest: @manifest, file_store: @file_store,

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

@@ -0,0 +1,26 @@
+module Textus
+  module Application
+    module Writes
+      # Shared gate for write verbs that require the caller to hold the
+      # manifest's accept_authority role. Provides one method, expressed
+      # as two early-returns rather than a ternary, so each failure mode
+      # reads on its own line.
+      module AuthorityGate
+        def assert_accept_authority!(verb)
+          return if @manifest.role_kind(@ctx.role) == :accept_authority
+
+          authority = @manifest.roles_with_kind(:accept_authority).first
+          if authority.nil?
+            raise ProposalError.new(
+              "no role with accept_authority kind is declared in this manifest; #{verb} is disabled",
+            )
+          end
+
+          raise ProposalError.new(
+            "only #{authority} role can #{verb} proposals; got '#{@ctx.role}'",
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -32,7 +32,7 @@ module Textus
             transform_resolver: ->(name) { @bus.rpc_callable(:transform_rows, name) },
             template_loader: ->(name) { read_template(name) },
             transform_context: @store,
-            inject_intro: -> { Textus::Intro.run(@store) },
+            inject_boot: -> { Textus::Boot.run(@store) },
           )
         end