textus 0.20.0 → 0.22.0

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

@@ -1,13 +1,14 @@
 module Textus
   module Application
     module Writes
-      # Single-pass publish use case: materializes Derived entries (template +
-      # projection + external runner) AND copies Leaf/Nested entries to their
-      # publish targets. Replaces the former two-step Build + Publish split.
+      # Single-pass publish use case: dispatches polymorphically to each
+      # entry's `publish_via` method. Derived entries materialize their body
+      # via Materializer; Nested entries fan out via publish_each; Leaf and
+      # Intake entries copy their stored body to publish_to targets. The
+      # Publish layer owns wiring (context, accumulation) but not per-kind
+      # logic.
       #
       # Return shape: { "protocol", "built", "published_leaves" }
-      # — wire-compatible with what the `textus build` CLI verb previously
-      #   assembled by merging Build + old Publish results.
       class Publish
         def initialize(ctx:, manifest:, file_store:, bus:, root:, store:, hook_context:) # rubocop:disable Metrics/ParameterLists
           @ctx          = ctx
@@ -22,26 +23,17 @@ module Textus
         def call(prefix: nil)
           built  = []
           leaves = []
-          repo_root = File.dirname(@root)
+          context = build_context
 
           @manifest.entries.each do |mentry|
             next if prefix && !entry_matches_prefix?(mentry, prefix)
 
-            case mentry
-            when Textus::Manifest::Entry::Derived
-              next unless mentry.in_generator_zone?
+            result = mentry.publish_via(context, prefix: prefix)
+            next if result.nil?
 
-              result = materialize_derived(mentry, repo_root)
-              built << result if result
-            when Textus::Manifest::Entry::Nested
-              next unless mentry.publish_each
-
-              publish_nested(mentry, repo_root, prefix, leaves)
-            when Textus::Manifest::Entry::Leaf
-              next if Array(mentry.publish_to).empty?
-
-              result = publish_leaf_entry(mentry, repo_root)
-              built << result if result
+            case result[:kind]
+            when :built  then built << result[:value]
+            when :leaves then leaves.concat(result[:value])
             end
           end
 
@@ -50,86 +42,19 @@ module Textus
 
         private
 
-        # Materialize a Derived entry and copy to publish_to targets.
-        def materialize_derived(mentry, repo_root)
-          target_path = Materializer.new(
-            ctx: @ctx, manifest: @manifest, file_store: @file_store,
-            bus: @bus, root: @root, store: @store
-          ).run(mentry)
-
-          publish_derived_copies(mentry, target_path, repo_root)
-          fire_build_completed(mentry, target_path)
-
-          { "key" => mentry.key, "path" => target_path, "published_to" => mentry.publish_to }
-        end
-
-        def publish_derived_copies(mentry, target_path, repo_root)
-          envelope = reader.call(mentry.key)
-          mentry.publish_to.each do |rel|
-            target_abs = File.join(repo_root, rel)
-            Textus::Infra::Publisher.publish(source: target_path, target: target_abs, store_root: @root)
-            publish_event(:file_published,
-                          key: mentry.key,
-                          envelope: envelope,
-                          source: target_path,
-                          target: target_abs)
-          end
-        end
-
-        def fire_build_completed(mentry, target_path) # rubocop:disable Lint/UnusedMethodArgument
-          envelope = reader.call(mentry.key)
-          src = mentry.source
-          selects = src.is_a?(Textus::Manifest::Entry::Derived::Projection) ? Array(src.select).compact : []
-          publish_event(:build_completed,
-                        key: mentry.key,
-                        envelope: envelope,
-                        sources: selects)
-        end
-
-        # Publish each leaf under a Nested entry's publish_each pattern.
-        def publish_nested(mentry, repo_root, prefix, accumulator)
-          @manifest.resolver.enumerate(prefix: mentry.key).each do |row|
-            next unless row[:manifest_entry].equal?(mentry)
-            next if prefix && !row[:key].start_with?(prefix) && row[:key] != prefix
-
-            accumulator << publish_nested_leaf(mentry, row, repo_root)
-          end
-        end
-
-        def publish_nested_leaf(mentry, row, repo_root)
-          target_rel = mentry.publish_target_for(row[:key])
-          target_abs = File.expand_path(File.join(repo_root, target_rel))
-          unless target_abs.start_with?(File.expand_path(repo_root) + File::SEPARATOR)
-            raise PublishError.new(
-              "entry '#{mentry.key}': publish_each target '#{target_rel}' for key '#{row[:key]}' escapes repo root",
-            )
-          end
-
-          Textus::Infra::Publisher.publish(source: row[:path], target: target_abs, store_root: @root)
-          publish_event(:file_published,
-                        key: row[:key],
-                        envelope: reader.call(row[:key]),
-                        source: row[:path],
-                        target: target_abs)
-          { "key" => row[:key], "source" => row[:path], "target" => target_abs }
-        end
-
-        # Publish a standalone Leaf entry that has publish_to targets.
-        def publish_leaf_entry(mentry, repo_root)
-          source_path = @manifest.resolver.resolve(mentry.key).path
-          envelope = reader.call(mentry.key)
-
-          mentry.publish_to.each do |rel|
-            target_abs = File.join(repo_root, rel)
-            Textus::Infra::Publisher.publish(source: source_path, target: target_abs, store_root: @root)
-            publish_event(:file_published,
-                          key: mentry.key,
-                          envelope: envelope,
-                          source: source_path,
-                          target: target_abs)
-          end
-
-          { "key" => mentry.key, "path" => source_path, "published_to" => mentry.publish_to }
+        def build_context
+          Textus::Manifest::Entry::Base::PublishContext.new(
+            repo_root: File.dirname(@root),
+            manifest: @manifest,
+            file_store: @file_store,
+            root: @root,
+            store: @store,
+            ctx: @ctx,
+            bus: @bus,
+            hook_context: @hook_context,
+            reader: reader,
+            emit: ->(event, **payload) { @bus.publish(event, ctx: @hook_context, **payload) },
+          )
         end
 
         # Whether the entry should be processed for the given prefix filter.
@@ -138,8 +63,6 @@ module Textus
 
           case mentry
           when Textus::Manifest::Entry::Nested
-            # Nested: process if the entry key is a prefix of `prefix` or
-            # `prefix` is a prefix of the entry key (a leaf under it).
             mentry.key.start_with?(prefix) ||
               prefix.start_with?("#{mentry.key}.")
           else
@@ -152,10 +75,6 @@ module Textus
             ctx: @ctx, manifest: @manifest, file_store: @file_store,
           )
         end
-
-        def publish_event(event, **payload)
-          @bus.publish(event, ctx: @hook_context, **payload)
-        end
       end
     end
   end

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/{intro.rb → boot.rb}

@@ -4,8 +4,8 @@ module Textus
   # project: zones and their write authority, entries and their flags,
   # registered hooks, write flows, and the CLI verb catalog.
   #
-  # Intro is side-effect-free.
-  module Intro
+  # Boot is side-effect-free.
+  module Boot
     PROTOCOL_ID = PROTOCOL
 
     # Conventional zone purposes. Unknown zones (declared in the manifest
@@ -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",
@@ -82,17 +95,17 @@ module Textus
     }.freeze
 
     # The CLI verb catalog. Truth lives here; do not derive dynamically.
-    # Agents that read intro should see a stable shape regardless of how
+    # Agents that read boot should see a stable shape regardless of how
     # verb implementations evolve.
     CLI_VERBS = [
-      { "name" => "intro",    "summary" => "this output — orientation for agents and tools" },
+      { "name" => "boot",     "summary" => "this output — orientation for agents and tools" },
       { "name" => "list",     "summary" => "enumerate keys (optional --prefix)" },
       { "name" => "get",      "summary" => "read an entry; envelope with _meta, body, uid, etag" },
       { "name" => "where",    "summary" => "resolve a key to its zone and path without reading" },
       { "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" },
@@ -103,8 +116,40 @@ module Textus
       { "name" => "doctor", "summary" => "health-check the store (missing schemas, illegal keys, sentinel drift, etc.)" },
       { "name" => "hook",
         "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
+      { "name" => "pulse",
+        "summary" => "delta since cursor — changed entries, stale, pending review, doctor summary" },
     ].freeze
 
+    def self.agent_quickstart(manifest, store)
+      proposer_roles = manifest.roles_with_kind(:proposer)
+      agent_role = proposer_roles.first
+
+      writable_zones = manifest.zones.each_with_object([]) do |(zname, writers), acc|
+        acc << zname if agent_role && writers.include?(agent_role)
+      end
+
+      propose_zone = writable_zones.find { |z| z.include?("review") } || writable_zones.first
+
+      {
+        "read_verbs" => %w[boot get list audit pulse freshness doctor],
+        "write_verbs" => agent_role ? ["put KEY --as=#{agent_role} --stdin"] : [],
+        "writable_zones" => writable_zones,
+        "propose_zone" => propose_zone,
+        "latest_seq" => store.audit_log.latest_seq,
+      }
+    end
+
+    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 +157,10 @@ 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),
+        "agent_quickstart" => agent_quickstart(store.manifest, store),
         "docs" => { "spec" => "SPEC.md", "example" => "examples/claude-plugin/" },
       }
     end
@@ -130,7 +176,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,
@@ -141,7 +187,7 @@ module Textus
           "derived" => derived,
           "intake" => e.is_a?(Textus::Manifest::Entry::Intake),
           "publish_to" => Array(e.publish_to),
-          "publish_each" => e.respond_to?(:publish_each) ? e.publish_each : nil,
+          "publish_each" => e.publish_each,
         }
       end
     end

data/lib/textus/builder/pipeline.rb

@@ -64,7 +64,7 @@ module Textus
 
       # rubocop:disable Metrics/ParameterLists
       def self.run(mentry:, manifest:, reader:, lister:, transform_resolver:, template_loader:,
-                   transform_context: nil, inject_intro: nil)
+                   transform_context: nil, inject_boot: nil)
         # 1. Load sources + project + reduce
         data =
           if mentry.is_a?(Textus::Manifest::Entry::Derived) && mentry.projection?
@@ -78,7 +78,7 @@ module Textus
           else
             { "entries" => [], "count" => 0, "generated_at" => Time.now.utc.iso8601 }
           end
-        data = data.merge("intro" => inject_intro.call) if mentry.inject_intro && inject_intro
+        data = data.merge("boot" => inject_boot.call) if mentry.inject_boot && inject_boot
 
         # 2. Render
         klass = renderers[mentry.format] or

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

@@ -9,6 +9,7 @@ module Textus
         option :role_filter, "--role=ROLE"
         option :verb_filter, "--verb=V"
         option :since, "--since=ISO8601|RELATIVE"
+        option :seq_since, "--seq-since=N"
         option :correlation_id, "--correlation-id=ID"
         option :limit, "--limit=N"
 
@@ -21,6 +22,7 @@ module Textus
             role: role_filter,
             verb: verb_filter,
             since: since_time,
+            seq_since: seq_since&.to_i,
             correlation_id: correlation_id,
             limit: limit&.to_i,
           )

data/lib/textus/cli/verb/{intro.rb → boot.rb}

@@ -1,11 +1,11 @@
 module Textus
   class CLI
     class Verb
-      class Intro < Verb
-        command_name "intro"
+      class Boot < Verb
+        command_name "boot"
 
         def call(store)
-          emit(Textus::Intro.run(store))
+          emit(Textus::Boot.run(store))
         end
       end
     end

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/cli/verb/pulse.rb

@@ -0,0 +1,17 @@
+module Textus
+  class CLI
+    class Verb
+      class Pulse < Verb
+        command_name "pulse"
+
+        option :since, "--since=N"
+
+        def call(store)
+          ops = operations_for(store)
+          since_n = (since || "0").to_i
+          emit(ops.pulse(since: since_n))
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli.rb

@@ -99,7 +99,7 @@ module Textus
           textus audit [--key=K] [--zone=Z] [--role=R] [--verb=V] [--since=X] [--correlation-id=ID] [--limit=N]
           textus blame KEY [--limit=N]
           textus doctor
-          textus intro
+          textus boot
 
           textus key {mv,uid,normalize}
           textus rule {list,explain}

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

@@ -215,4 +215,20 @@ module Textus
       )
     end
   end
+
+  class CursorExpired < Error
+    attr_reader :requested, :min_available
+
+    def initialize(requested:, min_available:)
+      @requested = requested
+      @min_available = min_available
+      super(
+        "cursor_expired",
+        "audit cursor expired: requested seq=#{requested} but oldest available is #{min_available}; " \
+        "call `textus boot` to re-orient and resume from latest_seq",
+        details: { "requested" => requested, "min_available" => min_available },
+        hint: "call `textus boot` to get the current latest_seq and resume from there",
+      )
+    end
+  end
 end