textus 0.51.0 → 0.53.0

data/lib/textus/background/worker.rb

@@ -0,0 +1,67 @@
+module Textus
+  module Background
+    class Worker
+      Summary = Struct.new(:completed, :failed, keyword_init: true)
+
+      def self.for(container:, queue:)
+        new(queue: queue, container: container,
+            lease_ttl: container.manifest.data.worker_config[:lease_ttl])
+      end
+
+      def initialize(queue:, container:, lease_ttl: 60)
+        @queue     = queue
+        @container = container
+        @lease_ttl = lease_ttl
+      end
+
+      def drain(worker_id: "drain-#{Process.pid}")
+        completed = 0
+        failed    = 0
+        loop do
+          leased = @queue.lease(worker_id: worker_id, lease_ttl: @lease_ttl)
+          break unless leased
+
+          case run_one(leased)
+          when :completed     then completed += 1
+          when :dead_lettered then failed += 1
+          end
+        end
+        Summary.new(completed: completed, failed: failed)
+      end
+
+      def drain_pool(pool: 4)
+        summaries = []
+        mutex     = Mutex.new
+        threads   = Array.new(pool) do |i|
+          Thread.new do
+            s = drain(worker_id: "pool-#{Process.pid}-#{i}")
+            mutex.synchronize { summaries << s }
+          end
+        end
+        threads.each(&:join)
+        Summary.new(completed: summaries.sum(&:completed), failed: summaries.sum(&:failed))
+      end
+
+      private
+
+      def run_one(leased)
+        job    = leased.job
+        klass  = Textus::Background::Job.fetch(job.type)
+        action = if klass.instance_method(:initialize).parameters.any?
+                   klass.new(**job.args.transform_keys(&:to_sym))
+                 else
+                   klass.new
+                 end
+        call   = Textus::Call.build(
+          role: job.enqueued_by || Textus::Role::AUTOMATION,
+          correlation_id: SecureRandom.uuid,
+        )
+        action.call(container: @container, call: call)
+        @queue.ack(leased)
+        :completed
+      rescue StandardError => e
+        @queue.fail(leased, error: e.message)
+      end
+    end
+  end
+end

data/lib/textus/boot.rb

@@ -1,7 +1,7 @@
 module Textus
   # Read-only "what's in this store and how do I use it" envelope.
   # A single call gives an agent the working model of a textus-managed
-  # project: zones and their write authority, entries and their flags,
+  # project: lanes and their write authority, entries and their flags,
   # registered hooks, write flows, and the CLI verb catalog.
   #
   # Boot is side-effect-free.
@@ -10,25 +10,25 @@ module Textus
 
     # Per-capability write-flow templates. Each lambda receives the user-facing
     # role name and the manifest, and returns guidance for that verb with the
-    # live zone named by kind (ADR 0034). A role holding multiple verbs gets one
+    # live lane named by kind (ADR 0034). A role holding multiple verbs gets one
     # joined string; roles whose verbs have no template are omitted.
     WRITE_FLOW_TEMPLATES = {
       author: lambda do |name, manifest|
-        "edit files in #{zone_label(manifest, :canon, "your canon zone")}, " \
+        "edit files in #{lane_label(manifest, :canon, "your canon lane")}, " \
           "then 'textus put KEY --as=#{name}'"
       end,
       keep: lambda do |name, manifest|
-        "keep durable notes in #{zone_label(manifest, :workspace, "your workspace")}: " \
+        "keep durable notes in #{lane_label(manifest, :workspace, "your workspace")}: " \
           "'textus put KEY --as=#{name}' (no accept needed)"
       end,
       propose: lambda do |name, manifest|
         authority = manifest.policy.roles_with_capability("author").first || "the author-holder"
-        "propose changes by writing #{manifest.policy.queue_zone}.* entries with --as=#{name} " \
+        "propose changes by writing #{manifest.policy.queue_lane}.* entries with --as=#{name} " \
           "and a 'proposal:' frontmatter block; the #{authority} role runs 'textus accept' to apply"
       end,
-      reconcile: lambda do |_name, manifest|
-        machine = zone_label(manifest, :machine, "machine")
-        "'textus reconcile' materializes derived #{machine} entries from their sources and " \
+      converge: lambda do |_name, manifest|
+        machine = lane_label(manifest, :machine, "machine")
+        "'textus drain' materializes derived #{machine} entries from their sources and " \
           "refreshes stale intake #{machine} entries from their declared source; " \
           "derived files are never hand-edited (reactive on canon writes, or a full pass on demand)"
       end,
@@ -44,17 +44,17 @@ module Textus
       end
     end
 
-    # Human-readable name(s) for the live zone(s) of a given kind, or `fallback`
+    # Human-readable name(s) for the live lane(s) of a given kind, or `fallback`
     # when the manifest declares none. Lets write-flow guidance name the live
-    # zone by kind instead of a hardcoded instance name (ADR 0034).
-    def self.zone_label(manifest, kind, fallback)
-      zones = manifest.policy.zones_of_kind(kind)
-      zones.empty? ? fallback : zones.join(", ")
+    # lane by kind instead of a hardcoded instance name (ADR 0034).
+    def self.lane_label(manifest, kind, fallback)
+      lanes = manifest.policy.lanes_of_kind(kind)
+      lanes.empty? ? fallback : lanes.join(", ")
     end
 
     # Static, store-independent parts of the agent-facing protocol. The
     # `recipes` and `role_resolution` blocks are derived per-manifest in
-    # agent_protocol(...) because zone and role names are user-configurable.
+    # agent_protocol(...) because lane and 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",
@@ -84,23 +84,23 @@ module Textus
       { "name" => "put" },
       { "name" => "propose" },
       { "name" => "accept" },
+      { "name" => "enqueue" },
       { "name" => "key", "summary" => "key operations: 'key delete', 'key mv', 'key uid'" },
-      { "name" => "reconcile" },
+      { "name" => "drain" },
       { "name" => "audit" },
       { "name" => "blame" },
       { "name" => "rule", "summary" => "inspect effective rules: 'rule list', 'rule explain KEY'" },
       { "name" => "doctor" },
-      { "name" => "hook", "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
+      { "name" => "jobs" },
       { "name" => "pulse" },
-      { "name" => "capabilities" },
     ].freeze
 
     # verb token => contract.summary, for every Dispatcher verb that carries a
     # contract. The single source for a verb's one-line summary (ADR 0039).
     def self.contract_summaries
-      Dispatcher::VERBS.values
-                       .select { |k| k.respond_to?(:contract?) && k.contract? }
-                       .to_h { |k| [k.contract.verb.to_s, k.contract.summary] }
+      Textus::Action::VERBS.values
+                           .select { |k| k.respond_to?(:contract?) && k.contract? }
+                           .to_h { |k| [k.contract.verb.to_s, k.contract.summary] }
     end
 
     # Build the CLI verb catalog: each summary is derived from its contract when
@@ -117,11 +117,15 @@ module Textus
     def self.agent_quickstart(manifest, audit_log)
       agent_role = manifest.policy.proposer_role
 
-      writable_zones = manifest.data.declared_zone_kinds.keys.each_with_object([]) do |zname, acc|
-        acc << zname if agent_role && manifest.policy.zone_writers(zname).include?(agent_role)
+      writable_lanes = manifest.data.declared_lane_kinds.keys.each_with_object([]) do |lane_name, acc|
+        next unless agent_role
+
+        verb = manifest.policy.verb_for_lane(lane_name)
+        writers = manifest.policy.roles_with_capability(verb)
+        acc << lane_name if writers.include?(agent_role)
       end
 
-      propose_zone = manifest.policy.propose_zone_for(agent_role)
+      propose_lane = manifest.policy.propose_lane_for(agent_role)
 
       {
         # Both verb lists derive from the MCP catalog (ADR 0056, ADR 0057): the
@@ -131,11 +135,11 @@ module Textus
         # internal scan, ADR 0085) nor omit one it can
         # (schema_show/rules); write_verbs drops the old `put KEY --as=… --stdin` CLI
         # framing (role is connection-resolved over MCP; there is no stdin).
-        # writable_zones / propose_zone below carry the agent's write authority.
-        "read_verbs" => Textus::MCP::Catalog.read_verbs,
-        "write_verbs" => agent_role ? Textus::MCP::Catalog.write_verbs : [],
-        "writable_zones" => writable_zones,
-        "propose_zone" => propose_zone,
+        # writable_lanes / propose_lane below carry the agent's write authority.
+        "read_verbs" => Textus::Surfaces::MCP::Catalog.read_verbs,
+        "write_verbs" => agent_role ? Textus::Surfaces::MCP::Catalog.write_verbs : [],
+        "writable_lanes" => writable_lanes,
+        "propose_lane" => propose_lane,
         "latest_seq" => audit_log.latest_seq,
       }
     end
@@ -145,13 +149,13 @@ module Textus
     # `textus get KEY`, MCP as the `get` tool) or is a plain materialize step. This
     # keeps shell lines out of the surface an MCP agent reads.
     def self.recipes(manifest)
-      queue = manifest.policy.queue_zone
-      feeds = zone_label(manifest, :machine, "the machine zone")
+      queue = manifest.policy.queue_lane
+      feeds = lane_label(manifest, :machine, "the machine lane")
       {
         "read" => {
           "purpose" => "find and read an entry",
           "steps" => [
-            "list (zone:, prefix:) — discover keys without reading bodies",
+            "list (lane:, prefix:) — discover keys without reading bodies",
             "get KEY — returns the entry envelope",
           ],
         },
@@ -166,17 +170,17 @@ module Textus
         "propose" => {
           "purpose" => "agent suggests a change for human review",
           "agent_steps" => [
-            "propose KEY — writes the change into the #{queue} zone for review",
+            "propose KEY — writes the change into the #{queue} lane for review",
           ],
           "human_steps" => [
-            "accept #{queue}.KEY — promotes the proposal into its target zone",
+            "accept #{queue}.KEY — promotes the proposal into its target lane",
           ],
         },
-        "reconcile" => {
+        "drain" => {
           "purpose" => "keep the machine-maintained lanes fresh — re-pull stale intake entries from their declared source",
           "steps" => [
             "pulse — its `stale` list names entries past their ttl",
-            "reconcile (zone: #{feeds}) — re-pull the stale entries",
+            "drain (lane: #{feeds}) — re-pull the stale entries",
           ],
         },
       }
@@ -202,7 +206,7 @@ module Textus
         return {
           "protocol" => PROTOCOL_ID,
           "store_root" => container.root,
-          "zones" => zones_for(manifest),
+          "lanes" => lanes_for(manifest),
           "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
           "contract_etag" => etag,
         }
@@ -211,7 +215,7 @@ module Textus
       {
         "protocol" => PROTOCOL_ID,
         "store_root" => container.root,
-        "zones" => zones_for(manifest),
+        "lanes" => lanes_for(manifest),
         "entries" => entries_for(manifest),
         "hooks" => hooks_for_container(container),
         "write_flows" => write_flows_for(manifest),
@@ -219,16 +223,17 @@ module Textus
         "agent_protocol" => agent_protocol(manifest),
         "agent_quickstart" => agent_quickstart(manifest, container.audit_log),
         "contract_etag" => etag,
-        "docs" => { "spec" => "SPEC.md", "example" => "examples/project/" },
+        "docs" => { "spec" => "SPEC.md", "example" => ".textus/" },
       }
     end
 
-    def self.zones_for(manifest)
-      manifest.data.declared_zone_kinds.keys.map do |name|
-        row = { "name" => name, "writers" => manifest.policy.zone_writers(name) }
+    def self.lanes_for(manifest)
+      manifest.data.declared_lane_kinds.keys.map do |name|
+        verb = manifest.policy.verb_for_lane(name)
+        row = { "name" => name, "writers" => manifest.policy.roles_with_capability(verb) }
         kind = manifest.policy.declared_kind(name)
         row["kind"] = kind.to_s if kind
-        purpose = manifest.data.zone_descs[name]
+        purpose = manifest.data.lane_descs[name]
         row["purpose"] = purpose if purpose && !purpose.empty?
         row
       end
@@ -239,7 +244,7 @@ module Textus
         derived = e.derived?
         {
           "key" => e.key,
-          "zone" => e.zone,
+          "lane" => e.lane,
           "schema" => e.schema,
           "nested" => e.is_a?(Textus::Manifest::Entry::Nested),
           "owner" => e.owner,
@@ -252,16 +257,21 @@ module Textus
     end
 
     def self.hooks_for_container(container)
-      hooks_for_container_internal(rpc: container.rpc, events: container.events)
+      hooks_for_container_internal(steps: container.steps)
     end
 
-    def self.hooks_for_container_internal(rpc:, events:)
+    def self.hooks_for_container_internal(steps:)
       sections = {}
-      Hooks::Catalog::RPC.each_key do |event|
-        sections[event.to_s] = rpc.names(event).map(&:to_s).sort
+      rpc_kind_map = {
+        resolve_handler: :fetch,
+        transform_rows: :transform,
+        validate: :validate,
+      }
+      Step::Catalog::RPC.each_key do |event|
+        sections[event.to_s] = steps.names(rpc_kind_map.fetch(event)).map(&:to_s).sort
       end
-      Hooks::Catalog::PUBSUB.each_key do |event|
-        sections[event.to_s] = events.pubsub_handlers(event).map { |h| h[:name].to_s }.sort
+      Step::Catalog::PUBSUB.each_key do |event|
+        sections[event.to_s] = steps.pubsub_handlers(event).map { |h| h[:name].to_s }.sort
       end
       sections
     end

data/lib/textus/command.rb

@@ -0,0 +1,36 @@
+module Textus
+  module Command
+    Get             = Data.define(:key, :role)
+    Put             = Data.define(:key, :meta, :body, :content, :if_etag, :role)
+    Propose         = Data.define(:key, :meta, :body, :content, :role, :pending_key) do
+      def initialize(key:, role:, meta: nil, body: nil, content: nil, pending_key: nil)
+        super
+      end
+    end
+    KeyDelete       = Data.define(:key, :if_etag, :role)
+    KeyMv           = Data.define(:old_key, :new_key, :dry_run, :role)
+    Accept          = Data.define(:pending_key, :role)
+    Reject          = Data.define(:pending_key, :role)
+    Enqueue         = Data.define(:type, :args, :role)
+    List            = Data.define(:prefix, :lane, :role)
+    Where           = Data.define(:key, :role)
+    Uid             = Data.define(:key, :role)
+    Blame           = Data.define(:key, :limit, :role)
+    Audit           = Data.define(:key, :lane, :verb, :since, :seq_since, :correlation_id, :limit, :role)
+    Deps            = Data.define(:key, :role)
+    Rdeps           = Data.define(:key, :role)
+    Pulse           = Data.define(:since, :role)
+    RuleExplain     = Data.define(:key, :detail, :role)
+    RuleList        = Data.define(:role)
+    RuleLint        = Data.define(:candidate_yaml, :role)
+    Published       = Data.define(:role)
+    SchemaShow      = Data.define(:key, :role)
+    Doctor          = Data.define(:checks, :role)
+    Boot            = Data.define(:lean, :role)
+    Jobs            = Data.define(:state, :action, :job_id, :role)
+    DataMv          = Data.define(:from, :to, :dry_run, :role)
+    KeyMvPrefix     = Data.define(:from_prefix, :to_prefix, :dry_run, :role)
+    KeyDeletePrefix = Data.define(:prefix, :dry_run, :role)
+    Drain           = Data.define(:prefix, :lane, :role)
+  end
+end

data/lib/textus/container.rb

@@ -5,6 +5,6 @@ module Textus
   # so this `Data.define` is the single source of truth for the field set.
   Container = Data.define(
     :manifest, :file_store, :schemas, :root,
-    :audit_log, :events, :rpc
+    :audit_log, :steps, :gate
   )
 end

data/lib/textus/{domain → core}/duration.rb

@@ -1,5 +1,5 @@
 module Textus
-  module Domain
+  module Core
     # Parses a duration value into whole seconds. Accepts a bare integer (or
     # integer-string) of seconds, or `<n><unit>` with unit s/m/h/d. Returns
     # nil for nil or any unparseable value.

data/lib/textus/{domain → core}/freshness/evaluator.rb

@@ -1,17 +1,17 @@
 require "time"
 
 module Textus
-  module Domain
+  module Core
     module Freshness
       # The single currency evaluator (ADR 0099). Answers "is the stored data
       # stale relative to its source?" for every produce-method:
-      #   - intake (source.from: handler) -> AGE signal: now - basis > source.ttl,
+      #   - intake (source.from: fetch) -> AGE signal: now - basis > source.ttl,
       #     basis = _meta.last_fetched_at (else file mtime). No ttl -> :no_policy
       #     (skipped — a cadence-less handler is not auto-re-pulled).
-      #   - derived/external -> DRIFT signal: a source changed since generated.at
+      #   - external -> DRIFT signal: a source changed since generated.at
       #     (surfaced by the doctor generator_drift check; derived entries annotate
-      #     fresh at read time because reconcile converges them reactively).
-      # Replaces Domain::IntakeStaleness and Domain::Staleness::GeneratorCheck and
+      #     fresh at read time because converge runs them reactively).
+      # Replaces Core::IntakeStaleness and Core::Staleness::GeneratorCheck and
       # the inline copies in Read::Get / Read::Freshness.
       class Evaluator
         def initialize(manifest:, file_stat:, clock:)
@@ -32,11 +32,11 @@ module Textus
           Verdict.build(stale: stale, reason: stale ? "ttl exceeded" : nil, fetching: false)
         end
 
-        # Keys of intake entries past their source.ttl — the reconcile produce
-        # scope (replaces Domain::IntakeStaleness#call). A ttl-less intake entry
+        # Keys of intake entries past their source.ttl — the converge produce
+        # scope (replaces Core::IntakeStaleness#call). A ttl-less intake entry
         # is :no_policy and skipped; a never-recorded one (with a ttl) is stale.
-        def stale_intake_keys(prefix: nil, zone: nil)
-          @manifest.data.entries.select { |m| due?(m, prefix: prefix, zone: zone) }.map(&:key)
+        def stale_intake_keys(prefix: nil, lane: nil)
+          @manifest.data.entries.select { |m| due?(m, prefix: prefix, lane: lane) }.map(&:key)
         end
 
         # Age basis as a Time (or nil): _meta.last_fetched_at when present, else
@@ -62,9 +62,9 @@ module Textus
 
         def fresh = Verdict.build(stale: false, reason: nil, fetching: false)
 
-        def due?(mentry, prefix:, zone:)
+        def due?(mentry, prefix:, lane:)
           return false unless mentry.intake?
-          return false if zone && mentry.zone != zone
+          return false if lane && mentry.lane != lane
           return false if prefix && !mentry.key.start_with?(prefix)
 
           ttl = mentry.source.ttl_seconds
@@ -92,7 +92,7 @@ module Textus
 
         # --- generator drift (lifted from Staleness::GeneratorCheck) ---
 
-        def drift_applicable?(mentry) = mentry.derived? && mentry.external?
+        def drift_applicable?(mentry) = mentry.external?
 
         def drift_reason(mentry, path)
           return "derived entry has never been generated" unless @file_stat.exists?(path)
@@ -158,7 +158,7 @@ module Textus
         def file?(fpath) = !@file_stat.directory?(fpath) && @file_stat.exists?(fpath)
 
         def drift_row(mentry, path, reason)
-          { "key" => mentry.key, "path" => path, "generator" => mentry.raw["compute"], "reason" => reason }
+          { "key" => mentry.key, "path" => path, "generator" => mentry.source.command, "reason" => reason }
         end
       end
     end

data/lib/textus/{domain → core}/freshness/verdict.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module Textus
-  module Domain
+  module Core
     module Freshness
       # Value object describing the freshness annotation attached to an Envelope
-      # after a currency evaluation (ADR 0099 — was Domain::Freshness).
+      # after a currency evaluation (ADR 0099 — was Core::Freshness).
       #
       # Note on wire format: `#to_h_for_wire` is intentionally narrower than the
       # full field set. It emits the legacy keys ("stale", "stale_reason",

data/lib/textus/{domain → core}/freshness.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module Textus
-  module Domain
+  module Core
     # Currency — "is the stored data stale relative to its source?" (ADR 0099).
     # The home of the single Freshness evaluator and its Verdict value object.
-    # Distinct from Domain::Retention (GC dueness, Q2).
+    # Distinct from Core::Retention (GC dueness, Q2).
     module Freshness
     end
   end

data/lib/textus/{domain → core}/retention/sweep.rb

@@ -1,12 +1,12 @@
 require "time"
 
 module Textus
-  module Domain
+  module Core
     module Retention
       # Retention sweep reporter (ADR 0093/0099). Which entries are past their
       # `retention:` ttl and the destructive action that applies. Age basis: file
-      # mtime. Only drop/archive. Renamed off the Domain::Retention vs
-      # Domain::Policy::Retention collision (ADR 0099).
+      # mtime. Only drop/archive. Renamed off the Core::Retention vs
+      # Manifest::Policy::Retention collision (ADR 0099).
       class Sweep
         def self.expired?(ttl_seconds:, mtime:, now:)
           return false if ttl_seconds.nil? || mtime.nil?
@@ -20,16 +20,16 @@ module Textus
           @clock = clock
         end
 
-        def call(prefix: nil, zone: nil)
+        def call(prefix: nil, lane: nil)
           @manifest.data.entries
-                   .select { |m| matches?(m, prefix: prefix, zone: zone) }
+                   .select { |m| matches?(m, prefix: prefix, lane: lane) }
                    .flat_map { |m| rows_for(m) }
         end
 
         private
 
-        def matches?(mentry, prefix:, zone:)
-          return false if zone && mentry.zone != zone
+        def matches?(mentry, prefix:, lane:)
+          return false if lane && mentry.lane != lane
           return false if prefix && !Textus::Key::Matching.matches_prefix?(
             mentry.key, prefix, nested: mentry.is_a?(Textus::Manifest::Entry::Nested)
           )

data/lib/textus/{domain → core}/retention.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module Textus
-  module Domain
+  module Core
     # Retention — "is the entry old enough to retire?" (Q2, ADR 0093/0099).
     # GC dueness, orthogonal to Freshness (content currency). The reporter is
-    # Domain::Retention::Sweep; the manifest rule policy is Domain::Policy::Retention.
+    # Core::Retention::Sweep; the manifest rule policy is Manifest::Policy::Retention.
     module Retention
     end
   end

data/lib/textus/{domain → core}/sentinel.rb

@@ -1,7 +1,7 @@
 require "digest"
 
 module Textus
-  module Domain
+  module Core
     # Pure value object representing a published-file sentinel. Holds the
     # recorded target path, source path, sha256 checksum, and publish mode.
     # Has no filesystem I/O — path layout and persistence live in

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

@@ -8,7 +8,7 @@ module Textus
       # verb reported.
       class GeneratorDrift < Check
         def call
-          gen = Textus::Domain::Freshness::Evaluator.new(
+          gen = Textus::Core::Freshness::Evaluator.new(
             manifest: manifest,
             file_stat: Textus::Ports::Storage::FileStat.new,
             clock: Textus::Ports::Clock.new,
@@ -19,7 +19,7 @@ module Textus
               "level" => "warning",
               "subject" => row["key"],
               "message" => row["reason"],
-              "fix" => "rematerialize the entry: `textus reconcile`",
+              "fix" => "rematerialize the entry: `textus drain`",
             }
           end
         end

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

@@ -0,0 +1,34 @@
+module Textus
+  module Doctor
+    class Check
+      # For every entry with a fetch handler, look up its handler_permit policy
+      # (if any) and verify the declared handler is permitted. Emits a failure
+      # when the handler is rejected by policy.
+      class HandlerPermit < Check
+        def call
+          out = []
+          manifest.data.entries.each do |mentry|
+            next unless mentry.intake?
+
+            handler = mentry.handler
+
+            permit = manifest.rules.for(mentry.key).handler_permit
+            next if permit.nil?
+            next if permit.permits?(handler)
+
+            out << {
+              "code" => "policy.handler_not_permitted",
+              "level" => "error",
+              "subject" => mentry.key,
+              "message" => "entry '#{mentry.key}' declares source.handler='#{handler}' but " \
+                           "handler_permit allows only: #{permit.handlers.join(", ")}",
+              "fix" => "change handler to one of [#{permit.handlers.join(", ")}] or " \
+                       "extend handler_permit in .textus/manifest.yaml",
+            }
+          end
+          out
+        end
+      end
+    end
+  end
+end

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

@@ -4,26 +4,19 @@ module Textus
       class Hooks < Check
         def call
           out = []
-          dir = File.join(root, "hooks")
+          dir = File.join(root, "steps")
           return out unless File.directory?(dir)
 
-          Dir.glob(File.join(dir, "*.rb")).sort.each do |f| # rubocop:disable Lint/RedundantDirGlobSort
-            events = Textus::Hooks::EventBus.new
-            rpc    = Textus::Hooks::RpcRegistry.new
-            Textus.drain_hook_blocks
-            begin
-              load(f)
-              Textus.drain_hook_blocks.each { |b| b.call(Textus::Hooks::Loader::Dsl.new(events: events, rpc: rpc)) }
-            end
-          rescue StandardError, ScriptError => e
-            out << {
-              "code" => "hook.load_failed",
-              "level" => "error",
-              "subject" => File.basename(f),
-              "message" => "#{e.class}: #{e.message}",
-              "fix" => "open #{f} and fix the syntax/load error",
-            }
-          end
+          Textus::Step::Loader.new(registry: Textus::Step::RegistryStore.new).load_dir(dir)
+          out
+        rescue Textus::UsageError => e
+          out << {
+            "code" => "step.load_failed",
+            "level" => "error",
+            "subject" => "steps",
+            "message" => e.message,
+            "fix" => "open the named step file under .textus/steps/ and fix the error",
+          }
           out
         end
       end

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

@@ -8,7 +8,7 @@ module Textus
             next unless entry.nested?
             next if entry.publish_mode.keyless? # publish_tree files are opaque payload, never keys (ADR 0047)
 
-            base = File.join(root, "zones", entry.path)
+            base = File.join(root, Textus::Key::Path.normalize_relative_path(entry.path))
             next unless File.directory?(base)
 
             check_all_paths(entry, base, out)