hecks 2.6.0 → 2.8.0

data/lib/hecks/release/runner/tagger.rb

@@ -0,0 +1,87 @@
+require_relative "commands"
+require_relative "git"
+
+module Hecks
+  module Release
+    class Runner
+      # Makes sure the release tag `vX.Y.Z` is an annotated tag on the release
+      # commit and is on origin, creating and pushing it only when it is missing.
+      class Tagger
+        # @param git [Git] the repository the release is cut from
+        # @param console [Console] asks before the tag is created or pushed
+        # @param dry_run [Boolean] report what would happen and change nothing
+        def initialize(git:, console:, dry_run:)
+          @git = git
+          @console = console
+          @dry_run = dry_run
+        end
+
+        # Brings the tag to the state described above, saying what it did.
+        #
+        # @param facts [Preflight::Facts] the version and commit being released
+        # @return [Boolean] false when the person declined the question, true otherwise
+        # @raise [Refusal] if the tag already points at another commit, locally or on origin
+        # @raise [CommandFailed] if creating or pushing the tag fails
+        def ensure!(facts)
+          tag = "v#{facts.version}"
+          local = local_commit(tag)
+          remote = remote_commit(tag)
+          refuse_elsewhere(tag, facts.sha, local: local, remote: remote)
+          return true.tap { already_there(tag) } if remote
+          return true.tap { preview(tag, facts.sha, local) } if @dry_run
+          return false unless @console.confirm?(question(tag, facts.sha, local))
+
+          create(tag, facts.sha) unless local
+          push(tag)
+          true
+        end
+
+        private
+
+        def already_there(tag)
+          @console.say("Tag #{tag} is already on origin at the release commit; skipping.")
+        end
+
+        def preview(tag, sha, local)
+          @console.say("Would create annotated tag #{tag} at #{sha[0, 7]}.") unless local
+          @console.say("Would push #{tag} to origin.")
+        end
+
+        def question(tag, sha, local)
+          verb = local ? "Push" : "Create and push"
+          "#{verb} annotated tag #{tag} at #{sha[0, 7]} to origin?"
+        end
+
+        def create(tag, sha)
+          @git.run!("tag", "-a", tag, "-m", "Release #{tag.delete_prefix('v')}", sha)
+        end
+
+        def push(tag)
+          @git.run!("push", "origin", tag)
+        end
+
+        def refuse_elsewhere(tag, sha, local:, remote:)
+          { "locally" => local, "on origin" => remote }.each do |where, commit|
+            next if commit.nil? || commit == sha
+
+            raise Refusal, "tag #{tag} already points at #{commit[0, 7]} #{where}, not at the release commit " \
+                           "#{sha[0, 7]}; if that tag was never released, delete it (git tag -d #{tag}; " \
+                           "git push origin :refs/tags/#{tag}) and re-run, otherwise main has moved since the release " \
+                           "and the missing package must be published from a checkout of #{tag}"
+          end
+        end
+
+        def local_commit(tag)
+          result = @git.capture("rev-parse", "-q", "--verify", "refs/tags/#{tag}^{commit}")
+          result.success? ? result.stdout.strip : nil
+        end
+
+        def remote_commit(tag)
+          listing = @git.read("ls-remote", "--tags", "origin", "refs/tags/#{tag}", "refs/tags/#{tag}^{}")
+          shas = listing.lines.to_h { |line| line.split.then { |sha, ref| [ref, sha] } }
+          shas.fetch("refs/tags/#{tag}^{}") { shas["refs/tags/#{tag}"] }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/release/runner.rb

@@ -0,0 +1,244 @@
+require_relative "runner/commands"
+require_relative "runner/console"
+require_relative "runner/git"
+require_relative "runner/preflight"
+require_relative "runner/published"
+require_relative "runner/tagger"
+require_relative "runner/gem_publisher"
+require_relative "runner/npm_publisher"
+require_relative "runner/ci_publisher"
+
+module Hecks
+  module Release
+    # Performs the release once the release PR has merged: tags the merge
+    # commit, publishes the gem to rubygems.org and gets the JavaScript client
+    # published to npm.
+    #
+    # ## Why it exists
+    #
+    # A release is four steps that have to happen in one order, and only
+    # the contributing guide remembered it. This runs them in that order, refuses to
+    # start from a checkout that is not the merged `main`, and can be run again:
+    # it asks the registries what is already published and skips it, so a run
+    # that died between the gem and the package resumes at the package.
+    #
+    # ## Steps
+    #
+    # 1. Preflight: tools installed, on a clean `main` equal to `origin/main`,
+    #    the gem and the client at one version, the changelog naming it.
+    # 2. Published state: which of the gem and the package are already out.
+    # 3. Tag: an annotated `vX.Y.Z` on the release commit, pushed to origin.
+    # 4. Gem: `bin/release_gem`, unchanged.
+    # 5. npm, one of two ways:
+    #    - by default CI publishes: the tag triggers `publish-client.yml`, which
+    #      uses npm trusted publishing, and this waits for the version to appear
+    #      (`--no-wait` skips the wait);
+    #    - with `--npm-local` this publishes from the machine, with a
+    #      bypass-two-factor token 1Password holds: the way to make the first
+    #      publish, before trusted publishing can be configured, and the fallback
+    #      when CI is down.
+    #
+    # ## Injectable commands and time
+    #
+    # Every process is started through `commands`, any object answering
+    # `capture(*argv, env:, chdir:)` and `run!(*argv, env:, chdir:)` like
+    # {Commands}, so a spec drives the whole release with a recorder. The wait for
+    # CI takes its clock and its pause as callables for the same reason.
+    class Runner
+      # Which steps to run and how.
+      class Options
+        # @return [Boolean] run every check and build, but tag, push and publish nothing
+        attr_reader :dry_run
+
+        # @param dry_run [Boolean] run every check and build, but tag, push and publish nothing
+        # @param gem_only [Boolean] publish the gem, not the package
+        # @param npm_only [Boolean] do the npm step only, not the gem: wait for CI's publish, or
+        #   with `npm_local` publish from here
+        # @param npm_local [Boolean] publish the package from this machine, not by CI
+        # @param no_wait [Boolean] do not wait for CI's publish to reach npm
+        # @param yes [Boolean] answer every confirmation yes
+        # @raise [ArgumentError] if the flags contradict each other
+        def initialize(dry_run: false, gem_only: false, npm_only: false, npm_local: false, no_wait: false, yes: false)
+          check_flags(gem_only, npm_only, npm_local, no_wait)
+
+          @dry_run = dry_run
+          @gem_only = gem_only
+          @npm_only = npm_only
+          @npm_local = npm_local
+          @no_wait = no_wait
+          @yes = yes
+        end
+
+        # Says whether confirmations are answered automatically.
+        #
+        # @return [Boolean] true under `--yes`
+        def yes?
+          @yes
+        end
+
+        # Says whether the gem step is in scope.
+        #
+        # @return [Boolean] true unless `--npm-only`
+        def gem?
+          !@npm_only
+        end
+
+        # Says whether the npm step is in scope.
+        #
+        # @return [Boolean] true unless `--gem-only`
+        def npm?
+          !@gem_only
+        end
+
+        # Says whether the package is published from this machine.
+        #
+        # @return [Boolean] true under `--npm-local`
+        def npm_local?
+          @npm_local
+        end
+
+        # Says whether to wait for CI's publish to reach npm.
+        #
+        # @return [Boolean] true unless `--no-wait`
+        def wait?
+          !@no_wait
+        end
+
+        private
+
+        def check_flags(gem_only, npm_only, npm_local, no_wait)
+          raise ArgumentError, "--gem-only and --npm-only cannot be combined" if gem_only && npm_only
+          raise ArgumentError, "--gem-only and --npm-local cannot be combined" if gem_only && npm_local
+          return unless no_wait && npm_local
+
+          raise ArgumentError, "--no-wait applies to CI's publish, so it cannot be combined with --npm-local"
+        end
+      end
+
+      # @param root [String] the repository root
+      # @param options [Options] which steps to run and how
+      # @param commands [#capture, #run!] starts every process the release runs
+      # @param input [IO] where confirmations are read from
+      # @param out [IO] where progress is written
+      # @param err [IO] where refusals and failures are written
+      # @param pause [#call] sleeps for a number of seconds while waiting for CI
+      # @param now [#call] answers the current time in seconds, monotonically, while waiting for CI
+      def initialize(root:, options: Options.new, commands: Commands.new, input: $stdin, out: $stdout, err: $stderr,
+                     pause: ->(seconds) { sleep(seconds) }, now: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        @root = root
+        @options = options
+        @commands = commands
+        @console = Console.new(input: input, out: out, err: err, assume_yes: options.yes?)
+        @git = Git.new(root: root, commands: commands)
+        @published = Published.new(root: root, commands: commands)
+        @ci = CiPublisher.new(root: root, published: @published, console: @console, pause: pause, now: now)
+      end
+
+      # Runs the release.
+      #
+      # @return [Integer] 0 when the release finished or had nothing to do, 1 when a check refused,
+      #   a step failed, CI's publish did not arrive in time or a confirmation was declined
+      def call
+        facts = Preflight.new(root: @root, commands: @commands, git: @git, tools: tools).check!
+        pending = pending_steps(facts.version)
+        require_workflow(pending)
+        return declined unless Tagger.new(git: @git, console: @console, dry_run: @options.dry_run).ensure!(facts)
+
+        publish(facts, pending)
+      rescue Refusal, CommandFailed => e
+        @console.warn(e.message)
+        1
+      end
+
+      private
+
+      def tools
+        list = %w[git curl]
+        list << "gem" if @options.gem?
+        list << "npm" if @options.npm?
+        list << "op" if !@options.dry_run && (@options.gem? || @options.npm_local?)
+        list
+      end
+
+      def pending_steps(version)
+        [
+          (:gem if @options.gem? && !done?("hecks #{version} is already on rubygems.org", @published.gem?(version))),
+          (:npm if @options.npm? && !done?("@hecks/client #{version} is already on npm", @published.npm?(version)))
+        ].compact
+      end
+
+      def done?(message, published)
+        @console.say("#{message}; skipping.") if published
+        published
+      end
+
+      def ci_publishes?(pending)
+        pending.include?(:npm) && !@options.npm_local?
+      end
+
+      def require_workflow(pending)
+        return unless ci_publishes?(pending) && !@ci.workflow?
+
+        raise Refusal, "#{CiPublisher::WORKFLOW} is not in this checkout, so CI cannot publish @hecks/client; " \
+                       "publish it from here with --npm-local (the first publish, before trusted publishing is set up)"
+      end
+
+      def publish(facts, pending)
+        if pending.empty?
+          @console.say("Nothing to publish for #{facts.version}.")
+          return 0
+        end
+        return declined unless @options.dry_run || publish_confirmed?(facts.version, pending)
+
+        run_steps(facts.version, pending)
+      end
+
+      def publish_confirmed?(version, pending)
+        targets = []
+        targets << "hecks #{version} to rubygems.org" if pending.include?(:gem)
+        targets << "@hecks/client #{version} to npm" if pending.include?(:npm) && @options.npm_local?
+        return true if targets.empty?
+
+        suffix = ci_publishes?(pending) ? " (CI then publishes @hecks/client from the tag)" : ""
+        @console.confirm?("Publish #{targets.join(' and ')}#{suffix}? This cannot be undone.")
+      end
+
+      def run_steps(version, pending)
+        dry_run = @options.dry_run
+        publish_gem(version, dry_run) if pending.include?(:gem)
+        return 1 if pending.include?(:npm) && !publish_npm!(version, dry_run, ci_publishes?(pending))
+
+        @console.say(dry_run ? "Dry run complete; nothing was tagged, pushed or published." : "Released hecks #{version}.")
+        0
+      end
+
+      def publish_gem(version, dry_run)
+        GemPublisher.new(root: @root, commands: @commands, console: @console).publish!(version, dry_run: dry_run)
+      end
+
+      def publish_npm!(version, dry_run, via_ci)
+        return wait_for_ci!(version, dry_run) if via_ci
+
+        NpmPublisher.new(root: @root, commands: @commands, console: @console).publish!(version, dry_run: dry_run)
+        true
+      rescue CommandFailed => e
+        @console.warn("npm publish failed: #{e.message}")
+        unless dry_run
+          @console.warn("Finish the release with: bin/release --npm-only --npm-local (published steps are not repeated)")
+        end
+        raise
+      end
+
+      def wait_for_ci!(version, dry_run)
+        arrived = @ci.wait!(version, dry_run: dry_run, wait: @options.wait?)
+        @console.warn(CiPublisher.timeout_hint(version)) unless arrived
+        arrived
+      end
+
+      def declined
+        @console.warn("Aborted; nothing was published.")
+        1
+      end
+    end
+  end
+end

data/lib/hecks/router/namespace_installer.rb

@@ -140,7 +140,7 @@ module Hecks
                        .each do |(aggregate, verb), candidates|
           # Bounded chapters wrap in their own module (`Domain::Aggregate`)
           # so two BCs can both declare `Person` without colliding on
-          # Object::Person. Folder-spread files of the SAME chapter still
+          # Object::Person. Folder-spread files of the same chapter still
           # get the shortcut — they are not BCs.
           next if bounded_chapter?(candidates)
 

data/lib/hecks/runtime/command_interpreter.rb

@@ -106,7 +106,7 @@ module Hecks
           ctx.plan = DependencyPlanning::Analyzer.call(aggregate: aggregate, command: command)
           # **Resolved here, once, before hydration** — `Registry#repository`
           # memoizes, so this and `step_hydrate`'s own read of `ctx.repository`
-          # (no second fetch there any more) always name the same instance;
+          # (no second fetch there) always name the same instance;
           # the isolation decision below (lock vs. CAS+retry) needs the
           # repository's capabilities before a single step runs.
           ctx.repository = @registry.repository(domain, aggregate)
@@ -154,7 +154,7 @@ module Hecks
 
       def step_hydrate(ctx)
         # `ctx.repository` is resolved once, in `#call`, before the
-        # isolation decision (lock vs. CAS+retry) — not here any more.
+        # isolation decision (lock vs. CAS+retry) — not here.
         ctx.strategy = ctx.plan.strategy_for(capabilities: ctx.repository.capabilities)
         ctx.instance = step(:hydrate) do
           if ctx.plan.complete_state? && ctx.plan.state_independent?
@@ -543,7 +543,7 @@ module Hecks
       # Transitional compatibility for live source that has not yet
       # acquired explicit effects, same as it always was — deliberately
       # isolated from the normal routing and planning path so
-      # `reference_to` no longer chooses how a migrated command hydrates
+      # `reference_to` does not choose how a migrated command hydrates
       # or persists. A real, future Wave 8 removes this once that wider
       # inventory is empty, not before.
       #

data/lib/hecks/runtime/command_rules/admissibility.rb

@@ -163,7 +163,7 @@ module Hecks
         def enforce_givens(subject, command, args, domain:, declaring: nil, parent: nil, correction: {})
           state = GuardState.new(subject)
           # A rule may only read within its own aggregate boundary (S12,
-          # ADR 0025) — `subject`'s own stored references are no longer
+          # ADR 0025) — `subject`'s own stored references are not
           # dereferenced here at all: a `projects :customer_status, from:
           # :"customer.status"` field is just `subject`'s own
           # field, a regular stored attribute, already present in
@@ -375,7 +375,7 @@ module Hecks
         def enforce_ensures(subject, command, args, old:, domain:, parent: nil, correction: {})
           state = GuardState.new(subject)
           # S12, ADR 0025 — same boundary reasoning as enforce_givens
-          # above: `subject`'s own stored references are no longer
+          # above: `subject`'s own stored references are not
           # dereferenced here; a `projects`-maintained field is already
           # part of `state`. `command`/`args` still dereferences — a
           # fresh reference-typed argument stays in bounds.

data/lib/hecks/runtime/command_rules/arithmetic.rb

@@ -123,7 +123,7 @@ module Hecks
           amount = unwrap_single_numeric_field(amount) if amount.is_a?(Value)
 
           # Widened from Integer to Numeric (migration plan task 4, i106):
-          # miette's organ math increments a Float (`increment: 0.02`) --
+          # an external project's organ math increments a Float (`increment: 0.02`) --
           # the raw, non-value-object path only ever mattered for Integer
           # counters before this corpus existed. Integer stays the common
           # case; Float is now accepted the same way.
@@ -192,7 +192,7 @@ module Hecks
           amount_fields  = amount.to_h
           # Widened from Integer to Numeric -- see #arithmetic's own
           # comment. A synthesised value-object wrapper around a bare
-          # Float attribute (miette's Synapse#strength, auto-wrapped per
+          # Float attribute (an external project's Synapse#strength, auto-wrapped per
           # Part 3a's "bare primitives forbidden" finding) lands here as
           # a one-Float-field Value exactly the way a one-Integer-field
           # Value already did.

data/lib/hecks/runtime/entity_element.rb

@@ -89,7 +89,7 @@ module Hecks
       # matches by the element's own minted identity string directly instead
       # (`element_identity`, below) — the routing envelope already resolved
       # which element it means, so re-deriving `wants` from `args` would be
-      # redundant at best and wrong if `args` no longer carries that identity
+      # redundant at best and wrong if `args` does not carry that identity
       # at all.
       # Locate, then copy-before-mutate, in that order — see the "one
       # level deeper" comment below on why the copy has to happen exactly

data/lib/hecks/runtime/entity_interpreter.rb

@@ -251,7 +251,7 @@ module Hecks
 
       def step_hydrate_parent(ctx)
         # `ctx.repository` is resolved once, in `#call`, before the
-        # isolation decision — not here any more.
+        # isolation decision — not here.
         ctx.instance = step(:hydrate_parent) do
           parent(ctx.repository, ctx.aggregate, ctx.entity_name, ctx.command_name, ctx.args, ctx.route)
         end

data/lib/hecks/runtime/invocation.rb

@@ -12,7 +12,7 @@ module Hecks
     # vs the flat facts hash `dispatch_flat` carries, a port operation's
     # reference attribute
     # lifted into `to:`). `Runtime::Routing.envelope`/`.payload` delegate here
-    # and no longer hold that logic themselves.
+    # and hold none of that logic themselves.
     #
     # `facts` maps a fact name to exactly one of:
     #

data/lib/hecks/runtime/loader.rb

@@ -177,10 +177,11 @@ module Hecks
       # (conservative — see `SagaPersistence#rehydrate_sagas!`'s own
       # comment).
       #
-      # ADR 0033 — this loader no longer names `EraCheck`, or any other
+      # ADR 0033 — this loader does not name `EraCheck`, or any other
       # era-specific class, at all. Every loaded persistence plugin
       # (`Ports::Persistence.each_plugin` — nothing here if nothing was
-      # ever `require`d) is asked to contribute its own `:pre_verify`/
+      # ever `require`d, or brought in by a bound adapter, see
+      # `load_bound_adapters!`) is asked to contribute its own `:pre_verify`/
       # `:post_verify` gates generically; `:saga_rehydration` is the one
       # gate core still registers directly, because ADR 0031 already
       # proved it's not era-specific.
@@ -193,6 +194,7 @@ module Hecks
       #   a wiring problem
       def self.run_boot_gates!(registry, directory)
         gates = BootGates.new
+        load_bound_adapters!(registry)
         Ports::Persistence.each_plugin { |plugin| plugin.contribute_boot_gates(registry, gates) }
         check_compute_rules_backstop!(registry)
 
@@ -200,11 +202,33 @@ module Hecks
         registry.verify!
 
         gates.register(:saga_rehydration, ->(reg, _dir) { reg.rehydrate_sagas! }, phase: :post_verify) if
-          registry.hecksagons.each_key.any? { |domain| registry.saga_persistence(domain) != Ports::Persistence::NULL_SAGA_STORE }
+          registry.saga_domains.any? { |domain| registry.saga_persistence(domain) != Ports::Persistence::NULL_SAGA_STORE }
         gates.run!(:post_verify, registry, directory)
         gates
       end
 
+      # Resolves the Ruby implementation of every adapter a hecksagon binds.
+      #
+      # An adapter whose implementation loads on first mention (`PostgresEra`,
+      # through the era plugin) registers its persistence plugin as a side effect
+      # of that load. Resolving here, before the gates are collected, is what makes
+      # a domain that declares `persisted_by "PostgresEra"` boot with the plugin
+      # loaded and its era gates registered, without the app requiring the plugin
+      # itself. An adapter with no Ruby implementation is left for `verify!`, which
+      # refuses it with the bind it came from.
+      #
+      # @param registry [Runtime::Registry] the registry mid-boot, whose hecksagons name the binds
+      # @return [void]
+      def self.load_bound_adapters!(registry)
+        registry.hecksagons.each_value do |hexagon|
+          hexagon.binds.each do |bind|
+            registry.adapter_class(bind.adapter)
+          rescue WiringError
+            next
+          end
+        end
+      end
+
       # The one piece of the old, era-owned `check_compute_rules!` core
       # still carries — deliberately thinner. `registry.translations` is
       # plain `Bluebook::Translation`/`TranslationAggregate`/

data/lib/hecks/runtime/outbox.rb

@@ -398,7 +398,7 @@ module Hecks
             # A DOMAIN_REFUSAL never reaches here — PolicyInterpreter and
             # SagaInterpreter both rescue it as a recorded, undelivered
             # reaction. Anything that does reach here is a defect in the
-            # relay's own path (a consumer that no longer exists, an
+            # relay's own path (a consumer that does not exist, an
             # adapter that raised outside the interpreters' own rescue).
             repository.outbox_settle(row.id, status: "failed", error: "#{e.class}: #{e.message}")
             row.status = "failed"

data/lib/hecks/runtime/reaction_invocation.rb

@@ -271,9 +271,9 @@ module Hecks
       # aggregate, never one of its entities). An entity target's own identity
       # is resolved entirely separately, from `args` (`build`'s own `entity_
       # identities` loop) — this method is never consulted for it, so
-      # answering for an entity target does not "invent an entity identity"
-      # any more than answering for a plain one invents that identity; it was
-      # already the one thing this method has ever supplied. `build`'s own
+      # answering for an entity target does not "invent an entity identity",
+      # just as answering for a plain one invents none; it is
+      # the one thing this method supplies. `build`'s own
       # explicit branch (below) already applies this correctly either way
       # (`aggregate_identity ||= inherited_receiver`, entity identities read
       # from `args` regardless) — the caller that actually needed a guard

data/lib/hecks/runtime/read_model_interpreter.rb

@@ -33,6 +33,8 @@ module Hecks
       # @raise [KeyError] if a rooted read model is asked without its reference argument
       # @raise [ArgumentError] if `group_by` or `median` names a field its target
       #   aggregate does not declare
+      # @raise [Runtime::InvariantViolation] if two rows reach the same full `group_by`
+      #   key path and that path does not cover the grouped aggregate's whole identity
       # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
       def call(domain, model, args)
         project(domain, model, args)
@@ -148,7 +150,8 @@ module Hecks
         reduced_head = aggregation_target(model, bluebook)
         [heads.each_with_object({}) do |(as, value), out|
           out[as] = if grouped_head && as == grouped_head[:as]
-                      nest(value.map { |record| Value.materialize_unwrapped(row(record)) }, model.group_by_fields)
+                      nest(value.map { |record| Value.materialize_unwrapped(row(record)) }, model.group_by_fields,
+                           collision_check(model, bluebook, grouped_head))
                     elsif reduced_head && as == reduced_head[:as] && model.count?
                       value.length
                     elsif reduced_head && as == reduced_head[:as]
@@ -267,28 +270,47 @@ module Hecks
         target
       end
 
+      # The read model whose `group_by` leaves must each hold one row, or nil
+      # when its key path covers the grouped aggregate's whole identity and so
+      # cannot collide (ADR 0061, decision D1). Decided from the declaration,
+      # never from the rows.
+      def collision_check(model, bluebook, grouped_head)
+        model.groups_by_identity?(bluebook.aggregate(grouped_head[:aggregate])) ? nil : model
+      end
+
       # One level of nesting per field, in `group_by`'s own declared
       # order — the leaf is the row with every grouped field removed
-      # (already spent, as the keys that reached it). Assumes the full
-      # `group_by` path uniquely identifies one row (true for grouping by
-      # an aggregate's own full identity, ConsoleSettings' own real use)
-      # — `leaves.first` silently keeps only the first row when several
-      # share the same full key path. A real, deliberate scope limit:
-      # true multi-row-per-leaf grouping would change the leaf shape
-      # from "one row" to "an array of rows", which no caller needs yet.
-      def nest(rows, fields)
+      # (already spent, as the keys that reached it). A leaf holds one row:
+      # when `checked` names a read model and two rows reach the same full
+      # key path, this refuses rather than keep one of them (ADR 0061,
+      # decision D1). An array-of-rows leaf would change the output shape
+      # of every shipped `group_by`, so it is not offered here.
+      #
+      # Groups are walked in first-occurrence order and depth first, so the
+      # collision reported is the first one reached; the Rust kernel's
+      # `read_model::nest` walks in the same order.
+      def nest(rows, fields, checked, reached = [])
         field, *rest = fields
-        rows.group_by { |row| row[field] }.transform_values do |group|
+        rows.group_by { |row| row[field] }.to_h do |key, group|
           # Strip only the field just grouped by, not the whole remaining
           # list — `rest`'s own fields have to survive into the recursive
-          # call below, or the next level groups by a key that's already
-          # gone (found by trying it: a two-field group_by's own second
-          # level came back keyed `nil` for every group, every time).
-          stripped = group.map { |row| row.reject { |key, _| key == field } }
-          rest.empty? ? stripped.first : nest(stripped, rest)
+          # call below, or the next level groups by a key that's already gone.
+          stripped = group.map { |row| row.reject { |name, _| name == field } }
+          path = reached + [[field, key]]
+          [key, rest.empty? ? leaf(stripped, checked, path) : nest(stripped, rest, checked, path)]
         end
       end
 
+      def leaf(rows, checked, path)
+        return rows.first unless checked && rows.size > 1
+
+        raise InvariantViolation,
+              RefusalWording.render_site("InvariantViolation", "group_by_collision",
+                                         read_model: checked.name, fields: checked.group_by_fields,
+                                         ids: rows.map { |row| row[:id] },
+                                         key: path.map { |field, value| "#{field} = #{value}" }.join(", "))
+      end
+
       # `count`/`median`'s own declared target — the same single
       # many-side head `group_by_target` resolves, for the same reason
       # (`seal_aggregation` already refuses zero or several many-side

data/lib/hecks/runtime/reference_hop.rb

@@ -45,7 +45,7 @@ module Hecks
       #   Options, Hecks::Runtime::ReferenceHop::Folded] `declared` unchanged when it has no
       #   hop clauses; otherwise a `Folded` wrapper whose `#wheres` replaces each hop clause
       #   with its folded `in` clause
-      # @raise [Runtime::WiringError] if a hop's target no longer resolves (see `fold`)
+      # @raise [Runtime::WiringError] if a hop's target does not resolve (see `fold`)
       def apply(declared, args, registry:, domain:, aggregate:)
         hopped, local = declared.wheres.partition { |clause| QuerySpecification::HopPath.hop_head?(clause.field, aggregate.attributes) }
         return declared if hopped.empty?
@@ -65,7 +65,7 @@ module Hecks
       # @param aggregate [Bluebook::Aggregate] the aggregate `clause` is declared against
       # @return [QuerySpecification::Common::WhereClause] a synthetic `in` clause on the hop
       #   attribute's name, whose value is every id the inner clause admits on the target
-      # @raise [Runtime::WiringError] if the hop's target aggregate no longer resolves
+      # @raise [Runtime::WiringError] if the hop's target aggregate does not resolve
       def fold(clause, args, registry:, domain:, aggregate:)
         step = QuerySpecification::HopPath.next_hop(clause.field, aggregate.attributes)
         hop, rest = step
@@ -74,7 +74,7 @@ module Hecks
         # this exact clause before the domain ever booted. Held anyway:
         # an unresolvable target folding silently to "matches
         # everything" is precisely the failure shape this whole feature
-        # exists to close, and a hop that can no longer resolve (a
+        # exists to close, and a hop that cannot resolve (a
         # target aggregate unloaded after boot, say) is a real fact
         # worth a real error, not a query that quietly stops filtering.
         unless hop&.target
@@ -106,7 +106,7 @@ module Hecks
       # @param registry [Runtime::Registry] the booted registry to resolve `target`'s
       #   repository from
       # @return [Array<String>] every distinct id the inner clause(s) admit on `target`
-      # @raise [Runtime::WiringError] if a hop nested inside `wheres` no longer resolves
+      # @raise [Runtime::WiringError] if a hop nested inside `wheres` does not resolve
       def matching_ids(domain, target, wheres, args, registry:)
         spec       = apply(QuerySpecification::Common::Options.new(wheres: wheres), args,
                            registry: registry, domain: domain, aggregate: target)