hecks 2.8.0 → 3.0.0

data/lib/hecks/language/hecksagon/port_operation.bluebook

@@ -7,17 +7,8 @@ Hecks.bluebook "Hecksagon" do
     attribute :attributes, list_of(PortOperationField)
     attribute :emits,      list_of(EmittedEvent)
 
-    # THE TWO ENDINGS OF AN `asks`, held by the language about itself.
-    #
-    # `emits` above is what an inbound `tells` says once the fact is in.
-    # These two are the outbound half: what the adapter came back with, and
-    # what it said instead. Singular where `emits` is a list, because an ask
-    # has exactly one of each — a call that could answer two different ways
-    # is two calls.
-    #
-    # Empty on every `tells`, which is why neither carries an invariant
-    # demanding a value; `PortOperationBuilder` refuses the wrong word for
-    # the direction long before a record gets here.
+    # The two endings of an `asks`: what the adapter answered, or what it refused with.
+    # Singular because an ask has exactly one of each; empty on every `tells`, so no invariant.
     attribute :answers,    AnsweringEvent
     attribute :refuses,    RefusingEvent
 
@@ -44,9 +35,7 @@ Hecks.bluebook "Hecksagon" do
       attribute :value, String
     end
 
-    # HOW PORTOPERATION IS SPELLED. These rows live with the concept
-    # they describe; SyntaxBoot discovers every aggregate-local seed table.
-    # Contexts represented here: PortOperation.
+    # Keyword rows for PortOperation; SyntaxBoot discovers every aggregate-local seed table.
     value_object "KeywordSeed" do
       attribute :word,          String
       attribute :context,       String, admits: "Syntax::Context"

data/lib/hecks/language/oidc.json

@@ -236,6 +236,21 @@
       "verb": "Bluebook::Query.Option",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:read_model.all",
+      "verb": "Bluebook::ReadModel.All",
+      "role": "Language"
+    },
+    {
+      "scope": "bluebook:read_model.any",
+      "verb": "Bluebook::ReadModel.Any",
+      "role": "Language"
+    },
+    {
+      "scope": "bluebook:read_model.avg",
+      "verb": "Bluebook::ReadModel.Avg",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:read_model.count",
       "verb": "Bluebook::ReadModel.Count",
@@ -256,16 +271,36 @@
       "verb": "Bluebook::ReadModel.GroupBy",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:read_model.max",
+      "verb": "Bluebook::ReadModel.Max",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:read_model.median",
       "verb": "Bluebook::ReadModel.Median",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:read_model.min",
+      "verb": "Bluebook::ReadModel.Min",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:read_model.option",
       "verb": "Bluebook::ReadModel.Option",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:read_model.percentile",
+      "verb": "Bluebook::ReadModel.Percentile",
+      "role": "Language"
+    },
+    {
+      "scope": "bluebook:read_model.sum",
+      "verb": "Bluebook::ReadModel.Sum",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:syntax.argument",
       "verb": "Bluebook::Syntax.Argument",

data/lib/hecks/language/port.bluebook

@@ -25,14 +25,8 @@ Hecks.bluebook "Port" do
       attribute :value, String, one_of: ["reply", "effect"]
     end
 
-    # THE METHOD CONTRACT — what an adapter must actually `respond_to?`
-    # for a dispatch through this door to reach it, as opposed to `verb`
-    # and `signal`, which only ever describe the door itself. Optional
-    # the same way `verb` is (a port declared with none is exactly
-    # today's pre-existing behavior, unchecked past `verify!`'s existing
-    # gates), and a plain list of method names rather than a richer
-    # shape — the same restraint `AdapterField` already takes for
-    # `field`/`secret`.
+    # The method contract: what an adapter must `respond_to?` for a dispatch through this door.
+    # A port that declares none is unchecked beyond `verify!`.
     value_object "PortAnswer" do
       attribute :value, String
       invariant("an answer names a real method") { !value.to_s.empty? }
@@ -43,12 +37,7 @@ Hecks.bluebook "Port" do
       goal "Open a resource door a domain's own aggregates may call by verb"
 
       attribute :name,   PortName
-      # OPTIONAL — real, pre-existing PortBuilder behavior (spec/dsl_spec
-      # .rb's own "signal says whether the domain gets a value back..."
-      # builds a port with only `signal`, never calling `verb` at all;
-      # `def verb(value)` has no default, unlike `signal`'s `:reply`).
-      # Same asymmetry world.bluebook's own Declare command already has
-      # for `realm`/`latest`.
+      # Optional: a port may declare only `signal`; `verb` has no default, unlike `signal`.
       attribute :verb,   PortVerb, optional: true
       attribute :signal, PortSignal
 
@@ -71,9 +60,7 @@ Hecks.bluebook "Port" do
       emits "PortAnswerAdded"
     end
 
-    # HOW PORT IS SPELLED. These rows live with the concept
-    # they describe; SyntaxBoot discovers every aggregate-local seed table.
-    # Contexts represented here: File, Port.
+    # Keyword rows for File and Port; SyntaxBoot discovers every aggregate-local seed table.
     value_object "KeywordSeed" do
       attribute :word,          String
       attribute :context,       String, admits: "Syntax::Context"

data/lib/hecks/language/translation/translation.bluebook

@@ -24,12 +24,8 @@ Hecks.bluebook "Translation" do
       invariant("a name says something") { !value.to_s.empty? }
     end
 
-    # ARBITRARY, UNVALIDATED CAPTURE — `convert`'s own `values:` table and
-    # `backfill`'s own `default:` are open-ended (any literal a real
-    # migration needs), the same shape `AggregateBuilder#provenance`/
-    # `CommandBuilder#provenance` already capture as plain, unvalidated
-    # text (`LiteralText`, aggregate.bluebook) rather than a fixed
-    # attribute shape a closed self-hosted record could enumerate.
+    # `convert` values and `backfill` defaults are open-ended literals, so they are held as
+    # unvalidated text, like `provenance` (`LiteralText`, aggregate.bluebook).
     value_object "TranslationLiteralText" do
       attribute :value, String
     end
@@ -60,9 +56,7 @@ Hecks.bluebook "Translation" do
       emits "TranslationAggregateRetired"
     end
 
-    # HOW TRANSLATION IS SPELLED. These rows live with the concept
-    # they describe; SyntaxBoot discovers every aggregate-local seed table.
-    # Contexts represented here: File, Translation.
+    # Syntax seed rows for the words this aggregate spells; SyntaxBoot discovers them.
     value_object "KeywordSeed" do
       attribute :word,          String
       attribute :context,       String, admits: "Syntax::Context"

data/lib/hecks/language/translation/translation_aggregate.bluebook

@@ -6,22 +6,8 @@ Hecks.bluebook "Translation" do
 
     identified_by TranslationAggregateName, as: :name
 
-    # `TranslationAggregateName` — a DEDICATED type for the identity
-    # field, not the shared `TranslationName` every non-identity field
-    # below uses. Found live, not by inspection: reusing one value-
-    # object type for BOTH an aggregate's own identity field and a
-    # sibling non-identity field on the same aggregate broke the
-    # single-field-VO identity-unwrap path — the stored `id` came back
-    # as a stringified Hash (`"{:value=>\"Account\"}"`) instead of the
-    # bare scalar (`"Account"`), so a self-reference to this aggregate
-    # could never find the record `Declare` had just created. Reusing
-    # the SAME type across MULTIPLE identity fields (Translation's own
-    # `TranslationEraName`, for both `from` and `to`) is unaffected —
-    # confirmed directly, not assumed — so the real trigger is identity
-    # + non-identity sharing, not reuse itself. A genuine framework bug,
-    # out of scope to fix here; every other self-hosted construct in
-    # this language already avoids it by convention (a dedicated type
-    # per identity field), which this now matches too.
+    # A dedicated identity type: sharing `TranslationName` with a non-identity field breaks the
+    # single-field identity unwrap, storing the id as a stringified Hash instead of a scalar.
     attribute :was,  TranslationName, optional: true
 
     value_object "TranslationAggregateName" do
@@ -47,11 +33,8 @@ Hecks.bluebook "Translation" do
     attribute :rekeys,    list_of(TranslationRekey)
     attribute :backfills, list_of(TranslationBackfill)
 
-    # Field names throughout mirror lib/hecks/bluebook/translation.rb
-    # EXACTLY (`Struct.new(:from, :to)` etc.) — the real Ruby records
-    # TranslationJudge dispatches from, not the builder's own local
-    # parameter names (`move(old_path, to:)`'s `old_path` becomes the
-    # struct's own `from`).
+    # Field names mirror the Struct records in lib/hecks/bluebook/translation.rb, not the
+    # builder's parameter names (`move(old_path, to:)` stores `old_path` as `from`).
     value_object "TranslationRename" do
       attribute :from, TranslationName
       attribute :to,   TranslationName
@@ -199,9 +182,7 @@ Hecks.bluebook "Translation" do
       emits "TranslationBackfillAdded"
     end
 
-    # HOW TRANSLATIONAGGREGATE IS SPELLED. These rows live with the concept
-    # they describe; SyntaxBoot discovers every aggregate-local seed table.
-    # Contexts represented here: TranslationAggregate.
+    # Syntax seed rows for the words this aggregate spells; SyntaxBoot discovers them.
     value_object "KeywordSeed" do
       attribute :word,          String
       attribute :context,       String, admits: "Syntax::Context"

data/lib/hecks/language/world/wiring.bluebook

@@ -7,9 +7,7 @@ Hecks.bluebook "World" do
     # so the bare reference name would collide with it.
     belongs_to World, as: :world_ref
 
-    # THE WORLD IT IS IN, AND THE VERB IT ANSWERS. One world binds one adapter per
-    # verb — that is what a binding IS — so the verb names the wiring, and the
-    # world says whose.
+    # One world binds one adapter per verb, so the verb names the wiring and the world says whose.
     identified_by :world, :verb
 
     attribute :world,    WiringText

data/lib/hecks/language/world/world.bluebook

@@ -59,9 +59,8 @@ Hecks.bluebook "World" do
       emits "WorldDeclared"
     end
 
-    # HOW WORLD IS SPELLED. These rows live with the concept
-    # they describe; SyntaxBoot discovers every aggregate-local seed table.
-    # Contexts represented here: File, World.
+    # Spelling rows for World keywords; SyntaxBoot discovers every
+    # aggregate-local seed table like this one.
     value_object "KeywordSeed" do
       attribute :word,          String
       attribute :context,       String, admits: "Syntax::Context"
@@ -77,10 +76,9 @@ Hecks.bluebook "World" do
       member word: "world",           context: "File",     body: "keywords", inner: "World",          opens: "World",          fills: ""
       member word: "realm",           context: "World",     body: "none", inner: "", opens: "", fills: "realm", calls: "realm_impl"
       member word: "latest",          context: "World",     body: "none", inner: "", opens: "", fills: "latest", calls: "latest_impl"
-      # THE TWO CROSS-CHAPTER DEFAULTS — the same connection string and the
-      # same persistence adapter every chapter of a project repeats, written
-      # once. A chapter's own world (`persisted_by ... database`) and its own
-      # hecksagon bind still win; see docs/implemented/reference/world.md.
+      # The connection string and persistence adapter every chapter of a
+      # project would otherwise repeat, written once here; a chapter's own
+      # world or hecksagon bind still wins.
       member word: "default_database", context: "World", body: "none", inner: "", opens: "", fills: "default_database", calls: "default_database_impl"
       member word: "default_adapter",  context: "World", body: "none", inner: "", opens: "", fills: "default_adapter", calls: "default_adapter_impl"
 

data/lib/hecks/literal.rb

@@ -1,45 +1,13 @@
 module Hecks
-  # The one spelling for a captured Ruby literal on the wire.
-  #
-  # Several `to_h` fields hold a value the author wrote in a bluebook —
-  # `where(status: { eq: "open" })`, `then_set append: { direction: { value:
-  # "credit" } }`, `dispatch ... with: { number: :source }`, an attribute's
-  # `default:` — as text, because the export has to stand on its own and a
-  # String field cannot say "this one was a Symbol". Every such field is the
-  # same question and now gets the same answer.
-  #
-  # It was three answers before, and they disagreed on both axes that matter.
-  # `Mutation#appended_fields` spelled a Symbol bare and everything else
-  # `inspect`; `QuerySpecification.render_value` spelled a Symbol with a colon
-  # and everything else `to_s`. So `:amount` crossed as "amount" in a mutation
-  # and ":amount" in a saga binding — the same value, two spellings, and each
-  # reader had to know which field it was looking at. Worse, `to_s`/`inspect`
-  # on a Hash is Ruby's own rendering, which moved under us: 3.3 writes
-  # `{:value=>"credit"}` and 3.4 writes `{value: "credit"}` for the identical
-  # Hash, so the wire format was silently pinned to an interpreter version.
-  #
-  # Self-describing is the rule, stated once here rather than inherited from
-  # whatever `inspect` happens to do: a symbol wears its colon, a string wears
-  # its quotes, a hash wears `{key: value}` braces, a list wears its brackets,
-  # and a number, a boolean and nil are bare. `read` is the exact inverse, and
-  # is the only thing that should ever take one of these strings apart.
-  # A mutation source that reads the record's own state — `sets :positions,
-  # append: { knights: state(:knights) }`. A bare Symbol in a mutation
-  # source always names a command argument (and imports it as one when
-  # the target's own field carries the same name — `CommandBuilder
-  # #resolve_append_fields!`); before this there was no way to say "the
-  # value this field already holds", so a command could not snapshot its
-  # own record — chess's threefold repetition needs exactly that, a
-  # position copied off the board every ply. Spelled `state(:name)` on
-  # the wire, read back by `Literal.read`; classified `kind: "state"` in
-  # a set's own source (`Behaviour::Mutation#classified_source`).
+  # A mutation source that reads the record's own state: `append: { knights: state(:knights) }`.
+  # A bare Symbol in a mutation source names a command argument, so this is the only way to say it.
   StateRef = Struct.new(:name) do
     def to_s = "state(:#{name})"
   end
 
-  # The `render`/`read` pair the header above describes: `render` turns a
-  # Ruby value into its self-describing wire spelling, `read` is its exact
-  # inverse.
+  # The one wire spelling for a Ruby literal captured from a bluebook: a symbol wears its
+  # colon, a string its quotes, a hash `{key: value}`, a list brackets; the rest are bare.
+  # Stated here, not left to `inspect`, whose Hash rendering differs between Ruby 3.3 and 3.4.
   module Literal
     module_function
 
@@ -63,16 +31,9 @@ module Hecks
       end
     end
 
-    # Read one back. Tolerant of a bare word on purpose: the language stores a
-    # closed set's members and a few hand-written fields as plain text that was
-    # never rendered, and those must stay the strings they are.
+    # Parses a wire spelling back into a Ruby value; the exact inverse of `render`.
+    # A bare word stays a String, since some fields are stored as plain text, never rendered.
     #
-    # The exact inverse of `render`'s `case`, above — one ordered guard per
-    # spelling `render` can produce (plus the bare-word tolerance this
-    # comment already explains). Each guard is a single self-contained
-    # `return`; splitting them into named predicates would just rename
-    # each line without changing what it does, and would separate this
-    # method from the `render` it is the deliberate mirror of.
     # @param text [String, #to_s] wire spelling produced by `render`, or a bare word
     # @return [Object] nil, true, false, Integer, Float, Symbol, StateRef, String,
     #   Hash, or Array — or `text` itself, stripped, when it matches no known spelling
@@ -131,10 +92,7 @@ module Hecks
     # @return [Array<Object>] the parsed values, each read recursively via `read`
     def read_array(raw) = split_items(raw[1..-2]).map { |item| read(item) }
 
-    # Split on the commas that are actually separators — never one inside a
-    # quoted string or a nested brace/bracket. Scanned rather than
-    # `String#split(", ")`, which tore `"a, b"` in half and lost the second
-    # field of anything nested.
+    # Splits on separator commas only, never one inside a quoted string or nested brace/bracket.
     #
     # @param body [String] the text between a literal's outer braces or brackets
     # @return [Array<String>] each item's raw text, stripped, with empty items dropped

data/lib/hecks/mcp_stdio_guard.rb

@@ -1,41 +1,8 @@
 require "socket"
 
 module Hecks
-  # The startup gate for the stdio MCP servers in `bin/` (`hecks_mcp_door`,
-  # `hecks_query_ir_mcp`): it refuses to run when the process was set up to
-  # speak to anything but a local parent, and it says on stderr what the
-  # process does and does not protect.
-  #
-  # ## Why a gate and not a comment
-  #
-  # Both servers have no authentication. What keeps a stranger away from
-  # them is that only a process that can spawn them can write to their
-  # stdin. That holds until someone wraps one in `socat TCP-LISTEN:... EXEC:`
-  # or an `inetd`-style listener, which hands the process a network socket
-  # as stdin/stdout without changing a line of the server. The gate turns
-  # that setup into a refusal at startup instead of an exposure nobody
-  # noticed.
-  #
-  # ## What it checks
-  #
-  # - **Arguments** — none, except `--stdio`. A `--port` or `--http` flag is
-  #   refused rather than ignored, so a caller that believes it started a
-  #   network server finds out immediately.
-  # - **Environment** — no `HECKS_MCP_*` variable except
-  #   `HECKS_MCP_TRANSPORT=stdio`. The servers take no configuration, so an
-  #   unknown option in that namespace fails closed.
-  # - **Descriptors** — stdin and stdout must not be internet-protocol sockets
-  #   (`AF_INET` or `AF_INET6`). A pipe, a file, a terminal and a Unix-domain socket all pass;
-  #   the last matters because some MCP clients spawn servers over a
-  #   `socketpair`, which is local to the machine.
-  #
-  # ## What it does not do
-  #
-  # It does not authenticate anyone and it cannot see a proxy that copies
-  # bytes from a network socket into an ordinary pipe. It closes the
-  # configurations that announce themselves; the ADR on MCP authentication
-  # (`docs/decisions/0062-mcp-servers-need-real-authentication-before-any-network-transport.md`)
-  # covers what a network transport would need.
+  # Startup gate for the stdio MCP servers `hecks mcp` runs: refuses network sockets, extra
+  # flags and unknown `HECKS_MCP_*` variables. It is not authentication (ADR 0062).
   module McpStdioGuard
     ACCEPTED_ARGS = %w[--stdio].freeze
     ENV_PREFIX    = "HECKS_MCP_".freeze
@@ -71,12 +38,8 @@ module Hecks
       (COMMON_NOTES + notes).map { |line| "#{server}: #{line}" }
     end
 
-    # Refuses to continue on a non-stdio setup.
-    #
-    # A server calls this before it requires anything heavy, so a misconfigured start
-    # fails in milliseconds and before any protocol byte is answered. Everything goes
-    # to `stderr`: stdout carries the MCP protocol, and one stray line there corrupts
-    # the client's framing.
+    # Refuses to continue on a non-stdio setup. Everything goes to `stderr`: stdout
+    # carries the MCP protocol, and a stray line there corrupts the client's framing.
     #
     # @param server [String] the server's name, used as the line prefix
     # @param argv [Array<String>] the command-line arguments

data/lib/hecks/naming.rb

@@ -1,19 +1,9 @@
 module Hecks
-  # Every derived-name and identity-joining rule the language relies on —
-  # pluralisation/singularisation, snake/Pascal casing, dotted-path and verb
-  # splitting, and the command/event reference rewrites — collected here so
-  # two readers never invent two different spellings for the same
-  # derivation.
+  # Derived-name and identity-joining rules: casing, pluralisation, dotted-path
+  # and verb splitting, command/event reference rewrites.
   module Naming
-    # What separates the parts of a derived identity.
-    #
-    # An identity of several parts is their join, and the join has to be spelled the
-    # same everywhere or two readers name two different records off one declaration.
-    # It was spelled three ways at once here — "::" for an aggregate under a
-    # chapter, "." for everything under an aggregate, "#" for the three that keyed
-    # off position — and each was written where it happened to be needed. Once the
-    # runtime derived the same identity, the runtime made a fourth, and a reference
-    # that resolved by string comparison found nothing.
+    # What separates the parts of a derived identity. Every reader must spell the
+    # join the same way, or string-compared references resolve to nothing.
     IDENTITY_JOIN = ":".freeze
 
     module_function
@@ -35,9 +25,8 @@ module Hecks
       type.to_s.split("::").last.to_s
     end
 
-    # snake_case -> PascalCase. The name a synthesised closed-set value object
-    # takes when an attribute declares one inline. The derivation is part of
-    # the IR contract: the same bluebook must always produce the same name.
+    # snake_case -> PascalCase. Names a closed-set value object synthesised from an
+    # inline attribute; the derivation is part of the IR contract.
     #
     # @param text [String, Symbol, #to_s] a snake_case (or already Pascal) name
     # @return [String] the PascalCase form
@@ -56,15 +45,8 @@ module Hecks
           .downcase
     end
 
-    # An identifier as a person would say it — `ATMCard` -> "ATM card",
-    # `AccrueInterest` -> "Accrue interest", `daily_limit` -> "Daily
-    # limit", `Back office` -> "Back office". The same two word-boundary
-    # splits `snake` uses, with a space instead of an underscore — plus
-    # the one thing `snake` cannot give back: an all-caps run stays an
-    # acronym ("ATM", "KYC") instead of being lowercased into a word
-    # nobody says ("Atm"). First word capitalized, the rest lowercased,
-    # so a headword reads as sentence case whatever casing it was
-    # declared in.
+    # An identifier as a sentence-cased phrase: `ATMCard` -> "ATM card",
+    # `daily_limit` -> "Daily limit". All-caps runs stay acronyms.
     #
     # @param text [String, Symbol, #to_s] a Pascal-, camel-, or snake-case identifier
     # @return [String] the space-separated, sentence-cased phrase
@@ -81,9 +63,7 @@ module Hecks
       end.join(" ")
     end
 
-    # Joins items into the Oxford-comma list — "A, B, and C" / "A or B" —
-    # every English sentence a projection writes wants; lived in
-    # `NarrateProjector` alone until a second projection needed it.
+    # Joins items into an Oxford-comma list: "A, B, and C" / "A or B".
     #
     # @param items [Array<#to_s>] the items to join
     # @param conj [String] the word before the last item, such as `"and"` or `"or"`
@@ -98,9 +78,8 @@ module Hecks
       end
     end
 
-    # Picks the article for `word` by its first letter — the vowel-letter
-    # heuristic, safe here for the same reason `Projections::Statements#article`
-    # gives: a construct name is a plain word, never "hour" or "university".
+    # Picks the article for `word` by its first letter. Construct names are plain
+    # words, never "hour" or "university", so the vowel-letter heuristic holds.
     #
     # @param word [String, Symbol, #to_s] the word the article precedes
     # @return [String] `"an"` if `word` starts with a vowel letter, `"a"` otherwise
@@ -108,15 +87,8 @@ module Hecks
       %w[a e i o u].include?(word.to_s[0].to_s.downcase) ? "an" : "a"
     end
 
-    # The name a collection of something takes.
-    #
-    # There were two of these and one was wrong. A read model's gathered heads
-    # derived their name with a bare `"#{snake(target)}s"`, so the meta-domain's
-    # own whole-bluebook read model handed back `querys`, `entitys`, `policys`
-    # and `dispatchs` — and every check was green, because the checks compared
-    # the wrong rule against itself. Agreement is not correctness; it never was.
-    #
-    # So: one pluraliser, three rules, and every collection name flows through it.
+    # The name a collection of something takes: "y" -> "ies", sibilants take "es",
+    # everything else "s". Every collection name must flow through this one rule.
     #
     # @param text [String, Symbol, #to_s] a singular name
     # @return [String] the pluralised name
@@ -128,13 +100,9 @@ module Hecks
       "#{word}s"
     end
 
-    # `has_many`'s undo — the plural written, back to the singular the target
-    # aggregate is actually named. Deliberately the crude half of a pair: `plural`
-    # above earns its precision (three suffix rules) because getting a collection
-    # name wrong reads as a typo forever ; this only ever recovers a name someone
-    # already wrote as a real aggregate, so "ies -> y, trailing s dropped" is the
-    # whole rule — enough for `has_many Invoices` to resolve to the aggregate
-    # actually named Invoice.
+    # Recovers the singular aggregate name from a `has_many` plural. Deliberately
+    # crude ("ies" -> "y", sibilant "es" and trailing "s" dropped): it only has to
+    # find a name someone already wrote.
     #
     # @param text [String, Symbol, #to_s] a plural name
     # @return [String] the singularised name
@@ -142,15 +110,8 @@ module Hecks
       word = text.to_s
       return "#{word[0..-4]}y" if word.length > 3 && word.end_with?("ies")
 
-      # `plural`'s own second rule adds "es" (not bare "s") after
-      # s/x/z/ch/sh — undone here the same way, or a word `plural`
-      # itself would have suffixed with "es" comes back missing its
-      # own trailing letter ("Boxes" -> "Boxe", not "Box") once this
-      # only ever knew how to drop a bare "s". Checked before the
-      # bare-"s" rule below: stripping "es" first and confirming what
-      # is left actually ends in one of those five shapes is what
-      # keeps an ordinary "-es" word (e.g. "Invoices" -> "Invoice")
-      # from also losing a letter it never doubled.
+      # Undo `plural`'s "es" after s/x/z/ch/sh before the bare-"s" rule, so "Boxes"
+      # gives "Box" while "Invoices" still gives "Invoice".
       return word[0..-3] if word.length > 3 && word.end_with?("es") && word[0..-3].match?(/(s|x|z|ch|sh)\z/)
 
       return word[0..-2] if word.length > 1 && word.end_with?("s")
@@ -199,29 +160,9 @@ module Hecks
 
     # Splits a domain-qualified verb into its domain, aggregate, and command parts.
     #
-    # Domain, aggregate, then the REST dot-joined into one command path.
-    #
-    # The `::` boundary between domain and aggregate is unambiguous by
-    # construction — every caller here has already prefixed the domain
-    # itself (`PolicyInterpreter#deliver`, `SagaInterpreter#qualified`,
-    # `Router#dispatch`'s own rebuilt string) before this ever runs. A
-    # third `::` segment can still show up past that boundary: a bare
-    # `ScopedConstant` naming a port operation (`command_ref`'s own
-    # comment — `Aggregate::Port::Operation`, three colon-joined
-    # segments with no `.` of its own) only gets its last `::` rewritten
-    # to `.` there, at DSL-build time, because nothing at that point
-    # knows yet whether the constant names a port operation or a
-    # domain-qualified command (`Domain::Aggregate::Command`, the other
-    # shape `command_ref` documents) — both are textually identical.
-    # Here, past the already-resolved domain boundary, any leftover
-    # `::` is unambiguous: it is that same rewrite artifact, and folding
-    # it into the dot-joined tail recovers exactly the
-    # `Aggregate::Port.Operation` shape a working port dispatch already
-    # expects (`spec/port_operation_interpreter_spec.rb`'s own
-    # `"Payments::Payment.PaymentGateway.Receive"`). `Outbox::Fanout
-    # .kind_for` and `ReactionInvocation#resolve_target` both already
-    # assume this contract on their own end; this is what actually
-    # delivers it to them.
+    # A `::` left after the domain and aggregate is the last-`::`-to-`.` rewrite
+    # `command_ref` leaves on a port operation; it folds into the dotted command
+    # tail (`Aggregate::Port.Operation`).
     #
     # @param verb [String, Symbol, #to_s] a `Domain::Aggregate.command` (or
     #   `.query`) path
@@ -239,26 +180,11 @@ module Hecks
       [domain, aggregate, command]
     end
 
-    # Rewrites a bare command constant's trailing `::` into `.`, matching a
-    # command's own FQN separator; a String or Symbol passes through unchanged.
+    # Rewrites a bare command constant's last `::` into `.`, matching a command's
+    # FQN separator (`Banking::Account::Debit` -> `Banking::Account.Debit`).
     #
-    # `trigger Account::Debit` / `dispatch Account::Debit` — a bare
-    # constant reference (`ConstShim`'s own `ScopedConstant`, S0b), not
-    # text (ADR 0025, "events and reactions" — command references become
-    # first-class). Ruby's `::` joins every segment the same way a
-    # constant path always does, but a command's own `hecks_fqn` joins
-    # its aggregate with `.` (`Construct#hecks_separator`'s default,
-    # only an aggregate overrides it to `::`) — so only the last `::`
-    # becomes a `.`; everything before it (the chapter, when a domain is
-    # spelled at all: `Banking::Account::Debit`) stays `::`-joined.
-    #
-    # A string passes through unchanged, on purpose — legacy era text
-    # (S0a's own shadow-parsed spelling) already mixes `::` (domain) and
-    # `.` (command) correctly on its own, e.g. `"Banking::Account.Debit"`,
-    # and re-splitting that by content rather than by type would corrupt
-    # it (its own last `::` sits between the domain and the aggregate,
-    # not the aggregate and the command). Only an actual constant object
-    # — never seen holding a `.` of its own — needs the rewrite at all.
+    # A String or Symbol passes through: era text already mixes `::` and `.`
+    # correctly, and re-splitting it by content would corrupt it.
     #
     # @param value [Symbol, String, Module] the command, as a bare constant (a
     #   `ScopedConstant` module `ConstShim` resolves) or already-dotted text
@@ -271,18 +197,8 @@ module Hecks
       path.empty? ? text : "#{path}.#{command}"
     end
 
-    # The event-side twin of `command_ref`, kept as its own name because an
-    # event name is not a command name that happens to share a format.
-    #
-    # `emits Account::AccountFrozen` / `on Account::AccountFrozen` — the
-    # event-side twin of `command_ref`, above (ADR 0025, S6 — "events
-    # first-class"). Identical transform (a bare `ScopedConstant`'s last
-    # `::` becomes `.`, a String passes through unchanged for legacy
-    # `shadow_parse` text and for corpus sites this pass didn't migrate —
-    # see that method's own comment for why both rules exist), given its
-    # own name because the two references mean different things even
-    # though the rewrite is byte-identical: an event name is not a
-    # command name that happens to share a format.
+    # The event-side twin of `command_ref`. Same rewrite, separate name, because an
+    # event reference is not a command reference that happens to share a format.
     #
     # @param value [Symbol, String, Module] the event, as a bare constant (a
     #   `ScopedConstant` module `ConstShim` resolves) or already-dotted text
@@ -291,32 +207,8 @@ module Hecks
 
     # Strips a process manager's event reference down to its bare event name.
     #
-    # `transition Account::AccountDebited => "state"` / `starts_on
-    # Transfer::TransferRequested` / `ends_on Transfer::TransferSettled`
-    # — a process manager's own event references (ADR 0025, S6),
-    # deliberately not `event_ref` — found live, not assumed, wiring a
-    # real migrated corpus site into `bin/model_check` for the first
-    # time (2026-08-28): `SagaInterpreter#begin_saga`/`#advance_saga`
-    # match `pm.starts_on`/`pm.handler_for` against `event.name`, which
-    # `CommandRules::Emission#emit` stamps bare — a command's own
-    # `emits AccountDebited` never carries its aggregate's name at all
-    # (unlike a policy's cross-aggregate `on`, matched instead by
-    # `Naming.demodulise(event.aggregate)` split apart from the bare
-    # name — `PolicyInterpreter#policies_for`). Handing a saga's own
-    # matcher the dotted `event_ref` form ("Account.AccountDebited")
-    # would silently name an event no command in the domain ever
-    # actually emits — caught by `bin/model_check`'s own `deaf_handler`/
-    # `deaf_trigger` findings the moment a real qualified corpus site
-    # existed to trip them, not by any unit test in isolation.
-    #
-    # A qualifier is still worth writing (`Account::`) — the same
-    # provenance a reader gets from `trigger Account::Debit` — it is
-    # only not worth keeping: `demodulise` drops everything but the
-    # final segment, so `Account::AccountDebited` and a bare
-    # `AccountDebited` resolve to the identical stored string. A String
-    # passes through unchanged either way, exactly like `command_ref`'s
-    # own legacy branch — this corpus never spelled one dotted to begin
-    # with, so there is nothing here to strip.
+    # Not `event_ref`: saga matching compares against `event.name`, which is stamped
+    # bare, so a dotted "Account.AccountDebited" would name an event nothing emits.
     #
     # @param value [Symbol, String, Module] the event, as a bare constant (a
     #   `ScopedConstant` module `ConstShim` resolves) or already-dotted text