textus 0.20.0 → 0.20.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 613e04300389a5f5bf058f4e75c15b5ff19f813fb7ef6102ba38ce53ecd43043
-  data.tar.gz: 97d121b40ac753af1e04893429db1abfe4044f791fff5ea02de33910a4cfa00c
+  metadata.gz: 35d3b6540fc043048133df0874e76b36e522d844da783b69a5e8993418157ae4
+  data.tar.gz: e0293b87efb32c1edf2d6c0103dcd94289d91031a4be570f8fdd40fb681c1e79
 SHA512:
-  metadata.gz: 13d11e92b35b952fc9974293544ab49d50dc6055f7ee80771b33a82f511ba534f6cf3fa8c26a84e886778f6b5ee662a3a540d36c7072c23f2b366540a365e066
-  data.tar.gz: 7cbf43d42e37271b73122d5db10a463a1936c39696cc6a5e7eee56646ccdb1c503a645e63b3b40e09bfc911ae531e2258b02d4e715458bcd54a193d9e7ca5b0d
+  metadata.gz: '039b6f44941ea52ac8d956297d9619c4cc8b2346e7d8bced24bc5671506726a44348da66791aa6d032e56dd403353d1b34e9b2fee37eaec05cd6c83d5defc715'
+  data.tar.gz: e6e5e8f97f5f9a07a03813d61f9efa2088fb8f1338af89ba1298bf307c6c72e89f1028aa5a67ffdf8f97f2151c0af1273f82ff80751c59c11aa93ef2953323a9

data/CHANGELOG.md

@@ -9,6 +9,71 @@ 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,

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/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/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/publish.rb

@@ -58,7 +58,7 @@ module Textus
           ).run(mentry)
 
           publish_derived_copies(mentry, target_path, repo_root)
-          fire_build_completed(mentry, target_path)
+          fire_build_completed(mentry)
 
           { "key" => mentry.key, "path" => target_path, "published_to" => mentry.publish_to }
         end
@@ -76,7 +76,7 @@ module Textus
           end
         end
 
-        def fire_build_completed(mentry, target_path) # rubocop:disable Lint/UnusedMethodArgument
+        def fire_build_completed(mentry)
           envelope = reader.call(mentry.key)
           src = mentry.source
           selects = src.is_a?(Textus::Manifest::Entry::Derived::Projection) ? Array(src.select).compact : []

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

@@ -1,7 +1,11 @@
+require_relative "authority_gate"
+
 module Textus
   module Application
     module Writes
       class Reject
+        include AuthorityGate
+
         def initialize(ctx:, manifest:, file_store:, envelope_io:, bus:, authorizer:, hook_context:) # rubocop:disable Metrics/ParameterLists
           @ctx          = ctx
           @manifest     = manifest
@@ -13,7 +17,7 @@ module Textus
         end
 
         def call(pending_key)
-          raise ProposalError.new("only human role can reject proposals; got '#{@ctx.role}'") unless @ctx.role == "human"
+          assert_accept_authority!("reject")
 
           mentry = @manifest.resolver.resolve(pending_key).entry
           unless mentry.in_proposal_zone?

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

@@ -8,7 +8,8 @@ module Textus
 
         def call(store)
           Textus::Infra::BuildLock.with(root: store.root) do
-            ops = Textus::Operations.for(store, role: "builder")
+            role = store.manifest.roles_with_kind(:generator).first || "builder"
+            ops = Textus::Operations.for(store, role: role)
             result = ops.publish(prefix: prefix)
             emit(result)
           end

data/lib/textus/doctor/check/illegal_keys.rb

@@ -44,15 +44,14 @@ module Textus
         end
 
         def issue(abs_path, stem)
-          proposed = Textus::Application::Tools::MigrateKeys.normalize(stem)
           {
             "code" => "key.illegal",
             "level" => "error",
             "subject" => abs_path,
             "path" => abs_path,
-            "proposed_key" => proposed,
             "message" => "illegal key segment '#{stem}' at #{abs_path}",
-            "fix" => "run 'textus key normalize --dry-run' then '--write' to rename to '#{proposed}'",
+            "fix" => "rename the file/directory so each segment matches [a-z0-9][a-z0-9-]* " \
+                     "(lowercase, digits, hyphens)",
           }
         end
 

data/lib/textus/domain/policy/promote.rb

@@ -2,14 +2,16 @@ module Textus
   module Domain
     module Policy
       class Promote
-        KNOWN = %i[schema_valid human_accept].freeze
+        KNOWN = %i[schema_valid accept_authority_signed].freeze
         attr_reader :requires
 
         def initialize(requires:)
           syms = Array(requires).map { |r| r.to_s.to_sym }
           unknown = syms - KNOWN
           unless unknown.empty?
-            raise Textus::UsageError.new("unknown promote requirement: #{unknown.first.inspect} (known: #{KNOWN.join(", ")})")
+            raise Textus::UsageError.new(
+              "unknown promote requirement: #{unknown.first.inspect} (known: #{KNOWN.join(", ")})",
+            )
           end
 
           @requires = syms

data/lib/textus/domain/policy/refresh.rb

@@ -2,6 +2,8 @@ module Textus
   module Domain
     module Policy
       class Refresh
+        ALLOWED_ON_STALE = %i[warn sync timed_sync].freeze
+
         attr_reader :ttl, :on_stale, :sync_budget_ms, :fetch_timeout_seconds
 
         def initialize(ttl:, on_stale:, sync_budget_ms:, fetch_timeout_seconds: nil)

data/lib/textus/intro.rb

@@ -18,19 +18,37 @@ module Textus
       "output" => "build-computed outputs; never hand-edited",
     }.freeze
 
-    WRITE_FLOWS = {
-      "human" => "edit files in identity/working zones, then 'textus put KEY --as=human'",
-      "agent" => "propose changes by writing 'review.*' entries with --as=agent and a 'proposal:' frontmatter block; " \
-                 "a human runs 'textus accept' to apply",
-      "runner" => "refresh intake entries with 'textus refresh KEY --as=runner' (uses the entry's declared action)",
-      "builder" => "'textus build' computes output entries from projections; output files are never hand-edited",
+    # Per-kind write-flow templates. Each lambda receives the user-facing role
+    # name and returns a guidance string for that role. Roles whose kind has
+    # no template (e.g. unknown future kinds) are omitted from write_flows.
+    WRITE_FLOW_TEMPLATES = {
+      accept_authority: lambda do |name, _manifest|
+        "edit files in identity/working zones, then 'textus put KEY --as=#{name}'"
+      end,
+      proposer: lambda do |name, manifest|
+        authority = manifest.roles_with_kind(:accept_authority).first || "accept_authority"
+        "propose changes by writing review.* entries with --as=#{name} and a 'proposal:' frontmatter block; " \
+          "the #{authority} role runs 'textus accept' to apply"
+      end,
+      runner: lambda do |name, _manifest|
+        "refresh intake entries with 'textus refresh KEY --as=#{name}' (uses the entry's declared action)"
+      end,
+      generator: lambda do |_name, _manifest|
+        "'textus build' computes output entries from projections; output files are never hand-edited"
+      end,
     }.freeze
 
-    # Static, store-independent guide to the agent-facing protocol. Surfaced
-    # under the new top-level `agent_protocol` key in Intro.run. Recipes
-    # describe CLI verbs (not Ruby Operations) because the audience is an
-    # agent driving textus from the command line.
-    AGENT_PROTOCOL = {
+    def self.write_flows_for(manifest)
+      manifest.role_mapping.each_with_object({}) do |(name, kind), acc|
+        tmpl = WRITE_FLOW_TEMPLATES[kind]
+        acc[name] = tmpl.call(name, manifest) if tmpl
+      end
+    end
+
+    # Static, store-independent parts of the agent-facing protocol. The
+    # `role_resolution` block is derived per-manifest in agent_protocol(...)
+    # because role names are user-configurable.
+    AGENT_PROTOCOL_TEMPLATE = {
       "envelope_shape" => {
         "summary" => "every read/write payload is a JSON envelope with _meta, body, uid, and etag",
         "fields" => {
@@ -41,11 +59,6 @@ module Textus
         },
         "ref" => "SPEC.md §8",
       },
-      "role_resolution" => {
-        "summary" => "write role is resolved in order: --as flag, TEXTUS_ROLE env var, .textus/role file, default human",
-        "roles" => %w[human agent runner builder],
-        "ref" => "SPEC.md §5",
-      },
       "recipes" => {
         "read" => {
           "purpose" => "find and read an entry",
@@ -92,7 +105,7 @@ module Textus
       { "name" => "schema",   "summary" => "field shape for a key family" },
       { "name" => "put",      "summary" => "write an entry; --as=<role>, --stdin payload" },
       { "name" => "accept",   "summary" => "apply a review.* proposal; --as=human only" },
-      { "name" => "key",      "summary" => "key operations: 'key mv', 'key uid', 'key normalize'" },
+      { "name" => "key",      "summary" => "key operations: 'key mv', 'key uid'" },
       { "name" => "delete",   "summary" => "delete an entry; --as=<role>" },
       { "name" => "build",    "summary" => "materialize output entries; publish_to and publish_each fan out copies" },
       { "name" => "refresh",  "summary" => "run an action for an intake entry" },
@@ -105,6 +118,17 @@ module Textus
         "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
     ].freeze
 
+    def self.agent_protocol(manifest)
+      AGENT_PROTOCOL_TEMPLATE.merge(
+        "role_resolution" => {
+          "summary" => "write role is resolved in order: --as flag, TEXTUS_ROLE env var, .textus/role file, " \
+                       "default 'human'",
+          "roles" => manifest.role_mapping.keys,
+          "ref" => "SPEC.md §5",
+        },
+      )
+    end
+
     def self.run(store)
       {
         "protocol" => PROTOCOL_ID,
@@ -112,9 +136,9 @@ module Textus
         "zones" => zones_for(store),
         "entries" => entries_for(store),
         "hooks" => hooks_for(store),
-        "write_flows" => WRITE_FLOWS.dup,
+        "write_flows" => write_flows_for(store.manifest),
         "cli_verbs" => CLI_VERBS.map(&:dup),
-        "agent_protocol" => AGENT_PROTOCOL,
+        "agent_protocol" => agent_protocol(store.manifest),
         "docs" => { "spec" => "SPEC.md", "example" => "examples/claude-plugin/" },
       }
     end
@@ -130,7 +154,7 @@ module Textus
 
     def self.entries_for(store)
       store.manifest.entries.map do |e|
-        derived = store.manifest.zone_writers(e.zone).include?("builder")
+        derived = store.manifest.zone_kinds(e.zone).include?(:generator)
         {
           "key" => e.key,
           "zone" => e.zone,

data/lib/textus/manifest/entry/base.rb

@@ -25,8 +25,8 @@ module Textus
           raise UsageError.new("entry '#{@key}': #{e.message}")
         end
 
-        def in_generator_zone? = zone_writers.include?("builder")
-        def in_proposal_zone?  = zone_writers.include?("agent")
+        def in_generator_zone? = @manifest.zone_kinds(@zone).include?(:generator)
+        def in_proposal_zone?  = @manifest.zone_kinds(@zone).include?(:proposer)
 
         def nested?  = false
         def derived? = false

data/lib/textus/manifest/entry/parser.rb

@@ -64,13 +64,7 @@ module Textus
 
         def self.parse_source(raw, key)
           compute = raw["compute"]
-          if compute.nil?
-            # Tolerate legacy derived entries with bare template (no compute block):
-            # treat as projection with no select.
-            return Derived::Projection.new(select: nil, pluck: nil, sort_by: nil, transform: nil) if raw["template"]
-
-            raise BadManifest.new("derived entry '#{key}' requires compute: { kind: projection|external } or template:")
-          end
+          raise BadManifest.new("derived entry '#{key}' requires compute: { kind: projection|external } or template:") if compute.nil?
 
           unless COMPUTE_KINDS.include?(compute["kind"])
             raise BadManifest.new(

data/lib/textus/manifest/resolver.rb

@@ -1,6 +1,8 @@
 module Textus
   class Manifest
     class Resolver
+      Resolution = Data.define(:entry, :path, :remaining)
+
       def initialize(manifest)
         @manifest = manifest
       end
@@ -83,7 +85,8 @@ module Textus
 
         illegal = segs.find { |s| !valid_segment?(s) }
         if illegal
-          warn("textus: skipping illegal key segment '#{illegal}' at #{path} — run 'textus key normalize --dry-run'")
+          warn("textus: skipping illegal key segment '#{illegal}' at #{path} — " \
+               "rename to match [a-z0-9][a-z0-9-]* (run 'textus doctor' for the full list)")
           return nil
         end
 

data/lib/textus/manifest/role_kinds.rb

@@ -0,0 +1,21 @@
+module Textus
+  class Manifest
+    module RoleKinds
+      DEFAULT_MAPPING = {
+        "human" => :accept_authority,
+        "agent" => :proposer,
+        "builder" => :generator,
+        "runner" => :runner,
+      }.freeze
+
+      # Returns { role_name => kind_symbol }. When `roles:` is declared we use
+      # exactly that; defaults are *not* layered in (declaring roles is an opt-in
+      # to a fully user-defined vocabulary).
+      def self.resolve(raw_roles)
+        return DEFAULT_MAPPING if raw_roles.nil?
+
+        raw_roles.to_h { |r| [r["name"], r["kind"].to_sym] }.freeze
+      end
+    end
+  end
+end

data/lib/textus/manifest/schema.rb

@@ -1,7 +1,9 @@
 module Textus
   class Manifest
     module Schema
-      ROOT_KEYS    = %w[version zones entries rules].freeze
+      ROOT_KEYS    = %w[version roles zones entries rules].freeze
+      ROLE_KEYS    = %w[name kind].freeze
+      ROLE_KINDS   = %w[accept_authority generator proposer runner].freeze
       ZONE_KEYS    = %w[name write_policy read_policy].freeze
       ENTRY_KEYS   = %w[
         key path zone kind schema owner nested format
@@ -19,6 +21,7 @@ module Textus
         raise BadManifest.new("manifest must be a hash") unless raw.is_a?(Hash)
 
         walk(raw, ROOT_KEYS, "$")
+        validate_roles!(raw["roles"])
         Array(raw["zones"]).each_with_index do |z, i|
           walk(z, ZONE_KEYS, "$.zones[#{i}]")
         end
@@ -37,6 +40,47 @@ module Textus
           end
           walk(r["promotion"], PROMOTION_KEYS, "#{path}.promotion") if r["promotion"].is_a?(Hash)
         end
+        validate_zone_writers_declared!(raw)
+      end
+
+      def self.validate_zone_writers_declared!(raw)
+        return if raw["roles"].nil? # default mapping is permissive
+
+        declared = Array(raw["roles"]).map { |r| r["name"] }.compact.to_set
+        Array(raw["zones"]).each do |z|
+          Array(z["write_policy"]).each_with_index do |w, j|
+            next if declared.include?(w)
+
+            raise BadManifest.new(
+              "zone '#{z["name"]}' write_policy[#{j}] references undeclared role '#{w}' " \
+              "(declared roles: #{declared.to_a.join(", ")})",
+            )
+          end
+        end
+      end
+
+      def self.validate_roles!(roles)
+        return if roles.nil?
+        raise BadManifest.new("roles: must be a list") unless roles.is_a?(Array)
+
+        accept_authority_count = 0
+        roles.each_with_index do |r, i|
+          path = "$.roles[#{i}]"
+          walk(r, ROLE_KEYS, path)
+          name = r["name"] or raise BadManifest.new("role at '#{path}' missing name")
+          kind = r["kind"] or raise BadManifest.new("role '#{name}' at '#{path}' missing kind")
+          unless ROLE_KINDS.include?(kind)
+            raise BadManifest.new("unknown role kind '#{kind}' at '#{path}' (known: #{ROLE_KINDS.join(", ")})")
+          end
+
+          accept_authority_count += 1 if kind == "accept_authority"
+        end
+        return unless accept_authority_count > 1
+
+        raise BadManifest.new(
+          "manifest declares #{accept_authority_count} accept_authority roles; " \
+          "at most one accept_authority role is allowed",
+        )
       end
 
       def self.validate_fetch_timeout!(value, path)

data/lib/textus/manifest.rb

@@ -1,7 +1,7 @@
 require "yaml"
 require_relative "manifest/schema"
-require_relative "manifest/resolution"
 require_relative "manifest/resolver"
+require_relative "manifest/role_kinds"
 
 module Textus
   class Manifest
@@ -30,6 +30,26 @@ module Textus
       )
     end
 
+    def role_mapping
+      @role_mapping ||= RoleKinds.resolve(@raw["roles"])
+    end
+
+    def role_kind(name)
+      role_mapping[name]
+    end
+
+    def roles_with_kind(kind)
+      role_mapping.each_with_object([]) { |(name, k), acc| acc << name if k == kind }
+    end
+
+    def zone_kinds(zone_name)
+      @zone_kinds_cache ||= {}
+      @zone_kinds_cache[zone_name] ||= zone_writers(zone_name).each_with_object(Set.new) do |w, acc|
+        k = role_kind(w)
+        acc << k if k
+      end.freeze
+    end
+
     def self.parse(yaml_text, root: ".")
       raw = YAML.safe_load(yaml_text, aliases: false)
       check_version!(raw, "<string>")

data/lib/textus/schema/tools.rb

@@ -49,7 +49,14 @@ module Textus
           end
         raise UsageError.new("schema migrate needs --rename=OLD:NEW or schema.evolution.migrate_from") if renames.empty?
 
-        ops = Textus::Operations.for(store, role: "human")
+        authority = store.manifest.roles_with_kind(:accept_authority).first
+        if authority.nil?
+          raise UsageError.new(
+            "schema migrate requires a role with kind :accept_authority in the manifest; " \
+            "none declared (add e.g. `- { name: owner, kind: accept_authority }` to roles:)",
+          )
+        end
+        ops = Textus::Operations.for(store, role: authority)
         touched = []
         store.manifest.resolver.enumerate.each do |row|
           env = ops.get(row[:key])

data/lib/textus/version.rb

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.20.0"
+  VERSION = "0.20.2"
   PROTOCOL = "textus/3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.20.2
 platform: ruby
 authors:
 - Patrick
@@ -110,7 +110,7 @@ files:
 - exe/textus
 - lib/textus.rb
 - lib/textus/application/context.rb
-- lib/textus/application/policy/predicates/human_accept.rb
+- lib/textus/application/policy/predicates/accept_authority_signed.rb
 - lib/textus/application/policy/predicates/schema_valid.rb
 - lib/textus/application/policy/promotion.rb
 - lib/textus/application/projection.rb
@@ -133,9 +133,8 @@ files:
 - lib/textus/application/refresh/all.rb
 - lib/textus/application/refresh/orchestrator.rb
 - lib/textus/application/refresh/worker.rb
-- lib/textus/application/tools/migrate_keys.rb
-- lib/textus/application/tools/migrate_manifest_to_kinds.rb
 - lib/textus/application/writes/accept.rb
+- lib/textus/application/writes/authority_gate.rb
 - lib/textus/application/writes/delete.rb
 - lib/textus/application/writes/envelope_io.rb
 - lib/textus/application/writes/materializer.rb
@@ -170,7 +169,6 @@ files:
 - lib/textus/cli/verb/hooks.rb
 - lib/textus/cli/verb/init.rb
 - lib/textus/cli/verb/intro.rb
-- lib/textus/cli/verb/key_normalize.rb
 - lib/textus/cli/verb/list.rb
 - lib/textus/cli/verb/mv.rb
 - lib/textus/cli/verb/published.rb
@@ -212,7 +210,6 @@ files:
 - lib/textus/domain/freshness/verdict.rb
 - lib/textus/domain/outcome.rb
 - lib/textus/domain/permission.rb
-- lib/textus/domain/policy.rb
 - lib/textus/domain/policy/handler_allowlist.rb
 - lib/textus/domain/policy/matcher.rb
 - lib/textus/domain/policy/promote.rb
@@ -263,8 +260,8 @@ files:
 - lib/textus/manifest/entry/validators/index_filename.rb
 - lib/textus/manifest/entry/validators/inject_intro.rb
 - lib/textus/manifest/entry/validators/publish_each.rb
-- lib/textus/manifest/resolution.rb
 - lib/textus/manifest/resolver.rb
+- lib/textus/manifest/role_kinds.rb
 - lib/textus/manifest/rules.rb
 - lib/textus/manifest/schema.rb
 - lib/textus/mustache.rb

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

@@ -1,30 +0,0 @@
-module Textus
-  module Application
-    module Policy
-      module Predicates
-        class HumanAccept
-          attr_reader :reason
-
-          def name
-            "human_accept"
-          end
-
-          # The role is passed explicitly. In practice, Accept already enforces
-          # role == "human" before reaching the promotion gate, so this predicate
-          # trivially passes. It documents intent and future-proofs multi-actor
-          # accept flows.
-          def call(role:, entry: nil) # rubocop:disable Lint/UnusedMethodArgument
-            role_str = role&.to_s
-            # If we cannot determine the role, trust that Accept has already
-            # checked — allow through.
-            return true if role_str.nil? || role_str.empty?
-
-            ok = (role_str == "human")
-            @reason = "current role is '#{role_str}', expected 'human'" unless ok
-            ok
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/application/tools/migrate_keys.rb

@@ -1,191 +0,0 @@
-module Textus
-  module Application
-    module Tools
-      # Run-once helper that renames files/directories whose basenames don't
-      # conform to the strict key grammar (§3 of plan-1.2). Only walks
-      # nested: true manifest entries — leaf entries with illegal declared
-      # keys are caught by Manifest load and must be fixed by hand.
-      module MigrateKeys
-        SEGMENT = /\A[a-z0-9][a-z0-9-]*\z/
-
-        module_function
-
-        # Returns the envelope hash described in plan-1.2 §3.
-        def run(store, write: false)
-          plan = build_plan(store)
-          collisions = plan[:collisions]
-          renames = plan[:renames]
-
-          ok = collisions.empty?
-          apply!(store, renames) if write && ok
-
-          {
-            "protocol" => Textus::PROTOCOL,
-            "mode" => write ? "write" : "dry-run",
-            "renames" => renames.map { |r| envelope_rename(r) },
-            "collisions" => collisions.map { |c| envelope_collision(c) },
-            "ok" => ok,
-          }
-        end
-
-        # ------------------------------------------------------------------
-        # Plan construction
-        # ------------------------------------------------------------------
-
-        # Returns { renames: [...], collisions: [...] }
-        # Each rename: { from:, to:, old_key:, new_key:, kind: :file|:dir }
-        # Each collision: { target:, sources: [...] }
-        def build_plan(store) # rubocop:disable Metrics/AbcSize
-          renames = []
-          target_buckets = Hash.new { |h, k| h[k] = [] } # target_path => [source_path, ...]
-
-          store.manifest.entries.each do |entry|
-            next unless entry.nested?
-
-            base = File.join(store.root, "zones", entry.path)
-            next unless File.directory?(base)
-
-            # Walk depth-first. Order matters when computing the "new key"
-            # for files inside a renamed directory: we record renames bottom-up,
-            # so children are renamed before their parents on apply.
-            walk(base) do |abs_path, is_dir|
-              next if abs_path == base
-
-              basename = File.basename(abs_path)
-              stem = is_dir ? basename : basename.sub(/#{Regexp.escape(File.extname(basename))}\z/, "")
-              next if stem.match?(SEGMENT)
-
-              new_stem = normalize(stem)
-              # Skip if normalization yields the same stem (e.g. already-legal
-              # under a different lens). In practice match?(SEGMENT) catches that
-              # above; this is a safety net.
-              next if new_stem == stem
-
-              new_basename = is_dir ? new_stem : new_stem + File.extname(basename)
-              target = File.join(File.dirname(abs_path), new_basename)
-              target_buckets[target] << abs_path
-
-              renames << {
-                from: abs_path,
-                to: target,
-                kind: is_dir ? :dir : :file,
-                entry: entry,
-                base: base,
-              }
-            end
-          end
-
-          collisions = target_buckets.select { |_, srcs| srcs.length > 1 }
-                                     .map { |t, srcs| { target: t, sources: srcs.sort } }
-
-          # Drop colliding entries from renames (we won't apply any of them)
-          colliding_targets = collisions.to_set { |c| c[:target] }
-          renames.reject! { |r| colliding_targets.include?(r[:to]) }
-
-          # Sort renames bottom-up (deepest path first) so children move before parents.
-          renames.sort_by! { |r| -r[:from].count("/") }
-
-          { renames: renames, collisions: collisions }
-        end
-
-        # Yields [absolute_path, is_dir] for every entry under root. Depth-first.
-        def walk(root, &block)
-          Dir.each_child(root) do |name|
-            abs = File.join(root, name)
-            if File.directory?(abs)
-              walk(abs, &block)
-              yield abs, true
-            else
-              yield abs, false
-            end
-          end
-        end
-
-        # Deterministic transform per plan §3.
-        def normalize(s)
-          s = s.downcase
-          s = s.gsub(/[^a-z0-9-]/, "-") # ., _, and anything else become -
-          s = s.gsub(/-+/, "-")
-          s.sub(/\A-+/, "").sub(/-+\z/, "")
-        end
-
-        # ------------------------------------------------------------------
-        # Apply
-        # ------------------------------------------------------------------
-
-        def apply!(store, renames)
-          audit = Textus::Infra::AuditLog.new(store.root)
-          renames.each do |r|
-            # Bottom-up order means a child's ancestors haven't moved yet, so
-            # `from`/`to` are valid as-recorded. The audit `key` reflects the
-            # eventual full key once every rename in this batch has applied.
-            from = r[:from]
-            to = r[:to]
-            File.rename(from, to)
-            new_key = compute_new_key(r, renames)
-            audit.append(
-              role: "runner",
-              verb: "migrate-keys",
-              key: new_key,
-              etag_before: nil,
-              etag_after: nil,
-              extras: { "from" => from, "to" => to },
-            )
-          end
-        end
-
-        # If an ancestor of `path` was renamed earlier in this batch, rewrite the path.
-        def resolve_current_path(path, renames)
-          out = path
-          renames.each do |r|
-            prefix = r[:from] + "/"
-            out = r[:to] + out[r[:from].length..] if out.start_with?(prefix)
-          end
-          out
-        end
-
-        # New full key after applying all renames up through this one.
-        def compute_new_key(rename, renames)
-          base = rename[:base]
-          entry = rename[:entry]
-          new_to = resolve_current_path(rename[:to], renames)
-
-          rel = new_to.sub(%r{\A#{Regexp.escape(base)}/?}, "")
-          stripped = rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "") unless rename[:kind] == :dir
-          stripped ||= rel
-          segs = stripped.split("/").reject(&:empty?)
-          (entry.key.split(".") + segs).join(".")
-        end
-
-        # ------------------------------------------------------------------
-        # Envelope helpers
-        # ------------------------------------------------------------------
-
-        def envelope_rename(r)
-          {
-            "from" => r[:from],
-            "to" => r[:to],
-            "old_key" => path_to_key(r[:from], r[:base], r[:entry], r[:kind]),
-            "new_key" => path_to_key(r[:to], r[:base], r[:entry], r[:kind]),
-          }
-        end
-
-        def envelope_collision(col)
-          { "target" => col[:target], "sources" => col[:sources] }
-        end
-
-        def path_to_key(path, base, entry, kind)
-          rel = path.sub(%r{\A#{Regexp.escape(base)}/?}, "")
-          stripped =
-            if kind == :dir
-              rel
-            else
-              rel.sub(/#{Regexp.escape(File.extname(rel))}\z/, "")
-            end
-          segs = stripped.split("/").reject(&:empty?)
-          (entry.key.split(".") + segs).join(".")
-        end
-      end
-    end
-  end
-end

data/lib/textus/application/tools/migrate_manifest_to_kinds.rb

@@ -1,31 +0,0 @@
-require "yaml"
-
-module Textus
-  module Application
-    module Tools
-      module MigrateManifestToKinds
-        module_function
-
-        def upgrade_yaml(yaml_text)
-          raw = YAML.safe_load(yaml_text, aliases: false)
-          raw["entries"] = Array(raw["entries"]).map { |row| upgrade_row(row) }
-          YAML.dump(raw)
-        end
-
-        def upgrade_row(row)
-          return row if row["kind"]
-
-          row.merge("kind" => infer_kind(row))
-        end
-
-        def infer_kind(row)
-          return "intake"  if row["intake"].is_a?(Hash) || row["intake_handler"]
-          return "derived" if row["template"] || row["compute"] || row["generator"] || row["projection"]
-          return "nested"  if row["nested"] == true
-
-          "leaf"
-        end
-      end
-    end
-  end
-end

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

@@ -1,48 +0,0 @@
-module Textus
-  class CLI
-    class Verb
-      class KeyNormalize < Verb
-        command_name "normalize"
-        parent_group Group::Key
-
-        option :write, "--write"
-        option :dry_run, "--dry-run"
-        option :upgrade_manifest, "--upgrade-manifest"
-
-        def call(store)
-          if upgrade_manifest
-            run_upgrade_manifest(store)
-          else
-            effective_write = write && !dry_run
-            res = Textus::Application::Tools::MigrateKeys.run(store, write: effective_write || false)
-            emit(res, exit_code: res["ok"] ? 0 : 1)
-          end
-        end
-
-        private
-
-        def run_upgrade_manifest(store)
-          manifest_path = File.join(store.root, "manifest.yaml")
-          orig = File.read(manifest_path)
-          new_yaml = Textus::Application::Tools::MigrateManifestToKinds.upgrade_yaml(orig)
-
-          if dry_run
-            diff_lines = unified_diff(orig, new_yaml, manifest_path)
-            emit({ "protocol" => PROTOCOL, "dry_run" => true, "diff" => diff_lines, "ok" => true }, exit_code: 0)
-          else
-            File.write(manifest_path, new_yaml)
-            puts "upgraded manifest at #{manifest_path}"
-            emit({ "protocol" => PROTOCOL, "upgraded" => manifest_path, "ok" => true }, exit_code: 0)
-          end
-        end
-
-        def unified_diff(before, after, _path)
-          before.lines.zip(after.lines).each_with_object([]) do |(a, b), acc|
-            acc << "- #{a.chomp}" if a && a != b
-            acc << "+ #{b.chomp}" if b && a != b
-          end
-        end
-      end
-    end
-  end
-end

data/lib/textus/domain/policy.rb

@@ -1,7 +0,0 @@
-module Textus
-  module Domain
-    module Policy
-      ALLOWED_ON_STALE = %i[warn sync timed_sync].freeze
-    end
-  end
-end

data/lib/textus/manifest/resolution.rb

@@ -1,5 +0,0 @@
-module Textus
-  class Manifest
-    Resolution = Data.define(:entry, :path, :remaining)
-  end
-end