hecks 3.5.0 → 3.7.0

data/lib/hecks/hecks/codebase.bluebook

@@ -960,6 +960,7 @@ Hecks.bluebook "Hecks" do
     attribute :operation, Operation, optional: true
     attribute :confirm,   Switch, optional: true
     attribute :check,     Switch, optional: true
+    attribute :live,      Switch, optional: true
     attribute :gate,      GateName, optional: true
     attribute :checkout,  Switch, optional: true
     attribute :report,    Report, optional: true
@@ -1027,6 +1028,24 @@ Hecks.bluebook "Hecks" do
       emits ProjectCiGatesRequested
     end
 
+    command "ProjectLanes" do
+      role "Maintainer"
+      goal "Project the Lane rows into the rulesets and the promotion workflow, or with live compare GitHub's rulesets"
+
+      attribute :check,   Switch, optional: true
+      attribute :live,    Switch, optional: true
+      attribute :run,     RunKey
+      attribute :confirm, Switch, optional: true
+
+      sets :check
+      sets :live
+      sets :run
+      sets :confirm
+      sets :operation, to: "project_lanes"
+
+      emits ProjectLanesRequested
+    end
+
     command "ProjectToolsDoc" do
       role "Maintainer"
       goal "Write the launcher forms of docs/tools.md from the RetiredScript rows, or with check only compare them"
@@ -1121,6 +1140,11 @@ Hecks.bluebook "Hecks" do
     trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
   end
 
+  policy "ExamineWhenProjectLanesRequested" do
+    on      "RegenerationRun.ProjectLanesRequested"
+    trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
+  end
+
   policy "ExamineWhenProjectToolsDocRequested" do
     on      "RegenerationRun.ProjectToolsDocRequested"
     trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
@@ -2365,6 +2389,7 @@ Hecks.bluebook "Hecks" do
     attribute :no_wait,        Switch, optional: true
     attribute :checkout,       Switch, optional: true
     attribute :branch,         Word, optional: true
+    attribute :release_lane,   Word, optional: true
     attribute :on_origin,      Switch, optional: true
     attribute :clean,          Switch, optional: true
     attribute :version,        Version, optional: true
@@ -2465,6 +2490,7 @@ Hecks.bluebook "Hecks" do
       reference_to PublishingRun
       attribute :checkout,       Switch
       attribute :branch,         Word
+      attribute :release_lane,   Word
       attribute :on_origin,      Switch
       attribute :clean,          Switch
       attribute :version,        Version
@@ -2476,8 +2502,10 @@ Hecks.bluebook "Hecks" do
       attribute :ships_from,     Checkout
 
       given("needs a hecks checkout: hecks.gemspec stands beside lib/") { checkout.value }
-      given("a release is cut from main: switch to main first") { branch.value == "main" }
-      given("main is origin/main: merge the release PR, then pull") { on_origin.value }
+      given("a release is cut from the release lane (the Lane row that feeds a tag): switch to it first") do
+        branch.value == release_lane.value
+      end
+      given("the release lane is its origin: wait for the release commit to be promoted, then pull") { on_origin.value }
       given("the working tree is clean: commit or discard changes first") { clean.value }
       given("the client package is at the gem's version: bump the package first") do
         client_version.value == version.value
@@ -2489,6 +2517,7 @@ Hecks.bluebook "Hecks" do
 
       sets :checkout
       sets :branch
+      sets :release_lane
       sets :on_origin
       sets :clean
       sets :version
@@ -2585,8 +2614,9 @@ Hecks.bluebook "Hecks" do
   policy "AcceptTheReleaseWhenExamined" do
     on      "PublishingRun.PublishingExamined"
     where   { operation.value == "publish" }
-    trigger PublishingRun::Accept, with: { checkout: :checkout, branch: :branch, on_origin: :on_origin,
-                                           clean: :clean, version: :version, client_version: :client_version,
+    trigger PublishingRun::Accept, with: { checkout: :checkout, branch: :branch, release_lane: :release_lane,
+                                           on_origin: :on_origin, clean: :clean, version: :version,
+                                           client_version: :client_version,
                                            changelog: :changelog, tag_state: :tag_state, head: :head,
                                            ir_version: :ir_version, ships_from: :ships_from }
   end
@@ -2603,7 +2633,7 @@ Hecks.bluebook "Hecks" do
     on      "PublishingRun.PublishingExamined"
     where do
       operation.value == "publish" &&
-        (!checkout.value || branch.value != "main" || !on_origin.value || !clean.value ||
+        (!checkout.value || branch.value != release_lane.value || !on_origin.value || !clean.value ||
           client_version.value != version.value || !changelog.value || tag_state.value == "elsewhere")
     end
     trigger PublishingRun::Fault, with: { refusal: "a release rule is not met: check the branch, tree, versions, CHANGELOG and tag" }
@@ -2666,4 +2696,291 @@ Hecks.bluebook "Hecks" do
     on      "PublishingRun.PublishingRefused"
     trigger PublishingRun::Fault, with: { refusal: :refusal }
   end
+
+  # Promotion: moving a lane forward onto a commit that has passed every `RequiredCheck`. The
+  # adapter reads the facts (does the lane exist, where its head stands, where each check stands
+  # against the commit) and `Accept` holds the rules, so what makes a commit fit for the lane is
+  # decided here and in the Lane and RequiredCheck rows, never by the workflow that runs
+  # `hecks promotion_run.promote`. Without --confirm the run is a rehearsal: it names the move it
+  # would make and makes none. A real run fast-forwards the lane (never forces it) and moves the
+  # tag the lane `feeds`, forward only; a lane that already holds the commit still has its tag
+  # brought up to the lane's head, so a half-finished run is finished by the next.
+  #
+  # A commit is certified by the checks of that exact commit. With `commit` named, that commit is
+  # the one judged, and no other is ever put in its place. Without it, the commit is the newest
+  # one of the followed lane (first-parent, a bounded way back) that every `RequiredCheck` passed
+  # on and that fast-forwards the lane, so the outcome never depends on which push's CI run
+  # started the promotion; when none qualifies the refusal names what the lane's head is
+  # waiting on.
+  aggregate "PromotionRun" do
+    description "One move of a lane onto a commit, or the rehearsal of it: judged by the facts, then carried out."
+
+    attribute :run,        RunKey
+    attribute :operation,  Operation, optional: true
+    attribute :confirm,    Switch, optional: true
+    attribute :lane,       Word
+    attribute :commit,     Word, optional: true
+    attribute :checkout,   Switch, optional: true
+    attribute :lane_known, Switch, optional: true
+    attribute :green,      Switch, optional: true
+    attribute :descends,   Switch, optional: true
+    attribute :head,       Word, optional: true
+    attribute :behind_hours, Hours, optional: true
+    attribute :limit_hours,  Hours, optional: true
+    attribute :alert_key,    Word, optional: true
+    attribute :promoted,   Switch, optional: true
+    attribute :reason,     Report, optional: true
+    attribute :report,     Report, optional: true
+    attribute :refusal,    Report, optional: true
+    identified_by :run
+
+    value_object "RunKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a run is named") { !value.to_s.empty? }
+    end
+
+    value_object "Operation" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    # A branch name, or a commit.
+    value_object "Word" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
+    # How long a lane has stood behind the lane it follows, or how long its row lets it.
+    value_object "Hours" do
+      attribute :value, Integer
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Accept"   => "accepted",  from: "requested"
+      transition "Observe"  => "observed",  from: "requested"
+      transition "Complete" => "completed", from: %w[accepted observed]
+      transition "Fault"    => "faulted",   from: %w[requested accepted]
+      transition "Lag"      => "faulted",   from: "observed"
+    end
+
+    # Looks at a lane and moves nothing: faults when it has stood behind the lane it follows for
+    # longer than its `Lane` row allows, which files a finding. A lane whose row allows no lag is
+    # never late.
+    command "Watch" do
+      role "Maintainer"
+      goal "Fault when a lane has stood behind the lane it follows for longer than its Lane row allows"
+
+      attribute :lane,      Word
+      attribute :run,       RunKey
+      attribute :alert_key, Word
+
+      sets :lane
+      sets :run
+      sets :alert_key
+      sets :operation, to: "watch"
+
+      emits WatchRequested
+    end
+
+    command "Promote" do
+      role "Maintainer"
+      goal "Move a lane onto a commit that has passed every required check, or with no --confirm rehearse the move"
+
+      attribute :lane,    Word
+      attribute :commit,  Word, optional: true
+      attribute :run,     RunKey
+      attribute :confirm, Switch, optional: true
+
+      sets :lane
+      sets :commit
+      sets :run
+      sets :confirm
+      sets :operation, to: "promote"
+
+      emits PromoteRequested
+    end
+
+    # What the tree and the remote reported, held against the rules of a promotion: the adapter
+    # supplies the facts and the givens decide.
+    command "Accept" do
+      role "System"
+      goal "Let a lane move only in a hecks checkout, onto a commit that is green on every required check and contains the lane's head"
+
+      reference_to PromotionRun
+      attribute :checkout,   Switch
+      attribute :lane_known, Switch
+      attribute :green,      Switch
+      attribute :descends,   Switch
+      attribute :commit,     Word
+      attribute :head,       Word, optional: true
+
+      given("needs a hecks checkout: hecks.gemspec stands beside lib/") { checkout.value }
+      given("the lane is one of the Lane rows, and follows another lane") { lane_known.value }
+      given("every RequiredCheck is green on the commit: wait for the checks, or fix the red one") { green.value }
+      given("the commit is on the lane it follows and contains the lane's head: a lane only moves forward") { descends.value }
+
+      sets :checkout
+      sets :lane_known
+      sets :green
+      sets :descends
+      sets :commit
+      sets :head
+
+      emits PromotionAccepted
+    end
+
+    # What the tree and the remote reported about a watched lane, held against the rules of a
+    # watch: it needs a hecks checkout and a lane that follows another.
+    command "Observe" do
+      role "System"
+      goal "Let a lane be judged late or on time only in a hecks checkout, for a lane that follows another"
+
+      reference_to PromotionRun
+      attribute :checkout,     Switch
+      attribute :lane_known,   Switch
+      attribute :behind_hours, Hours
+      attribute :limit_hours,  Hours
+      attribute :alert_key,    Word
+      attribute :promoted,     Switch
+      attribute :reason,       Report
+
+      given("needs a hecks checkout: hecks.gemspec stands beside lib/") { checkout.value }
+      given("the lane is one of the Lane rows, and follows another lane") { lane_known.value }
+
+      sets :checkout
+      sets :lane_known
+      sets :behind_hours
+      sets :limit_hours
+      sets :alert_key
+      sets :promoted
+      sets :reason
+
+      emits LaneObserved
+    end
+
+    command "Complete" do
+      role "System"
+      goal "Record that the promotion was carried out or rehearsed, or the lane was on time, and what it reported"
+
+      reference_to PromotionRun
+      attribute :report,   Report
+      attribute :promoted, Switch
+
+      sets :report
+      sets :promoted
+
+      emits PromotionCompleted
+    end
+
+    # A lane that has stood behind the lane it follows for longer than its Lane row allows.
+    command "Lag" do
+      role "System"
+      goal "Record that a lane is late, and what it is waiting on, under the alert key that names its finding"
+
+      reference_to PromotionRun
+      attribute :refusal,   Report
+      attribute :alert_key, Word
+
+      sets :refusal
+      sets :alert_key
+
+      emits LaneLagged
+    end
+
+    command "Fault" do
+      role "System"
+      goal "Record that the promotion was refused or could not be carried out, and why"
+
+      reference_to PromotionRun
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits PromotionFaulted
+    end
+
+    query "PromotionOutcome" do
+      description "How one promotion ended: its status, and what it reported or why it failed."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "PromotionFaulted" do
+      description "Every promotion that was refused or could not be carried out."
+      where(status: "faulted")
+      order_by :run
+    end
+  end
+
+  policy "ExamineWhenPromoteRequested" do
+    on      "PromotionRun.PromoteRequested"
+    trigger PromotionRun::SourceTree::Examine, with: { run: :run }
+  end
+
+  policy "ExamineWhenWatchRequested" do
+    on      "PromotionRun.WatchRequested"
+    trigger PromotionRun::SourceTree::Examine, with: { run: :run }
+  end
+
+  policy "ObserveWhenWatchExamined" do
+    on      "PromotionRun.PromotionExamined"
+    where   { operation.value == "watch" }
+    trigger PromotionRun::Observe, with: { checkout: :checkout, lane_known: :lane_known, behind_hours: :behind_hours,
+                                           limit_hours: :limit_hours, alert_key: :alert_key, promoted: :promoted,
+                                           reason: :reason }
+  end
+
+  policy "FaultWhenWatchCannotBeJudged" do
+    on      "PromotionRun.PromotionExamined"
+    where   { operation.value == "watch" && (!checkout.value || !lane_known.value) }
+    trigger PromotionRun::Fault, with: { refusal: :reason }
+  end
+
+  policy "LagWhenLaneLate" do
+    on      "PromotionRun.LaneObserved"
+    where   { behind_hours.value > limit_hours.value }
+    trigger PromotionRun::Lag, with: { refusal: :reason, alert_key: :alert_key }
+  end
+
+  policy "CompleteWhenLaneOnTime" do
+    on      "PromotionRun.LaneObserved"
+    where   { behind_hours.value <= limit_hours.value }
+    trigger PromotionRun::Complete, with: { report: :reason, promoted: :promoted }
+  end
+
+  policy "AcceptPromotionWhenExamined" do
+    on      "PromotionRun.PromotionExamined"
+    where   { operation.value == "promote" }
+    trigger PromotionRun::Accept, with: { checkout: :checkout, lane_known: :lane_known, green: :green,
+                                          descends: :descends, commit: :commit, head: :head }
+  end
+
+  policy "FaultPromotionWhenNotAccepted" do
+    on      "PromotionRun.PromotionExamined"
+    where   { operation.value == "promote" && (!checkout.value || !lane_known.value || !green.value || !descends.value) }
+    trigger PromotionRun::Fault, with: { refusal: :reason }
+  end
+
+  policy "PerformPromotionWhenAccepted" do
+    on      "PromotionRun.PromotionAccepted"
+    trigger PromotionRun::SourceTree::Perform, with: { run: :run }
+  end
+
+  policy "RecordPromotionOutcome" do
+    on      "PromotionRun.PromotionAnswered"
+    trigger PromotionRun::Complete, with: { report: :report, promoted: :promoted }
+  end
+
+  policy "RecordPromotionFault" do
+    on      "PromotionRun.PromotionRefused"
+    trigger PromotionRun::Fault, with: { refusal: :refusal }
+  end
 end

data/lib/hecks/hecks/custodian.behaviors

@@ -147,6 +147,12 @@ Hecks.behaviors "Custodian" do
     expect refused: "a count is positive"
   end
 
+  test "Mutate refuses a budget that is not positive" do
+    tests "Mutate", on: "FuzzRun"
+    input run: { value: "mutants" }, domain: { value: "examples/pizzas" }, budget: { value: 0 }
+    expect refused: "a count is positive"
+  end
+
   test "Fuzz refuses a persistence it does not know" do
     tests "Fuzz", on: "FuzzRun"
     input run: { value: "sweep" }, adapter: { value: "cassandra" }

data/lib/hecks/hecks/custodian.bluebook

@@ -1963,7 +1963,9 @@ policy "RecordTheEra" do
     attribute :seeds,      Count,       optional: true
     attribute :steps,      Count,       optional: true
     attribute :workers,    Count,       optional: true
+    attribute :budget,     Count,       optional: true
     attribute :adapter,    Persistence, optional: true
+    attribute :persist_regressions, RegressionSwitch, optional: true
     attribute :domains,    NameList,    optional: true
     attribute :targets,    NameList,    optional: true
     attribute :iterations, Count,       optional: true
@@ -2006,6 +2008,11 @@ policy "RecordTheEra" do
       attribute :value, String, pattern: '^(memory|sqlite|postgres)$'
     end
 
+    # Whether each distinct finding's minimized repro is also kept under `spec/corpus/regressions/`.
+    value_object "RegressionSwitch" do
+      attribute :value, Boolean
+    end
+
     # Names, comma separated: benchmark domains, or the targets to measure.
     value_object "NameList" do
       attribute :value, String, pattern: '^[^ \t\n\r,]+(,[^ \t\n\r,]+)*$'
@@ -2047,6 +2054,7 @@ policy "RecordTheEra" do
       attribute :steps,   Count,       optional: true
       attribute :workers, Count,       optional: true
       attribute :adapter, Persistence, optional: true
+      attribute :persist_regressions, RegressionSwitch, optional: true
 
       sets :domain
       sets :run
@@ -2054,10 +2062,34 @@ policy "RecordTheEra" do
       sets :steps
       sets :workers
       sets :adapter
+      sets :persist_regressions
 
       emits FuzzRequested
     end
 
+    # Mutation-tests a domain's own checks: changes its bluebooks in small ways and keeps which
+    # changes the fuzz properties, the corpus script and the domain's behaviors tests let through.
+    # A survivor is a hole in those checks. `budget` caps how many mutants are tried. The run is a
+    # child process started through the ProcessPool adapter, as a sweep is.
+    command "Mutate" do
+      role "Operator"
+      goal "Mutate a domain's rules and keep whether its checks noticed each change"
+
+      attribute :domain, DomainPath
+      attribute :run,    FuzzKey
+      attribute :seeds,  Count, optional: true
+      attribute :steps,  Count, optional: true
+      attribute :budget, Count, optional: true
+
+      sets :domain
+      sets :run
+      sets :seeds
+      sets :steps
+      sets :budget
+
+      emits MutateRequested
+    end
+
     # Measures each persistence adapter, and the Rust binary when there is one to build or use.
     # The report is kept in this record, which the Hecks domain binds to Memory: keeping a
     # domain's benchmark history beside it, in Sqlite under the project's `.hecks/`, is decided
@@ -2148,6 +2180,11 @@ policy "RecordTheEra" do
     trigger FuzzRun::ProcessPool::Sweep, with: { run: :run }
   end
 
+  policy "MutateWhenRequested" do
+    on      "FuzzRun.MutateRequested"
+    trigger FuzzRun::ProcessPool::Probe, with: { run: :run }
+  end
+
   policy "MeasureWhenRequested" do
     on      "FuzzRun.BenchRequested"
     trigger FuzzRun::RustToolchain::Measure, with: { run: :run }

data/lib/hecks/hecks/hecks.hecksagon

@@ -188,6 +188,12 @@ Hecks.hecksagon "Hecks" do
       answers "FuzzAnswered"
       refuses "FuzzRefused"
     end
+
+    asks "Probe", to: FuzzRun do
+      attribute :run, FuzzKey
+      answers "FuzzAnswered"
+      refuses "FuzzRefused"
+    end
   end
 
   Hecks::FuzzRun.port "RustToolchain" do
@@ -364,6 +370,22 @@ Hecks.hecksagon "Hecks" do
     end
   end
 
+  # Promotion: the SourceTree adapter reads the lane's head and where each required check stands
+  # against the commit, and carries out the move only after Accept.
+  Hecks::PromotionRun.port "SourceTree" do
+    asks "Examine", to: PromotionRun do
+      attribute :run, RunKey
+      answers "PromotionExamined"
+      refuses "PromotionRefused"
+    end
+
+    asks "Perform", to: PromotionRun do
+      attribute :run, RunKey
+      answers "PromotionAnswered"
+      refuses "PromotionRefused"
+    end
+  end
+
   # Deploy, attached above: its bluebook loads without deploy.hecksagon, so the outside its
   # commands reach is named here as well. TenantProvisioning writes a tenant's overlay world;
   # DeployToolchain generates and checks a recipe and projects the OIDC manifests.

data/lib/hecks/hecks/hecks.world

@@ -1,7 +1,7 @@
 # Where the Hecks domain keeps its journal: every command's events, one entry per aggregate.
 #
 # **PostgresEra** is the default, for real runs: a client's `hecks` and a maintainer's on main
-# or in the merge queue. The journal then survives the process, and `hecks stores` and
+# or stable. The journal then survives the process, and `hecks stores` and
 # `hecks history` read it back. `default_adapter` binds every aggregate of the chapter (and of
 # the attached Governance chapter, see governance.world) in one line, which is what lets the
 # environments/memory.world overlay swap the whole domain to Memory.
@@ -31,7 +31,10 @@
 # gem's `exe/hecks`), `streams` lists the questions `--stream` may tail (`Follow`), `memory_commands` names
 # the commands that launcher runs on the Memory environment unless `HECKS_ENVIRONMENT` is set (so
 # `hecks console` needs no database), and `legacy` names the commands it hands to `Hecks::CLI` in the
-# positional forms ADR 0066 shipped.
+# positional forms ADR 0066 shipped. `maintainer` names the aggregates only someone working on a hecks
+# checkout runs (Codebase, and releasing hecks itself): the help leaves them out anywhere else and
+# `--maintainer` lists them; `chapters` names the attached chapters the help points at, one line each
+# (`hecks deploy`), and `maintainer_chapters` the language's own, added inside a checkout.
 Hecks.world "Hecks" do
   realm "Hecks"
   default_adapter "PostgresEra"
@@ -51,6 +54,11 @@ Hecks.world "Hecks" do
                                 "package.release" => "registry.release" },
                        streams: %w[Follow],
                        executable: "exe/hecks",
+                       maintainer: %w[LanguageRun KernelRun ConformanceRun RegenerationRun GateRun StyleRun
+                                      CodemodRun TestSuiteRun CorpusRun PublishingRun PromotionRun Release
+                                      SyntaxBootCache],
+                       chapters: %w[Deploy Governance Tenancy Site Tickets QualityControl],
+                       maintainer_chapters: %w[Bluebook Hecksagon World Adapter Port Translation Expression],
                        memory_commands: %w[console init interview],
                        legacy: %w[run docs narrate ir stores model_check smoke_test
                                   project_diagrams project_cli mcp]

data/lib/hecks/kernel_capabilities/templates.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Hecks
+  module KernelCapabilities
+    # The Rust source of the two capability modules. Extended onto `KernelCapabilities`.
+    module Templates
+      # One capability module, with `%{...}` where its parts go.
+      RUST = <<~RUST
+        // GENERATED by hecks project_kernel_capabilities from %<doc_line>s.
+        // Do not hand-edit — re-run hecks project_kernel_capabilities instead.
+        //
+        %<header>s
+
+        %<mods>s
+
+        /// One variant per real %<kind>s the Ruby
+        /// grammar admits, in the order %<doc_line>s declares them. Every match
+        /// over this enum in the kernel (rust/src/kernel/expr.rs) is written
+        /// WITHOUT a wildcard `_ =>` arm — see expr.rs's own header for why:
+        /// a wildcard here would let a newly-admitted capability compile
+        /// silently into a router that never calls the new file this same
+        /// regeneration adds a `pub mod` line for above.
+        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+        pub enum %<enum_name>s {
+        %<variants>s
+        }
+
+        impl %<enum_name>s {
+            /// The `rust/src/kernel/%<directory>s/<name>.rs` file this
+            /// variant names — `hecks measure_kernel_coverage`'s own existence
+            /// check reads this, so the file-name spelling here is the ONE
+            /// place that ever needs to change if a name is renamed.
+            pub fn module_name(&self) -> &'static str {
+                match self {
+        %<arms>s
+                }
+            }
+
+            pub const ALL: &'static [%<enum_name>s] = &[%<all>s];
+        }
+      RUST
+
+      # @return [String] the whole `attribute_shapes/mod.rs`
+      def shapes_module
+        header = <<~HEADER.strip
+          // Ground truth: Hecks::Runtime::Value::Coercion::SHAPES
+          // (lib/hecks/runtime/value/coercion.rb) — the four branches
+          // `for_attribute` itself takes, read directly rather than
+          // re-derived here.
+        HEADER
+        render(header: header, enum_name: "AttributeShape", names: Hecks::Runtime::Value::Coercion::SHAPES,
+               doc_line: "Coercion::SHAPES")
+      end
+
+      # @return [String] the whole `expression_operators/mod.rs`
+      def operators_module
+        header = <<~HEADER.strip
+          // Ground truth: Hecks::Grammar.admitted_operators (lib/hecks/
+          // grammar.rb), the SAME live-booted call hecks project_expression_tables
+          // uses — grouped by the `category` field Evaluator::PROJECTION already
+          // partitions comparison operators by (evaluator.rb).
+        HEADER
+        render(header: header, enum_name: "OperatorCategory", names: operator_categories,
+               doc_line: "Grammar.admitted_operators's own `category` field")
+      end
+
+      # Renders one capability module: `pub mod` lines, the enum, and its `ALL`.
+      #
+      # @param header [String] the ground-truth comment
+      # @param enum_name [String] `AttributeShape` or `OperatorCategory`
+      # @param names [Array<String>] the capabilities, in declaration order
+      # @param doc_line [String] where the capabilities are declared
+      # @return [String] the Rust source
+      def render(header:, enum_name:, names:, doc_line:)
+        shapes = enum_name == "AttributeShape"
+        format(RUST, header: header, doc_line: doc_line, enum_name: enum_name,
+                     kind: shapes ? "attribute shape" : "expression-operator category",
+                     directory: shapes ? "attribute_shapes" : "expression_operators",
+                     mods: names.map { |name| "pub mod #{name};" }.join("\n"),
+                     variants: names.map { |name| "    #{pascal(name)}," }.join("\n"),
+                     arms: names.map { |name| "            #{enum_name}::#{pascal(name)} => #{name.to_s.inspect}," }.join("\n"),
+                     all: names.map { |name| "#{enum_name}::#{pascal(name)}" }.join(", "))
+      end
+
+      # @param name [String, Symbol] a snake_case capability name
+      # @return [String] the PascalCase Rust variant
+      def pascal(name)
+        name.to_s.split("_").map { |part| part[0].upcase + part[1..] }.join
+      end
+    end
+  end
+end