textus 0.10.5 → 0.12.1

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

@@ -4,7 +4,7 @@ module Textus
   module Application
     module Reads
       # Per-entry freshness report. Walks every entry declared in the manifest,
-      # consults `policies_for(key)` for a refresh policy, and reports the
+      # consults `rules_for(key)` for a refresh rule, and reports the
       # current status. Status is one of :fresh, :stale, :never_refreshed, or
       # :no_policy.
       class Freshness
@@ -27,7 +27,7 @@ module Textus
         private
 
         def row_for(mentry)
-          set = @ctx.store.manifest.policies_for(mentry.key)
+          set = @ctx.store.manifest.rules_for(mentry.key)
           refresh = set.refresh
           envelope = safe_get(mentry.key)
           last = envelope&.dig("_meta", "last_refreshed_at")

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

@@ -12,7 +12,7 @@ module Textus
           envelope = @ctx.store.reader.read_raw_envelope(key)
           return nil if envelope.nil?
 
-          policy_set = @ctx.store.manifest.policies_for(key)
+          policy_set = @ctx.store.manifest.rules_for(key)
           refresh_policy = policy_set.refresh
           return annotate_fresh(envelope) if refresh_policy.nil?
 

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

@@ -9,7 +9,7 @@ module Textus
         end
 
         def call(key:)
-          policies = @ctx.store.manifest.policies
+          policies = @ctx.store.manifest.rules
           matching = policies.explain(key)
           winners  = policies.for(key)
 
@@ -29,7 +29,7 @@ module Textus
                 on_stale: winners.refresh.on_stale,
               },
               handler_allowlist: winners.handler_allowlist&.handlers,
-              promote_requires: winners.promote&.requires,
+              promotion: winners.promote && { requires: winners.promote.requires },
             },
           }
         end

data/lib/textus/application/refresh/orchestrator.rb

@@ -50,7 +50,7 @@ module Textus
             store_view = @store ? Textus::Application::Context.new(store: @store, role: @role) : nil
             payload = { key: key, started_at: Time.now.utc.iso8601, budget_ms: budget_ms }
             payload[:store] = store_view if store_view
-            @bus.publish(:refresh_detached, **payload)
+            @bus.publish(:refresh_backgrounded, **payload)
             @detached_spawner.call(store_root: @store_root, key: key)
             Textus::Domain::Outcome::Detached.new
           elsif result.is_a?(Textus::Error)

data/lib/textus/application/refresh/worker.rb

@@ -27,9 +27,9 @@ module Textus
         end
 
         def fetch_with_bus(key, mentry)
-          callable = @ctx.store.registry.rpc_callable(:intake, mentry.intake_handler)
-          @bus.publish(:refresh_began, store: read_view, key: key, mode: :sync,
-                                       correlation_id: @ctx.correlation_id)
+          callable = @ctx.store.registry.rpc_callable(:resolve_intake, mentry.intake_handler)
+          @bus.publish(:refresh_started, store: read_view, key: key, mode: :sync,
+                                         correlation_id: @ctx.correlation_id)
           call_intake(key, mentry, callable)
         end
 
@@ -61,8 +61,8 @@ module Textus
           )
           change = detect_change(before_etag, envelope)
           unless change == :unchanged
-            @bus.publish(:refreshed, store: read_view, key: key, envelope: envelope, change: change,
-                                     correlation_id: @ctx.correlation_id)
+            @bus.publish(:entry_refreshed, store: read_view, key: key, envelope: envelope, change: change,
+                                           correlation_id: @ctx.correlation_id)
           end
           envelope
         end

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

@@ -15,6 +15,8 @@ module Textus
           target = proposal["target_key"] or raise ProposalError.new("proposal missing target_key")
           action = proposal["action"] || "put"
 
+          evaluate_promotion!(env, target)
+
           case action
           when "put"
             # Nested proposal "frontmatter" — the meta to write to the accepted
@@ -30,7 +32,7 @@ module Textus
 
           Composition.writes_delete(@ctx).call(pending_key)
 
-          @bus.publish(:accepted,
+          @bus.publish(:proposal_accepted,
                        store: @ctx.with_role(@ctx.role),
                        key: pending_key,
                        target_key: target,
@@ -38,6 +40,22 @@ module Textus
 
           { "protocol" => PROTOCOL, "accepted" => pending_key, "target_key" => target, "action" => action }
         end
+
+        private
+
+        def evaluate_promotion!(env, target_key)
+          rules = @ctx.store.manifest.rules_for(target_key)
+          promote = rules.promote
+          return if promote.nil? || promote.requires.empty?
+
+          policy = Textus::Domain::Policy::Promotion.from_names(promote.requires)
+          result = policy.evaluate(entry: env, store: @ctx.store)
+          return if result.ok?
+
+          raise ProposalError.new(
+            "promotion gate failed: #{result.reasons.join("; ")}",
+          )
+        end
       end
     end
   end

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

@@ -5,8 +5,8 @@ module Textus
     module Writes
       # Materializes generator-zone entries (template + projection) onto disk
       # and copies the result to any configured `publish_to` / `publish_each`
-      # targets. Fires `:built` and `:published` events on the bus, tagged with
-      # the request's correlation_id for traceability.
+      # targets. Fires `:build_completed` and `:file_published` events on the bus,
+      # tagged with the request's correlation_id for traceability.
       class Build
         def initialize(ctx:, bus:)
           @ctx = ctx
@@ -59,7 +59,7 @@ module Textus
           end
 
           Textus::Infra::Publisher.publish(source: row[:path], target: target_abs, store_root: root)
-          publish_event(:published,
+          publish_event(:file_published,
                         key: row[:key],
                         envelope: store.get(row[:key]),
                         source: row[:path],
@@ -91,14 +91,14 @@ module Textus
           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(:published,
+            publish_event(:file_published,
                           key: mentry.key,
                           envelope: envelope,
                           source: target_path,
                           target: target_abs)
           end
 
-          publish_event(:built,
+          publish_event(:build_completed,
                         key: mentry.key,
                         envelope: envelope,
                         sources: Array(mentry.projection&.fetch("select", nil)).compact)

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

@@ -21,7 +21,7 @@ module Textus
           )
 
           unless suppress_events
-            @bus.publish(:deleted,
+            @bus.publish(:entry_deleted,
                          store: @ctx.with_role(@ctx.role),
                          key: key,
                          correlation_id: @ctx.correlation_id)

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

@@ -13,7 +13,7 @@ module Textus
             target: target,
             store_root: @ctx.store.root,
           )
-          @bus.publish(:published,
+          @bus.publish(:file_published,
                        key: key,
                        source: source,
                        target: target,

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

@@ -25,7 +25,7 @@ module Textus
           )
 
           unless suppress_events
-            @bus.publish(:put,
+            @bus.publish(:entry_put,
                          store: @ctx.with_role(@ctx.role),
                          key: key,
                          envelope: envelope,

data/lib/textus/builder/pipeline.rb

@@ -10,7 +10,7 @@ module Textus
         from = Array(mentry.projection&.fetch("select", nil)).compact
         meta["from"] = from unless from.empty?
         meta["template"] = mentry.template if mentry.template
-        reduce = mentry.projection&.dig("reduce")
+        reduce = mentry.projection&.dig("transform")
         meta["reduce"] = reduce if reduce
 
         out = { "_meta" => meta }

data/lib/textus/builder/renderer/json.rb

@@ -28,7 +28,7 @@ module Textus
         end
 
         def default_shape(mentry, data)
-          if mentry.projection && mentry.projection["reduce"] && data.is_a?(Hash) && !data.key?("entries")
+          if mentry.projection && mentry.projection["transform"] && data.is_a?(Hash) && !data.key?("entries")
             data
           elsif data.is_a?(Hash) && data["entries"].is_a?(Array)
             { "entries" => data["entries"] }

data/lib/textus/builder/renderer/yaml.rb

@@ -28,7 +28,7 @@ module Textus
         end
 
         def default_shape(mentry, data)
-          if mentry.projection && mentry.projection["reduce"] && data.is_a?(Hash) && !data.key?("entries")
+          if mentry.projection && mentry.projection["transform"] && data.is_a?(Hash) && !data.key?("entries")
             data
           elsif data.is_a?(Hash) && data["entries"].is_a?(Array)
             { "entries" => data["entries"] }

data/lib/textus/cli/group/key.rb

@@ -5,7 +5,7 @@ module Textus
         self.cli_name = "key"
         subcommands["mv"]      = Verb::Mv
         subcommands["uid"]     = Verb::Uid
-        subcommands["migrate"] = Verb::MigrateKeys
+        subcommands["normalize"] = Verb::KeyNormalize
       end
     end
   end

data/lib/textus/cli/group/refresh.rb

@@ -0,0 +1,21 @@
+module Textus
+  class CLI
+    class Group
+      class Refresh < Group
+        self.cli_name = "refresh"
+        subcommands["stale"] = Verb::RefreshStale
+
+        def parse(argv)
+          if argv.first == "stale"
+            argv.shift
+            @sub_klass = Verb::RefreshStale
+          else
+            @sub_klass = Verb::Refresh
+          end
+          @sub = @sub_klass.new(stdin: @stdin, stdout: @stdout, stderr: @stderr, cwd: @cwd)
+          @sub.parse(argv)
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/group/rule.rb

@@ -0,0 +1,11 @@
+module Textus
+  class CLI
+    class Group
+      class Rule < Group
+        self.cli_name = "rule"
+        subcommands["list"]    = Verb::RuleList
+        subcommands["explain"] = Verb::RuleExplain
+      end
+    end
+  end
+end

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

@@ -5,7 +5,7 @@ module Textus
         option :prefix, "--prefix=K"
 
         def call(store)
-          ctx = Textus::Composition.context(store, role: "build")
+          ctx = Textus::Composition.context(store, role: "builder")
           emit(Textus::Composition.writes_build(ctx).call(prefix: prefix))
         end
       end

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

@@ -15,7 +15,8 @@ module Textus
           @raw_argv.each do |tok|
             case tok
             when /\A--as=(.+)\z/         then as_flag = ::Regexp.last_match(1)
-            when /\A--format=/           then next
+            when /\A--output=/           then next
+            when /\A--format=/           then raise FlagRenamed.new("--format", "--output")
             when /\A--([\w-]+)=(.*)\z/   then args[::Regexp.last_match(1)] = ::Regexp.last_match(2)
             else
               raise UsageError.new("unknown arg to 'hook run #{name}': #{tok}")
@@ -23,7 +24,7 @@ module Textus
           end
 
           role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-          callable = store.registry.rpc_callable(:intake, name)
+          callable = store.registry.rpc_callable(:resolve_intake, name)
           view = Application::Context.new(store: store, role: role)
 
           begin

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

@@ -35,7 +35,7 @@ module Textus
 
                 rows << {
                   "event" => evt.to_s, "mode" => "manifest", "exec" => defn["exec"],
-                  "key" => e.key, "as" => defn["as"] || "script"
+                  "key" => e.key, "as" => defn["as"] || "runner"
                 }
               end
             end

data/lib/textus/cli/verb/{migrate_keys.rb → key_normalize.rb}

@@ -1,7 +1,7 @@
 module Textus
   class CLI
     class Verb
-      class MigrateKeys < Verb
+      class KeyNormalize < Verb
         option :write, "--write"
         option :dry_run, "--dry-run"
 

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

@@ -15,7 +15,7 @@ module Textus
           raw = @stdin.read
           payload =
             if fetch_name
-              callable = store.registry.rpc_callable(:intake, fetch_name)
+              callable = store.registry.rpc_callable(:resolve_intake, fetch_name)
               result =
                 begin
                   Timeout.timeout(Textus::Application::Refresh::Worker::FETCH_TIMEOUT_SECONDS) do

data/lib/textus/cli/verb/{policy_explain.rb → rule_explain.rb}

@@ -1,7 +1,7 @@
 module Textus
   class CLI
     class Verb
-      class PolicyExplain < Verb
+      class RuleExplain < Verb
         def call(store)
           key = positional.shift or raise UsageError.new("policy explain requires a KEY")
           ctx = context_for(store)

data/lib/textus/cli/verb/{policy_list.rb → rule_list.rb}

@@ -1,9 +1,9 @@
 module Textus
   class CLI
     class Verb
-      class PolicyList < Verb
+      class RuleList < Verb
         def call(store)
-          policies = store.manifest.policies.blocks.map do |b|
+          policies = store.manifest.rules.blocks.map do |b|
             row = { "match" => b.match }
             if b.refresh
               row["refresh"] = {
@@ -13,7 +13,7 @@ module Textus
               }
             end
             row["handler_allowlist"] = b.handler_allowlist.handlers if b.handler_allowlist
-            row["promote_requires"] = b.promote.requires if b.promote
+            row["promotion"] = { "requires" => b.promote.requires } if b.promote
             row["retention"] = b.retention if b.retention
             row
           end

data/lib/textus/cli/verb.rb

@@ -41,9 +41,10 @@ module Textus
           self.class.options.each do |name, optspec|
             o.on(optspec) { |v| public_send(:"#{name}=", v) }
           end
-          o.on("--format=FMT") { |v| fmt = v }
+          o.on("--output=FMT") { |v| fmt = v }
+          o.on("--format=FMT") { |_v| raise FlagRenamed.new("--format", "--output") }
         end.permute!(argv)
-        raise UsageError.new("only --format=json is supported in v1") unless fmt == "json"
+        raise UsageError.new("only --output=json is supported in v1") unless fmt == "json"
 
         @positional = argv.dup
       end

data/lib/textus/cli.rb

@@ -21,12 +21,11 @@ module Textus
       "intro" => Verb::Intro,
       "key" => Group::Key,
       "list" => Verb::List,
-      "policy" => Group::Policy,
       "published" => Verb::Published,
       "put" => Verb::Put,
       "rdeps" => Verb::Rdeps,
-      "refresh" => Verb::Refresh,
-      "refresh-stale" => Verb::RefreshStale,
+      "refresh" => Group::Refresh,
+      "rule" => Group::Rule,
       "schema" => Group::Schema,
       "where" => Verb::Where,
     }.freeze
@@ -90,16 +89,17 @@ module Textus
           textus get KEY
           textus put KEY --stdin [--fetch=NAME] --as=ROLE
           textus freshness [--prefix=KEY] [--zone=Z]
-          textus refresh-stale [--prefix=KEY] [--zone=Z]
+          textus refresh KEY
+          textus refresh stale [--prefix=KEY] [--zone=Z]
           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 key {mv,uid,migrate}
+          textus key {mv,uid,normalize}
+          textus rule {list,explain}
           textus schema {show,init,diff,migrate}
           textus hook {list,run}
-          textus policy {list,explain}
       HELP
     end
   end

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

@@ -11,7 +11,7 @@ module Textus
             handler = mentry.intake_handler
             next if handler.nil?
 
-            allow = store.manifest.policies_for(mentry.key).handler_allowlist
+            allow = store.manifest.rules_for(mentry.key).handler_allowlist
             next if allow.nil?
             next if allow.allows?(handler)
 

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

@@ -10,28 +10,51 @@ module Textus
             base = File.join(store.root, "zones", entry.path)
             next unless File.directory?(base)
 
-            walk_nested(base) do |abs_path, is_dir|
-              basename = File.basename(abs_path)
-              stem = is_dir ? basename : basename.sub(/#{Regexp.escape(File.extname(basename))}\z/, "")
-              next if stem.match?(Key::Grammar::SEGMENT)
-
-              proposed = Textus::MigrateKeys.normalize(stem)
-              out << {
-                "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 migrate --dry-run' then '--write' to rename to '#{proposed}'",
-              }
-            end
+            entry.index_filename ? check_index_paths(entry, base, out) : check_all_paths(base, out)
           end
           out
         end
 
         private
 
+        def check_all_paths(base, out)
+          walk_nested(base) do |abs_path, is_dir|
+            basename = File.basename(abs_path)
+            stem = is_dir ? basename : basename.sub(/#{Regexp.escape(File.extname(basename))}\z/, "")
+            next if stem.match?(Key::Grammar::SEGMENT)
+
+            out << issue(abs_path, stem)
+          end
+        end
+
+        # When the entry uses `index_filename:`, only the parent-directory
+        # segments leading to each index file participate in keys. Sibling
+        # files and unrelated subtrees are not enumerated and must not be
+        # flagged. Each illegal segment is reported once per path.
+        def check_index_paths(entry, base, out)
+          Dir.glob(File.join(base, "**", entry.index_filename)).each do |fp|
+            rel = fp.sub(%r{\A#{Regexp.escape(base)}/?}, "")
+            File.dirname(rel).split("/").reject { |s| s.empty? || s == "." }.each do |seg|
+              next if seg.match?(Key::Grammar::SEGMENT)
+
+              out << issue(fp, seg)
+            end
+          end
+        end
+
+        def issue(abs_path, stem)
+          proposed = Textus::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}'",
+          }
+        end
+
         def walk_nested(root, &block)
           Dir.each_child(root) do |name|
             abs = File.join(root, name)

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

@@ -6,15 +6,15 @@ module Textus
 
         def call
           declared = collect_declared_handlers
-          registered = store.registry.rpc_names(:intake).to_set
+          registered = store.registry.rpc_names(:resolve_intake).to_set
 
           out = (declared - registered).map do |name|
             {
               "code" => "intake.handler_missing",
               "level" => "error",
               "subject" => name.to_s,
-              "message" => "manifest references intake handler '#{name}' but no Textus.intake(:#{name}) is registered",
-              "fix" => "create .textus/hooks/#{name}.rb with `Textus.intake(:#{name}) { ... }`",
+              "message" => "manifest references intake handler '#{name}' but no Textus.on(:resolve_intake, :#{name}) is registered",
+              "fix" => "create .textus/hooks/#{name}.rb with `Textus.on(:resolve_intake, :#{name}) { ... }`",
             }
           end
 
@@ -23,7 +23,7 @@ module Textus
               "code" => "intake.handler_orphan",
               "level" => "warning",
               "subject" => name.to_s,
-              "message" => "Textus.intake(:#{name}) is registered but no manifest entry references it",
+              "message" => "Textus.on(:resolve_intake, :#{name}) is registered but no manifest entry references it",
               "fix" => "remove the unused handler, or add an entry with `intake.handler: #{name}`",
             }
           end

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

@@ -0,0 +1,47 @@
+require "yaml"
+
+module Textus
+  module Doctor
+    class Check
+      # Runs as a standalone module (Check::ProtocolVersion.run(root:)) and also
+      # as a class-based doctor check (ProtocolVersion.new(store).call).
+      class ProtocolVersion < Check
+        # Standalone interface: root is the project root (parent of .textus/).
+        def self.run(root:)
+          path = File.join(root, ".textus/manifest.yaml")
+          return [] unless File.exist?(path)
+
+          doc = YAML.safe_load_file(path, aliases: false) || {}
+          version = doc["version"]
+          return [] if version == "textus/3"
+
+          [{
+            "code" => "protocol_mismatch",
+            "severity" => "error",
+            "message" => "Store reports version=#{version.inspect}; this gem expects textus/3.",
+            "hint" => "Install textus 0.11.x to run the migrator, then upgrade to this version. See https://github.com/patrick204nqh/textus/blob/main/CHANGELOG.md#0110",
+          }]
+        end
+
+        # Doctor check interface: store.root is the .textus/ directory itself,
+        # so manifest.yaml lives directly inside it.
+        def call
+          path = File.join(store.root, "manifest.yaml")
+          return [] unless File.exist?(path)
+
+          doc = YAML.safe_load_file(path, aliases: false) || {}
+          version = doc["version"]
+          return [] if version == "textus/3"
+
+          [{
+            "code" => "protocol_mismatch",
+            "level" => "error",
+            "subject" => path,
+            "message" => "Store reports version=#{version.inspect}; this gem expects textus/3.",
+            "fix" => "Install textus 0.11.x to run the migrator, then upgrade to this version. See https://github.com/patrick204nqh/textus/blob/main/CHANGELOG.md#0110",
+          }]
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/{policy_ambiguity.rb → rule_ambiguity.rb}

@@ -1,18 +1,18 @@
 module Textus
   module Doctor
     class Check
-      # Flags entries whose key is matched by two or more policy blocks of the
+      # Flags entries whose key is matched by two or more rule blocks of the
       # SAME specificity in the same slot (refresh / handler_allowlist /
       # promote). Ties are non-deterministic in the parser's pick step, so
       # they're a configuration smell — surface them.
-      class PolicyAmbiguity < Check
+      class RuleAmbiguity < Check
         SLOTS = %i[refresh handler_allowlist promote].freeze
 
         def call
           out = []
-          policies = store.manifest.policies
+          rules = store.manifest.rules
           store.manifest.entries.each do |mentry|
-            matches = policies.explain(mentry.key)
+            matches = rules.explain(mentry.key)
             next if matches.length < 2
 
             SLOTS.each { |slot| out.concat(ambiguities_for(mentry, slot, matches)) }
@@ -34,10 +34,10 @@ module Textus
         def issue_for(mentry, slot, group)
           globs = group.map(&:match).sort
           {
-            "code" => "policy.ambiguity",
+            "code" => "rule.ambiguity",
             "level" => "warning",
             "subject" => mentry.key,
-            "message" => "entry '#{mentry.key}' matches #{group.length} policy blocks at the same " \
+            "message" => "entry '#{mentry.key}' matches #{group.length} rule blocks at the same " \
                          "specificity for #{slot}: #{globs.join(", ")}",
             "fix" => "narrow one of the conflicting match: globs in .textus/manifest.yaml so a single " \
                      "block wins for this key",

data/lib/textus/doctor.rb

@@ -9,6 +9,7 @@ module Textus
     DOCTOR_CHECK_TIMEOUT_SECONDS = 2
 
     CHECKS = [
+      Check::ProtocolVersion,
       Check::ManifestFiles,
       Check::Schemas,
       Check::SchemaParseError,
@@ -20,7 +21,7 @@ module Textus
       Check::AuditLog,
       Check::UnownedSchemaFields,
       Check::SchemaViolations,
-      Check::PolicyAmbiguity,
+      Check::RuleAmbiguity,
       Check::HandlerAllowlist,
     ].freeze
 
@@ -53,8 +54,8 @@ module Textus
     def run_registered_checks(store)
       out = []
       view = Application::Context.new(store: store, role: "human")
-      store.registry.rpc_names(:check).each do |name|
-        callable = store.registry.rpc_callable(:check, name)
+      store.registry.rpc_names(:validate).each do |name|
+        callable = store.registry.rpc_callable(:validate, name)
         begin
           result = Timeout.timeout(DOCTOR_CHECK_TIMEOUT_SECONDS) { callable.call(store: view) }
           if result.is_a?(Array)
@@ -71,7 +72,7 @@ module Textus
         rescue StandardError => e
           out << fail_issue(name, code: "doctor_check.failed",
                                   message: "#{e.class}: #{e.message}",
-                                  fix: "fix the :check hook in .textus/hooks/")
+                                  fix: "fix the :validate hook in .textus/hooks/")
         end
       end
       out