textus 0.52.0 → 0.53.0

data/lib/textus/gate.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Textus
+  class Gate
+    VERB_COMMAND = {
+      get: Textus::Command::Get,
+      put: Textus::Command::Put,
+      propose: Textus::Command::Propose,
+      key_delete: Textus::Command::KeyDelete,
+      key_mv: Textus::Command::KeyMv,
+      accept: Textus::Command::Accept,
+      reject: Textus::Command::Reject,
+      enqueue: Textus::Command::Enqueue,
+      list: Textus::Command::List,
+      where: Textus::Command::Where,
+      uid: Textus::Command::Uid,
+      blame: Textus::Command::Blame,
+      audit: Textus::Command::Audit,
+      deps: Textus::Command::Deps,
+      rdeps: Textus::Command::Rdeps,
+      pulse: Textus::Command::Pulse,
+      rule_explain: Textus::Command::RuleExplain,
+      rule_list: Textus::Command::RuleList,
+      rule_lint: Textus::Command::RuleLint,
+      published: Textus::Command::Published,
+      schema_show: Textus::Command::SchemaShow,
+      doctor: Textus::Command::Doctor,
+      boot: Textus::Command::Boot,
+      jobs: Textus::Command::Jobs,
+      data_mv: Textus::Command::DataMv,
+      key_mv_prefix: Textus::Command::KeyMvPrefix,
+      key_delete_prefix: Textus::Command::KeyDeletePrefix,
+      drain: Textus::Command::Drain,
+    }.freeze
+
+    ROUTES = {
+      Command::Get => [Textus::Action::Get],
+      Command::Put => [Textus::Action::Put],
+      Command::Propose => [Textus::Action::Propose],
+      Command::KeyDelete => [Textus::Action::KeyDelete],
+      Command::KeyMv => [Textus::Action::KeyMv],
+      Command::Accept => [Textus::Action::Accept],
+      Command::Reject => [Textus::Action::Reject],
+      Command::Enqueue => [Textus::Action::Enqueue],
+      Command::List => [Textus::Action::List],
+      Command::Where => [Textus::Action::Where],
+      Command::Uid => [Textus::Action::Uid],
+      Command::Blame => [Textus::Action::Blame],
+      Command::Audit => [Textus::Action::Audit],
+      Command::Deps => [Textus::Action::Deps],
+      Command::Rdeps => [Textus::Action::Rdeps],
+      Command::Pulse => [Textus::Action::Pulse],
+      Command::RuleExplain => [Textus::Action::RuleExplain],
+      Command::RuleList => [Textus::Action::RuleList],
+      Command::RuleLint => [Textus::Action::RuleLint],
+      Command::Published => [Textus::Action::Published],
+      Command::SchemaShow => [Textus::Action::SchemaEnvelope],
+      Command::Doctor => [Textus::Action::Doctor],
+      Command::Boot => [Textus::Action::Boot],
+      Command::Jobs => [Textus::Action::Jobs],
+      Command::DataMv => [Textus::Action::DataMv],
+      Command::KeyMvPrefix => [Textus::Action::KeyMvPrefix],
+      Command::KeyDeletePrefix => [Textus::Action::KeyDeletePrefix],
+      Command::Drain => [Textus::Action::Drain],
+    }.freeze
+
+    def initialize(container)
+      @container = container
+    end
+
+    def dispatch(cmd, correlation_id: nil)
+      cmd = normalize_propose_key(cmd, @container) if cmd.is_a?(Command::Propose)
+      action_classes = ROUTES.fetch(cmd.class) do
+        raise Textus::UsageError.new("unknown command: #{cmd.class}")
+      end
+
+      Gate::Auth.new(@container).check!(cmd)
+      call_obj = build_call(cmd, correlation_id: correlation_id)
+      results = action_classes.map { |klass| run_action(klass, cmd, @container, call_obj) }
+      results.length == 1 ? results.first : results
+    end
+
+    private
+
+    def normalize_propose_key(cmd, container)
+      return cmd if cmd.pending_key
+
+      zone = container.manifest.policy.propose_lane_for(cmd.role.to_s)
+      cmd.with(pending_key: zone ? "#{zone}.#{cmd.key}" : nil)
+    end
+
+    def run_action(klass, cmd, container, call_obj)
+      action = klass.new(**extract_kwargs(klass, cmd))
+      action.call(container:, call: call_obj)
+    end
+
+    def extract_kwargs(klass, cmd)
+      params = klass.instance_method(:initialize).parameters
+      accepts_keyrest = params.any? { |t, _| t == :keyrest }
+      param_set = params.to_set { |_t, n| n }
+      cmd.members.each_with_object({}) do |m, h|
+        next unless accepts_keyrest || param_set.include?(m)
+
+        val = cmd.public_send(m)
+        h[m] = val unless val.nil?
+      end
+    end
+
+    def build_call(cmd, correlation_id: nil)
+      dry_run = cmd.respond_to?(:dry_run) ? !cmd.dry_run.nil? : false
+      Textus::Call.build(role: cmd.role, dry_run:, correlation_id: correlation_id)
+    end
+  end
+end

data/lib/textus/init/templates/machine_intake.rb

@@ -1,4 +1,4 @@
-# .textus/hooks/machine_intake.rb
+# .textus/steps/fetch/machine_intake.rb
 # Scaffolded by `textus init` — CUSTOMIZE FREELY, or delete the feeds.machines
 # entry from manifest.yaml if you don't want it.
 # Feeds a per-host SNAPSHOT into feeds.machines.<host> on `textus drain`
@@ -6,40 +6,44 @@
 # `local` leaf scans THIS host; add ssh hosts with the cookbook recipe
 # (docs/cookbook/environment-scan.md). tracked:false → gitignored. Keep this an
 # ALLOWLIST of versions and counts — NEVER secrets, raw `env`, or package lists.
-Textus.hook do |reg|
-  reg.on(:resolve_handler, :machines) do |config:, args:, **|
-    machine = args[:leaf_segments].first or
-      raise "machines intake needs a host leaf, e.g. the 'local' in feeds.machines.local"
-    spec = (config["machines"] || {}).fetch(machine) { raise "unknown machine: #{machine}" }
-    unless (spec["via"] || "local").to_s == "local"
-      raise "machine #{machine}: only `via: local` is scaffolded — see " \
-            "docs/cookbook/environment-scan.md for the SSH (remote) fan-out"
-    end
+module Textus
+  module Step
+    class MachineIntakeFetch < Fetch
+      def call(config:, args:, caps:, **)
+        machine = args[:leaf_segments].first or
+          raise "machines intake needs a host leaf, e.g. the 'local' in feeds.machines.local"
+        spec = (config["machines"] || {}).fetch(machine) { raise "unknown machine: #{machine}" }
+        unless (spec["via"] || "local").to_s == "local"
+          raise "machine #{machine}: only `via: local` is scaffolded — see " \
+                "docs/cookbook/environment-scan.md for the SSH (remote) fan-out"
+        end
 
-    sh    = ->(cmd) { `#{cmd}`.strip }                      # local shell-out, no network
-    ver   = ->(cmd) { o = `#{cmd} 2>/dev/null`.strip; o.empty? ? nil : o } # nil if tool absent
-    count = ->(cmd) { n = `#{cmd} 2>/dev/null`.strip.lines.size; n.zero? ? nil : n }
-    { content: {
-      # git_* describe THIS repo on the control host — only meaningful for `local`.
-      "git_head"       => sh.call("git rev-parse --short HEAD 2>/dev/null"),
-      "git_branch"     => sh.call("git rev-parse --abbrev-ref HEAD 2>/dev/null"),
-      "git_dirty"      => !sh.call("git status --porcelain 2>/dev/null").empty?,
-      "repo_root"      => sh.call("git rev-parse --show-toplevel 2>/dev/null"),
-      "captured_at"    => Time.now.utc.iso8601,
-      "os"             => RbConfig::CONFIG["host_os"],
-      "arch"           => RbConfig::CONFIG["host_cpu"],
-      "ruby_version"   => RUBY_VERSION,
-      "runtimes"       => {                                 # versions only; nil when not installed
-        "node"   => ver.call("node --version"),
-        "python" => ver.call("python3 --version"),
-        "go"     => ver.call("go version"),
-      },
-      "packages"       => {                                 # COUNTS only — never the list (size/secrets)
-        "brew" => count.call("brew list --formula"),        # ~1-3s on macOS; runs only on fetch, amortized by the ttl rule
-        "apt"  => count.call("dpkg-query -f '.\n' -W"),
-      },
-      "textus_version" => Textus::VERSION,
-      "protocol"       => Textus::PROTOCOL,
-    } }
+        sh    = ->(cmd) { `#{cmd}`.strip }                      # local shell-out, no network
+        ver   = ->(cmd) { o = `#{cmd} 2>/dev/null`.strip; o.empty? ? nil : o } # nil if tool absent
+        count = ->(cmd) { n = `#{cmd} 2>/dev/null`.strip.lines.size; n.zero? ? nil : n }
+        { content: {
+          # git_* describe THIS repo on the control host — only meaningful for `local`.
+          "git_head"       => sh.call("git rev-parse --short HEAD 2>/dev/null"),
+          "git_branch"     => sh.call("git rev-parse --abbrev-ref HEAD 2>/dev/null"),
+          "git_dirty"      => !sh.call("git status --porcelain 2>/dev/null").empty?,
+          "repo_root"      => sh.call("git rev-parse --show-toplevel 2>/dev/null"),
+          "captured_at"    => Time.now.utc.iso8601,
+          "os"             => RbConfig::CONFIG["host_os"],
+          "arch"           => RbConfig::CONFIG["host_cpu"],
+          "ruby_version"   => RUBY_VERSION,
+          "runtimes"       => {                                 # versions only; nil when not installed
+            "node"   => ver.call("node --version"),
+            "python" => ver.call("python3 --version"),
+            "go"     => ver.call("go version"),
+          },
+          "packages"       => {                                 # COUNTS only — never the list (size/secrets)
+            "brew" => count.call("brew list --formula"),        # ~1-3s on macOS; runs only on fetch, amortized by the ttl rule
+            "apt"  => count.call("dpkg-query -f '.\n' -W"),
+          },
+          "textus_version" => Textus::VERSION,
+          "protocol"       => Textus::PROTOCOL,
+        } }
+      end
+    end
   end
 end

data/lib/textus/init/templates/orientation_reducer.rb

@@ -1,17 +1,21 @@
 # Reducer that reshapes the raw projection rows into the keys the
 # orientation.mustache template references. Without this, the template
 # would only have access to the flat rows list.
-Textus.hook do |reg|
-  reg.on(:transform_rows, :orientation_reducer) do |rows:, **|
-    project_row = rows.find { |r| r["_key"] == "knowledge.project" } || {}
-    runbook_rows = rows.select { |r| r["_key"]&.start_with?("knowledge.runbooks.") }
+module Textus
+  module Step
+    class OrientationTransform < Transform
+      def call(rows:, config:, **)
+        project_row = rows.find { |r| r["_key"] == "knowledge.project" } || {}
+        runbook_rows = rows.select { |r| r["_key"]&.start_with?("knowledge.runbooks.") }
 
-    {
-      "project" => {
-        "name" => project_row["name"],
-        "description" => project_row["description"]
-      },
-      "runbooks" => runbook_rows.map { |r| { "name" => r["name"], "description" => r["description"] } }
-    }
+        {
+          "project" => {
+            "name" => project_row["name"],
+            "description" => project_row["description"]
+          },
+          "runbooks" => runbook_rows.map { |r| { "name" => r["name"], "description" => r["description"] } }
+        }
+      end
+    end
   end
 end

data/lib/textus/init.rb

@@ -11,31 +11,31 @@ module Textus
         - { name: human,      can: [author, propose] }
         - { name: agent,      can: [propose, keep] }
         - { name: automation, can: [converge] }
-      zones:
+      lanes:
         - { name: knowledge, kind: canon,     desc: "the maintained source of truth (identity.* lives here)" }
         - { name: notebook,  kind: workspace, owner: agent, desc: "the agent's own durable working notes" }
         - { name: proposals, kind: queue,     desc: "changes awaiting your accept" }
         - { name: artifacts, kind: machine,   desc: "machine-maintained: external inputs (artifacts.feeds.*) + computed outputs (artifacts.derived.*)" }
       entries:
-        - { key: knowledge.identity, path: knowledge/identity.md, zone: knowledge, schema: null, owner: human:self, kind: leaf }
-        - { key: knowledge.notes,    path: knowledge/notes,       zone: knowledge, schema: null, owner: human:self, nested: true, kind: nested }
-        - { key: notebook.notes,     path: notebook/notes,        zone: notebook,  schema: null, owner: agent:self, nested: true, kind: nested }
-        - { key: proposals.notes,    path: proposals/notes,       zone: proposals, schema: null, owner: agent:self, nested: true, kind: nested }
+        - { key: knowledge.identity, path: data/knowledge/identity.md, lane: knowledge, schema: null, owner: human:self, kind: leaf }
+        - { key: knowledge.notes,    path: data/knowledge/notes,       lane: knowledge, schema: null, owner: human:self, nested: true, kind: nested }
+        - { key: notebook.notes,     path: data/notebook/notes,        lane: notebook,  schema: null, owner: agent:self, nested: true, kind: nested }
+        - { key: proposals.notes,    path: data/proposals/notes,       lane: proposals, schema: null, owner: agent:self, nested: true, kind: nested }
         # A per-host snapshot, refreshed from its declared intake by `textus drain` (scheduled, or on demand).
         # Nested so it grows to a fleet — add artifacts.feeds.machines.<host> leaves over SSH
         # (see docs/cookbook/environment-scan.md) without renaming. tracked:false →
         # gitignored (machine info can be sensitive/noisy) but still protocol-readable
         # via `textus get artifacts.feeds.machines.local`. Delete to opt out. (ADR 0043)
         - key: artifacts.feeds.machines
-          path: artifacts/feeds/machines
-          zone: artifacts
+          path: data/artifacts/feeds/machines
+          lane: artifacts
           format: yaml
           nested: true
           tracked: false
           kind: produced
           source:
-            from: handler
-            handler: machines
+            from: fetch
+            handler: machine-intake
             ttl: 1h # cadence on a long-running server
             config:
               machines:
@@ -43,57 +43,40 @@ module Textus
       rules: []
     YAML
 
-    HOOKS_README = <<~MD
-      # Hooks
+    STEPS_README = <<~MD
+      # Steps
 
-      Drop one Ruby file per hook. All hooks register through one DSL.
-      Files anywhere under `.textus/hooks/` (including subdirectories) are loaded at
-      startup in alphabetical order by full path. Subdirectory names are organizational
-      only — the registered event and name come from the DSL call, not the file path.
+      Drop one Ruby file per step. Steps are discovered by convention.
+      Files under `.textus/steps/<kind>/<name>.rb` are loaded at
+      startup and registered.
 
-      ## DSL
+      ## Conventions
 
-      ```ruby
-      Textus.hook do |reg|
-        reg.on(:resolve_handler, :my_source) do |config:, args:, **|
-          { _meta: { "last_fetched_at" => Time.now.utc.iso8601 }, body: "…" }
-        end
+      The directory name (`<kind>`) must be one of:
+      - `fetch`: Acquires data from outside the store.
+      - `transform`: Reshapes projection rows.
+      - `validate`: Validates data before writing.
+      - `observe`: Listens to store events.
 
-        reg.on(:transform_rows, :my_source) { |rows:, **| rows.map { |r| r.merge(processed: true) } }
-        reg.on(:validate,       :my_check)  { |caps:, **| [] }
-        reg.on(:entry_written,      :my_listener, keys: ["knowledge.*"]) { |key:, envelope:, **| }
+      The filename (`<name>.rb`) defines the step name. The class defined
+      in the file must be a subclass of `Textus::Step::<Kind>` (e.g.
+      `Textus::Step::Fetch`) and be wrapped in the `Textus::Step` module.
 
-        # Run a side-effect every time textus writes a file to your repo:
-        reg.on(:entry_published, :notify) do |key:, target:, **|
-          warn "wrote \#{target} (from \#{key})"
+      ## Example
+
+      ```ruby
+      module Textus
+        module Step
+          class MyFetch < Fetch
+            def call(config:, args:, caps:, **)
+              { content: { "foo" => "bar" } }
+            end
+          end
         end
       end
       ```
 
-      The intake handler above is paired with a manifest entry whose
-      `source:` block declares the handler and its refresh cadence
-      (`ttl`). Age GC (drop/archive) lives in a top-level `retention:`
-      rule, not on the entry:
-
-      ```yaml
-      entries:
-        - key: artifacts.feeds.foo
-          kind: produced
-          path: artifacts/feeds/foo.md
-          zone: artifacts
-          source:
-            from: handler
-            handler: my_source
-            ttl: 10m        # refresh cadence for this intake
-
-      rules:
-        - match: artifacts.feeds.foo
-          retention:
-            ttl: 30d
-            action: archive   # drop | archive (age GC of stored rows)
-      ```
-
-      Events: :resolve_handler, :transform_rows, :validate (rpc — return value used)
+      Events: :fetch, :transform, :validate (rpc — return value used)
               :entry_written, :entry_deleted, :entry_fetched, :entry_renamed,
               :entry_produced, :produce_failed,
               :proposal_accepted, :proposal_rejected,
@@ -104,50 +87,83 @@ module Textus
     MD
 
     AGENT_ENTRIES = <<~YAML.gsub(/^/, "  ")
-      # --with-agent profile: project facts + runbooks feed the orientation
-      # projection below, which `textus drain` renders to CLAUDE.md/AGENTS.md.
-      - { key: knowledge.project, path: knowledge/project.md, zone: knowledge, schema: project, owner: human:self, kind: leaf }
-      - { key: knowledge.runbooks, path: knowledge/runbooks, zone: knowledge, schema: runbook, owner: human:self, nested: true, kind: nested }
+      - { key: knowledge.project, path: data/knowledge/project.md, lane: knowledge, schema: project, owner: human:self, kind: leaf }
+      - { key: knowledge.runbooks, path: data/knowledge/runbooks, lane: knowledge, schema: runbook, owner: human:self, nested: true, kind: nested }
       - key: artifacts.derived.orientation
-        path: artifacts/derived/orientation.json
-        zone: artifacts
+        path: data/artifacts/derived/orientation.json
+        lane: artifacts
         publish:
         - { to: CLAUDE.md, template: orientation.mustache, inject_boot: true }
         - { to: AGENTS.md, template: orientation.mustache, inject_boot: true }
         source:
-          from: project
+          from: derive
           select:
           - knowledge.project
           - knowledge.runbooks
-          transform: orientation_reducer
+          transform: orientation
         kind: produced
     YAML
 
     def self.run(target_root, with_agent: false)
+      check_target!(target_root)
+      scaffold_dir = File.expand_path("init/templates", __dir__)
+      create_directories(target_root)
+      write_steps_readme(target_root, scaffold_dir)
+      write_manifest(target_root, with_agent:)
+      mcp_status = scaffold_agent(target_root, scaffold_dir, with_agent:)
+      setup_state_dirs(target_root)
+      write_gitignore(target_root)
+      build_result(target_root, with_agent:, mcp_status:)
+    end
+
+    def self.check_target!(target_root)
       raise UsageError.new(".textus/ already exists at #{target_root}") if File.directory?(target_root)
+    end
 
+    def self.create_directories(target_root)
       FileUtils.mkdir_p(File.join(target_root, "schemas"))
       FileUtils.mkdir_p(File.join(target_root, "templates"))
-      FileUtils.mkdir_p(File.join(target_root, "hooks"))
+      FileUtils.mkdir_p(File.join(target_root, "steps/fetch"))
+      FileUtils.mkdir_p(File.join(target_root, "steps/transform"))
+      FileUtils.mkdir_p(File.join(target_root, "steps/validate"))
+      FileUtils.mkdir_p(File.join(target_root, "steps/observe"))
       ZONES.each do |z|
-        dir = File.join(target_root, "zones", z)
+        dir = File.join(target_root, "data", z)
         FileUtils.mkdir_p(dir)
         File.write(File.join(dir, ".gitkeep"), "")
       end
-      File.write(File.join(target_root, "hooks", "README.md"), HOOKS_README)
-      scaffold_dir = File.expand_path("init/templates", __dir__)
-      File.write(File.join(target_root, "hooks", "machine_intake.rb"),
-                 File.read(File.join(scaffold_dir, "machine_intake.rb")))
+    end
+
+    def self.write_steps_readme(target_root, scaffold_dir)
+      File.write(File.join(target_root, "steps/README.md"), STEPS_README)
+      File.write(
+        File.join(target_root, "steps/fetch/machine-intake.rb"),
+        File.read(File.join(scaffold_dir, "machine_intake.rb")),
+      )
+    end
+
+    def self.write_manifest(target_root, with_agent:)
       File.write(File.join(target_root, "manifest.yaml"), manifest_yaml(with_agent: with_agent))
-      mcp_status = nil
-      if with_agent
-        scaffold_agent_profile(target_root, scaffold_dir)
-        mcp_status = write_mcp_config(target_root, scaffold_dir)
-      end
+    end
+
+    def self.scaffold_agent(target_root, scaffold_dir, with_agent:)
+      return nil unless with_agent
+
+      scaffold_agent_profile(target_root, scaffold_dir)
+      write_mcp_config(target_root, scaffold_dir)
+    end
+
+    def self.setup_state_dirs(target_root)
       FileUtils.mkdir_p(Textus::Layout.audit_dir(target_root))
       FileUtils.mkdir_p(Textus::Layout.state(target_root))
       FileUtils.mkdir_p(Textus::Layout.locks(target_root))
+    end
+
+    def self.write_gitignore(target_root)
       File.write(File.join(target_root, ".gitignore"), derived_gitignore(target_root))
+    end
+
+    def self.build_result(target_root, with_agent:, mcp_status:)
       result = { "protocol" => PROTOCOL, "initialized" => target_root, "profile" => with_agent ? "agent" : "default" }
       result["mcp_config"] = mcp_status if with_agent
       result
@@ -168,7 +184,7 @@ module Textus
         "project.schema.yaml" => File.join("schemas", "project.yaml"),
         "runbook.schema.yaml" => File.join("schemas", "runbook.yaml"),
         "orientation.mustache" => File.join("templates", "orientation.mustache"),
-        "orientation_reducer.rb" => File.join("hooks", "orientation_reducer.rb"),
+        "orientation_reducer.rb" => File.join("steps/transform", "orientation.rb"),
       }.each do |src, dest|
         File.write(File.join(target_root, dest), File.read(File.join(scaffold_dir, src)))
       end
@@ -193,8 +209,9 @@ module Textus
       manifest = Textus::Manifest.load(target_root)
       root = Pathname.new(target_root)
       untracked = manifest.data.entries.reject(&:tracked?).map do |e|
-        if e.nested? # a whole subtree of leaf files (artifacts.feeds.machines.* → zones/artifacts/feeds/machines/)
-          "#{File.join("zones", e.path)}/"
+        if e.nested? # a whole subtree of leaf files (artifacts.feeds.machines.* → data/artifacts/feeds/machines/)
+          rel = e.path.start_with?("data/") ? e.path : File.join("data", e.path)
+          "#{rel}/"
         else
           Pathname.new(Textus::Key::Path.resolve(manifest.data, e)).relative_path_from(root).to_s
         end

data/lib/textus/key/path.rb

@@ -10,12 +10,19 @@ module Textus
       # `manifest.data`.
       def self.resolve(data, mentry)
         primary_ext = Entry.for_format(mentry.format).extensions.first
+        rel_path = normalize_relative_path(mentry.path)
         if File.extname(mentry.path) == ""
-          File.join(data.root, "zones", mentry.path + primary_ext)
+          File.join(data.root, rel_path + primary_ext)
         else
-          File.join(data.root, "zones", mentry.path)
+          File.join(data.root, rel_path)
         end
       end
+
+      def self.normalize_relative_path(path)
+        return path if path.start_with?("data/")
+
+        File.join("data", path)
+      end
     end
   end
 end

data/lib/textus/layout.rb

@@ -4,6 +4,15 @@ module Textus
   # tracked/disposable boundary is a directory boundary. ADR 0038.
   module Layout
     RUN = ".run"
+    DATA = "data"
+
+    def self.data(root)
+      File.join(root, DATA)
+    end
+
+    def self.data_lane(root, lane_name)
+      File.join(data(root), lane_name)
+    end
 
     def self.run(root)
       File.join(root, RUN)
@@ -25,6 +34,10 @@ module Textus
       File.join(run(root), "build.lock")
     end
 
+    def self.watcher_lock(root)
+      File.join(run(root), "watcher.lock")
+    end
+
     def self.queue(root)
       File.join(run(root), "queue")
     end

data/lib/textus/manifest/data.rb

@@ -5,15 +5,15 @@ module Textus
   class Manifest
     # Immutable, parsed view of a manifest YAML document.
     #
-    # Holds raw structural data (zones, entries, audit_config, role_caps)
-    # but no behaviour beyond accessors. Behaviour (zone authority, key
+    # Holds raw structural data (lanes, entries, audit_config, role_caps)
+    # but no behaviour beyond accessors. Behaviour (lane authority, key
     # resolution, rules) lives on Manifest::Policy / Resolver / Rules.
     class Data
       AUDIT_DEFAULTS = { max_size: 10_485_760, keep: 5 }.freeze
       WORKER_DEFAULTS = { pool: 4, poll: 5, lease_ttl: 60, max_attempts: 3 }.freeze
 
-      attr_reader :raw, :root, :entries, :declared_zone_kinds,
-                  :zone_descs, :zone_owners,
+      attr_reader :raw, :root, :entries, :declared_lane_kinds,
+                  :lane_descs, :lane_owners,
                   :audit_config, :worker_config, :role_caps, :policy
 
       def self.validate_key!(key)
@@ -27,7 +27,7 @@ module Textus
       def validate_key!(key) = self.class.validate_key!(key)
 
       def self.parse(raw, root:)
-        raise BadFrontmatter.new(File.join(root.to_s, "manifest.yaml"), "manifest must declare zones:") if Array(raw["zones"]).empty?
+        raise BadFrontmatter.new(File.join(root.to_s, "manifest.yaml"), "manifest must declare lanes:") if Array(raw["lanes"]).empty?
 
         Schema.validate!(raw)
         new(raw: raw, root: root)
@@ -36,17 +36,17 @@ module Textus
       def initialize(raw:, root:)
         @raw = raw
         @root = root
-        # Write authority is derived from capabilities × zone-kind (ADR 0030),
-        # not a per-zone writer list. "Which zones are declared" lives in the
-        # one kind-keyed map below (declared_zone_kinds); membership checks by
-        # read-side callers (boot, maintenance/zone_mv) use its keyset (ADR 0034).
-        @declared_zone_kinds = Array(raw["zones"]).to_h do |z|
+        # Write authority is derived from capabilities × lane-kind (ADR 0030),
+        # not a per-lane writer list. "Which lanes are declared" lives in the
+        # one kind-keyed map below (declared_lane_kinds); membership checks by
+        # read-side callers (boot, maintenance/data_mv) use its keyset (ADR 0034).
+        @declared_lane_kinds = Array(raw["lanes"]).to_h do |z|
           [z["name"], z["kind"]&.to_sym]
         end
-        @zone_descs  = Array(raw["zones"]).to_h { |z| [z["name"], z["desc"]] }
-        # Only zones that actually declare an owner — keep nil-tombstones out so a
-        # future `zone_owners.key?(name)` means "owner declared", not "zone exists".
-        @zone_owners = Array(raw["zones"]).to_h { |z| [z["name"], z["owner"]] }.compact
+        @lane_descs  = Array(raw["lanes"]).to_h { |z| [z["name"], z["desc"]] }
+        # Only lanes that actually declare an owner — keep nil-tombstones out so a
+        # future `lane_owners.key?(name)` means "owner declared", not "lane exists".
+        @lane_owners = Array(raw["lanes"]).to_h { |z| [z["name"], z["owner"]] }.compact
         @audit_config = build_audit_config(raw)
         @worker_config = build_worker_config(raw)
         @role_caps = Capabilities.resolve(raw["roles"])