hecks 2.7.0 → 2.9.0

data/lib/hecks/language/bluebook/attaches/paging.bluebook

@@ -3,16 +3,8 @@ Hecks.bluebook "Paging" do
   generic
   attaches_to "Query", "ReadModel"
 
-  # A PLACE TO HOLD ROWS, AND NOTHING ELSE — the same shape `Vocabulary`
-  # (vocabulary.bluebook) already is: no commands, because nothing ever
-  # dispatches this aggregate for real. `SyntaxBoot`'s own generic
-  # discovery reads `KeywordSeed`/`ArgumentSeed`'s rows straight off the
-  # declared IR, the exact way it already reads the core's own — and
-  # dispatches them through the CORE's `Bluebook::Syntax.Keyword`/
-  # `.Argument` verbs, which is why these rows need no entity, no
-  # lifecycle, no creating command of their own here: the verb they ride
-  # already exists, and a second copy of it would be the core's own
-  # machinery duplicated for no reason.
+  # Holds grammar rows only, like `Vocabulary`: SyntaxBoot reads them off the declared IR and
+  # dispatches them through the core's `Syntax.Keyword`/`.Argument` verbs, so no commands here.
   aggregate "Syntax" do
     description "The rows this sub-language contributes to the core's own grammar table."
     identified_by PagingSyntaxName, as: :name
@@ -23,11 +15,7 @@ Hecks.bluebook "Paging" do
       invariant("a syntax table is named") { !value.to_s.empty? }
     end
 
-    # THE SAME EIGHT ROWS syntax.bluebook held directly until now — moved,
-    # not rewritten. `limit`/`offset`/`cursor`/`nulls`, on both `Query`
-    # and `ReadModel`. See syntax.bluebook's own comment at the old site
-    # for why `limit` fills a dedicated field while the other three land
-    # on the open `options` map.
+    # `limit` fills a dedicated field on Query; the other three land on the open `options` map.
     value_object "KeywordSeed" do
       attribute :word,    String
       attribute :context, String
@@ -68,7 +56,10 @@ Hecks.bluebook "Paging" do
       member keyword: "nulls",  context: "Query", at: "1", named: "", kind: "symbol", required: "true", fills: "mode"
 
       member keyword: "limit",  context: "ReadModel", at: "1", named: "", kind: "number", required: "true", fills: "value"
+      # ADR 0055's `on:`; see projection.bluebook's own "where"/"order_by" ReadModel rows.
+      member keyword: "limit",  context: "ReadModel", at: "",  named: "on", kind: "constant", required: "false", fills: "target"
       member keyword: "offset", context: "ReadModel", at: "1", named: "", kind: "number", required: "true", fills: "value"
+      member keyword: "offset", context: "ReadModel", at: "",  named: "on", kind: "constant", required: "false", fills: "target"
       member keyword: "cursor", context: "ReadModel", at: "1", named: "", kind: "symbol", required: "true", fills: "value"
       member keyword: "nulls",  context: "ReadModel", at: "1", named: "", kind: "symbol", required: "true", fills: "mode"
     end

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

@@ -2,17 +2,7 @@ Hecks.bluebook "Bluebook", version: "1" do
   vision "The bluebook language, declared in itself. Loading a domain becomes dispatching commands into this meta-domain ; the IR it stores must equal the IR the DSL builder produces. The floor that stays hand-written is the interpreter — evaluating a predicate held as data — and IO."
   core
 
-  # A WHOLE BLUEBOOK, handed back in one read.
-  #
-  # The twelve `DeclaredIn` queries below can walk the tree a level at a time, and
-  # a caller stitching twelve reads together is a caller reimplementing this. The
-  # language already knows how to say "gather these heads around that spine" —
-  # it is what a read model IS — so the reconstruction is DECLARED rather than
-  # coded, and the shape of what comes back is a fact about the language instead
-  # of a fact about whoever wrote the reader.
-  #
-  # Spined on Bluebook because a bluebook is what you ask for. Everything else
-  # hangs off it, down to a Member's pairs and a Dispatch's bindings.
+  # A whole bluebook in one read: every declaration gathered around the chapter itself.
   read_model "WholeBluebook" do
     description "Every declaration of one chapter, gathered around the chapter itself — the way back, in a single read."
     reference_to Bluebook
@@ -34,54 +24,21 @@ Hecks.bluebook "Bluebook", version: "1" do
   aggregate "Bluebook" do
     description "One .bluebook file — the root a domain declaration hangs from."
 
-    # A CHAPTER IS KNOWN BY ITS NAME, which is what anyone would have said.
-    #
-    # It was not, and the reason it was not is worth keeping : the runtime read the
-    # identity out of the payload under its head's own name, so a command that both
-    # REACHED a bluebook and carried a name could not say both, and `Normalise`
-    # could never name what it acts on. The answer at the time was to duck it —
-    # keep `name` a plain field and be reached by a minted `id` like nothing else
-    # in the language.
-    #
-    # The duck is what is gone. A command reaches its root through the REFERENCE it
-    # declares (`bluebook_id`), which is a different key from any argument it
-    # carries, so the two cannot collide however they are spelled. The fallback was
-    # hiding a lookup bug ; removing it made the bug visible, and the bug was the
-    # smaller thing.
+    # A chapter is identified by its name; commands reach it through the `bluebook_id` reference.
     identified_by BluebookName, as: :name
 
     attribute :vision,         Vision
     attribute :classification, Classification
-    # A domain CONTRACT version, pinned per chapter — `Hecks.bluebook "Pizzas",
-    # version: "v2"`. Held here because the language must hold everything the
-    # runtime runs on, and this was the one field it did not: the round trip sliced
-    # its comparison by the reconstruction's own keys, so a version was excluded
-    # from the check rather than failing it, and a chapter assembled purely from
-    # these records would have lost it in silence. Most chapters declare none, and
-    # ABSENT IS NOT EMPTY — an unversioned chapter offers nothing here at all.
+    # Contract version pinned per chapter, e.g. `version: "v2"`. Absent is not empty.
     attribute :version,        Version
-    # A domain's own identity can change — held here so a rename is a
-    # declared fact the language carries, not just a Ruby-side accessor.
-    # Most chapters declare none, and ABSENT IS NOT EMPTY, the same
-    # reading `version` above gives.
+    # A rename is a declared fact. Absent is not empty.
     attribute :formerly_known_as, FormerlyKnownAs
     attribute :normalisations, list_of(NormalisationRule)
-    # THE SEAM ADR 0026 ADDS. A sub-language chapter (Paging, so far the
-    # only one) names the core contexts its own `Syntax` aggregate
-    # contributes rows for — "Query", "ReadModel" — so SyntaxBoot's own
-    # discovery can find it without the core ever naming it back. Most
-    # chapters attach to nothing, and ABSENT IS NOT EMPTY, the same
-    # reading `version`/`formerly_known_as` above give.
+    # Core contexts a sub-language chapter contributes Syntax rows for (ADR 0026).
+    # Absent is not empty: most chapters attach to nothing.
     attribute :attaches_to, list_of(AttachesToContext)
-    # A CAPABILITY THIS CHAPTER ANSWERS FOR OTHER DOMAINS — declared, so
-    # nothing downstream has to recognise the chapter BY NAME. One row
-    # per (capability, key, verb): `provides "authorization", grant:
-    # "RoleAssignment.Assign"` is the row (authorization, grant,
-    # RoleAssignment.Assign). The runtime's role check, boot's
-    # ungoverned-role refusal, the authorization adapter and the fuzzer
-    # all read the rows rather than the literal "Governance". Most
-    # chapters provide nothing, and ABSENT IS NOT EMPTY, the same reading
-    # `attaches_to` above gives.
+    # Capabilities this chapter answers for other domains, one row per (capability, key, verb).
+    # Absent is not empty: most chapters provide nothing.
     attribute :provides, list_of(Provision)
 
     value_object "Provision" do
@@ -159,11 +116,7 @@ Hecks.bluebook "Bluebook", version: "1" do
       emits ChapterDeclared
     end
 
-    # ONE CONTEXT THE CHAPTER ATTACHES TO, appended the way one identity
-    # part is (Aggregate.Identify, above) — `attaches_to "Query",
-    # "ReadModel"` names any number at once, and a list is filled by a
-    # verb of its own here the same reason it is everywhere else in this
-    # language.
+    # Appends one context; `attaches_to "Query", "ReadModel"` names several at once.
     command "Attach" do
       role "Language"
       goal "Name one core context this chapter's own Syntax rows attach to"
@@ -171,21 +124,13 @@ Hecks.bluebook "Bluebook", version: "1" do
       attribute :context, AttachesToContext
 
       sets :attaches_to, append: { value: :context }
-      # S16, ADR 0026 — the language's own self-use gate: an append is
-      # exactly the shape banking's own ensures already checks ("a
-      # ledger entry was posted") { ledger.size == old.ledger.size + 1
-      # } — one more row than before, never fewer, never the same.
+      # Appending grows the list by exactly one row.
       ensures("the list grew by exactly one") { attaches_to.size == old.attaches_to.size + 1 }
       emits ChapterAttached
     end
 
-    # ONE ROW OF ONE CAPABILITY — `provides "authorization", assignments:
-    # ..., grant: ..., transitions: ...` offers three, one per key, in the
-    # order they were written. Membership (`admit`/`grant`/`people`) and
-    # identity (`register`/`link`/`resolve`) use the same word with their
-    # own named keys; the argument table admits every key any capability
-    # declares, and `Capabilities::CONTRACTS` holds which keys a given
-    # capability must name.
+    # One row of one capability: `provides "authorization", grant: ...` offers one row per key.
+    # `Capabilities::CONTRACTS` holds which keys a capability must name.
     command "Provide" do
       role "Language"
       goal "Declare one verb this chapter answers a capability with"
@@ -199,19 +144,8 @@ Hecks.bluebook "Bluebook", version: "1" do
       emits CapabilityProvided
     end
 
-    # THE WAY BACK.
-    #
-    # Until these existed the meta-domain was write-only: twelve categories, 34
-    # verbs, and not one query. A bluebook could be dispatched in and never read
-    # out, which is exactly as much as JUDGING requires — offer every declaration,
-    # collect the refusals, throw the records away. It is also why the language
-    # could only validate. A store you cannot read cannot be the source of
-    # anything, and "loading a domain becomes dispatching commands into this
-    # meta-domain" — the vision at the top of this file — needs the records to
-    # come back out as the IR the runtime runs.
-    # Named to finish a sentence about the thing, the way every other query in the
-    # corpus is — pizzas COSTING LESS THAN a ceiling, orders PENDING, cards
-    # ACTIVE. So: the bluebook CALLED "Pizzas".
+    # Reads a bluebook back out, not only in.
+    # Named to finish a sentence: the bluebook CALLED "Pizzas".
     query "Called" do
       attribute :name, BluebookName
       where(name: :name)
@@ -235,9 +169,7 @@ Hecks.bluebook "Bluebook", version: "1" do
       emits NormalisationAttached
     end
 
-    # HOW BLUEBOOK IS SPELLED. These rows live with the concept
-    # they describe; SyntaxBoot discovers every aggregate-local seed table.
-    # Contexts represented here: File, Bluebook.
+    # Keyword rows for this chapter; SyntaxBoot discovers every aggregate-local seed table.
     value_object "KeywordSeed" do
       attribute :word,          String
       attribute :context,       String, admits: "Syntax::Context"

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

@@ -1,19 +1,7 @@
-# THE LANGUAGE IS A DOMAIN LIKE ANY OTHER, and this is the line that
-# says so. `lib/hecks/language/bluebook/` describes what a bluebook
-# IS — nine files, one chapter — and until MetaValidator.defer existed it
-# could not be booted the ordinary way at all: each file was judged
-# before its siblings had been read, so Aggregate's reference to Bluebook
-# dangled and the load refused. It boots now, which means it can also be
-# fuzzed, model-checked and inspected exactly like banking or pizzas.
-#
-# Memory because this chapter is read, never written to a store — nothing
-# dispatches a command against the language in production. A binding
-# still has to be DECLARED rather than defaulted, so that what answers is
-# a stated fact rather than whatever the runtime happened to fall back on.
+# The bluebook language as an ordinary domain, so it can be booted, fuzzed and model-checked.
+# Memory: this chapter is read, never written to a store.
 Hecks.hecksagon "Bluebook" do
-  # Several constructs here declare `role "Language"` (Aggregate.Declare,
-  # Entity.Declare, ...) — only real access control once Governance can
-  # check it against something (S8).
+  # `role "Language"` is real access control only once Governance can check it (S8).
   uses_framework "Governance"
   persisted_by "Memory"
 end

data/lib/hecks/language/bluebook/command.bluebook

@@ -4,28 +4,12 @@ Hecks.bluebook "Bluebook" do
 
     reference_to Aggregate
 
-    # WHICH PIECE DECLARED IT, when a piece did. A command argument with no
-    # attribute to land in does not persist — the same lesson `disputed_by` taught
-    # on CardPayment — so the field has to exist here for Command.Declare's
-    # `entity_id` to be held at all.
+    # The entity that declared it, when one did; Command.Declare's `entity_id` needs it.
     reference_to Entity, as: :entity_id, optional: true
 
-    # SPELLED AS THE IR SPELLS THEM. The judge walks a built IR and offers each
-    # field by name, so a field named differently here would need a translation
-    # table between two vocabularies for the same thing — and a table is a place
-    # to be wrong quietly. One spelling, and the walk reads straight through.
-    # THE IMMEDIATE OWNER, AND ITS NAME. Almost every chapter declares a
-    # `Declare` ; the owner is what tells one from another.
-    #
-    # `owner_id` NOT `aggregate_id` : a command declared on an ENTITY is that
-    # entity's, not its aggregate's — `Banking:Account:LedgerEntry:Amend` is
-    # LedgerEntry's Amend, and `Banking:Account:LedgerEntry` is what tells it
-    # apart from a same-named command on some OTHER entity of the same
-    # aggregate. `aggregate_id` (kept, below, as data) still names the true
-    # root, for the DeclaredIn walk that gathers every command under a
-    # chapter’s aggregate whichever piece declared it ; `owner_id` names only
-    # whichever declared THIS one. `owner_id` is not a declared attribute —
-    # it is the WALK's immediate parent, read the same way `position` is.
+    # Field names match the IR's so the judge can walk it without a translation table.
+    # `owner_id` is the walk's immediate parent (an entity's command belongs to the entity);
+    # `aggregate_id` still names the true root for the DeclaredIn walk.
     identified_by :owner_id, :name
 
     attribute :name,       CommandName
@@ -35,19 +19,11 @@ Hecks.bluebook "Bluebook" do
     attribute :references, EventName, optional: true
     attribute :attributes, list_of(Argument)
     attribute :givens,     list_of(Rule)
-    # THE POSTCONDITIONS — same Rule shape as givens, checked on the other
-    # side of the mutations: a given says what must hold to begin, an
-    # ensures says what must hold to have finished. Meyer's third leg.
+    # Postconditions: same Rule shape as givens, checked after the mutations.
     attribute :ensures,    list_of(Rule)
     attribute :mutations,  list_of(Change)
     attribute :provenance, CommandText
-    # LIFECYCLE STATE AS A COMMAND GUARD (S10, ADR 0025) — a LITERAL,
-    # the same shape `provenance`/`default:` already carry (`from:
-    # "open"` or `from: ["open", "frozen"]`, encoded and decoded the
-    # same way any other Ruby literal on this construct is), not a
-    # dedicated list-of-value-object the way `givens` is — the guard
-    # names no target state and moves nothing, so it needs no Rule-
-    # shaped predicate at all, only the states it admits.
+    # Lifecycle guard as a literal (`from: "open"` or `from: ["open", "frozen"]`); ADR 0025.
     attribute :from,       CommandText, optional: true
 
     value_object "CommandName" do
@@ -57,15 +33,11 @@ Hecks.bluebook "Bluebook" do
 
     value_object "Actor" do
       attribute :value, String
-      # RELAXED for the experiment : banking leaves 19 of 40 commands without a
-      # role, and the hand-written CommandBuilder never required one. Whether
-      # role/goal are mandatory is a language decision — the meta-domain found
-      # the drift the moment it enforced uniformly.
+      # Optional: many commands declare no role or goal, and the builder never required one.
     end
 
     value_object "Goal" do
       attribute :value, String
-      # RELAXED — see Actor above.
     end
 
     value_object "EventName" do
@@ -82,10 +54,9 @@ Hecks.bluebook "Bluebook" do
       attribute :list,    String
       attribute :optional, String, optional: true
       attribute :pattern,  String, optional: true
-      # optional: a declaration with no default has none (C3.7 — a value object's fields arrive or it refuses)
+      # A declaration with no default has none.
       attribute :default, String, optional: true
-      # The closed set this value must belong to — see Aggregate::Field, which is
-      # the same declaration, spelled for a command's arguments.
+      # The closed set this value must belong to (see Aggregate::Field).
       attribute :admits, String, optional: true
       attribute :relationship, String, optional: true
     end
@@ -97,32 +68,17 @@ Hecks.bluebook "Bluebook" do
 
     value_object "Change" do
       attribute :target, String
-      # The same word, one aggregate over. `OpName` used to carry
-      # `set || append || increment || decrement` in an invariant — Vocabulary's
-      # MutationOp written out a second time, one level in, with nothing
-      # comparing the two. Naming the set is the whole of what that invariant was
-      # trying to say, and it says it where the set actually lives.
       attribute :op,     String, admits: "Vocabulary::MutationOp"
       attribute :field,  String
       attribute :kind,   String
       attribute :source, String
     end
 
-    # A plain string holder, for the id of the aggregate above. Command had no
-    # generic text value object and the alternatives all meant something else —
-    # RuleText is a predicate, FieldRef is a field, ArgType is a type. Reusing one
-    # of those would read as a lie, the way `bluebook_id` typed AggregateName did.
+    # Plain string holder for an aggregate id; the other text value objects mean something else.
     value_object "CommandText" do
       attribute :value, String
     end
-    # The way back: everything DECLARED IN the aggregate above. The parent
-    # reference IS the query.
-    # WHERE IT SITS AMONG ITS SIBLINGS. Declaration order is a FACT ABOUT THE
-    # SOURCE — the IR is a contract read straight from this file,
-    # field for field AND INDEX FOR INDEX. So the language HOLDS it, instead of
-    # inheriting it from whatever order a store happens to iterate: an ask that
-    # does not say how it is ordered is answered in identity order, which is
-    # right for every other ask and fatal for the one that is the SOURCE.
+    # Declaration order is a fact about the source, so the language holds it, not the store.
     value_object "Position" do
       attribute :value, Integer
     end
@@ -139,18 +95,12 @@ Hecks.bluebook "Bluebook" do
       goal "Open a command on an aggregate"
 
       reference_to Aggregate
-      # DECLARED ON AN AGGREGATE, or on one of its ENTITIES. The IR uses the same
-      # Command for both — an entity's commands are Command objects — so the
-      # language uses the same Command, and says which piece declared it when a piece
-      # did. Absent for an aggregate's own commands, and ABSENT is not EMPTY.
+      # Declared on an aggregate or one of its entities; absent for an aggregate's own commands.
       reference_to Entity, as: :entity_id, optional: true
       attribute :name,  CommandName
       attribute :role,  Actor, optional: true
       attribute :goal,  Goal, optional: true
-      # See Aggregate.Declare's own `provenance` — identical shape, one
-      # level down.
       attribute :provenance, CommandText, optional: true
-      # See this aggregate's own `from` field comment, above.
       attribute :from,       CommandText, optional: true
 
       attribute :position, Position, optional: true
@@ -175,18 +125,9 @@ Hecks.bluebook "Bluebook" do
       attribute :optional, ArgType, optional: true
       attribute :pattern,  ArgType, optional: true
       attribute :default, ArgType, optional: true
-      # The closed set this argument's value must belong to — see
-      # Aggregate.Attribute, which carries the same word for a head's attributes.
+      # The closed set this argument's value must belong to (see Aggregate.Attribute).
       attribute :admits,  ArgType, optional: true
-      # Whether this argument was minted verbatim from the owning aggregate/
-      # entity's own reference-typed attribute (`sets :field` importing a
-      # `reference_to`/`has_many`/`has_one`/`belongs_to` field rather than
-      # retyping it) — see Aggregate.Attribute, which carries the same word
-      # for a head's own attributes. Missing here, a round trip through the
-      # self-hosted meta-domain silently dropped it for every command
-      # argument, even though the live DSL builder set it correctly in
-      # memory (CommandBuilder#resolve_bare_set!) — the wire just never
-      # carried it back.
+      # Marks an argument minted from the owner's reference-typed attribute.
       attribute :relationship, ArgType, optional: true
 
       sets :attributes, append: { name: :name, type: :type, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
@@ -194,32 +135,19 @@ Hecks.bluebook "Bluebook" do
       emits ArgumentAttached
     end
 
-    # An argument that points at ANOTHER aggregate's head — the same word
-    # `reference_to`, written on a command instead of on the head.
-    #
-    # `Argument` types its type as text, so a reference argument arrived as the
-    # STRING "Reference<Customer>" and the language held a spelling rather than a
-    # reference. That left "a reference points at a declared head" enforceable
-    # only by a `raise Malformed` in the DSL, for three of the four places the
-    # word can be written. As a reference it is a consequence of the model here
-    # too, exactly as Aggregate.Reference made it one on a head.
+    # An argument pointing at another aggregate's head, typed as a reference, not text.
     command "Reference" do
       role "Language"
       goal "Attach an argument that points at another aggregate's head"
 
       reference_to Aggregate, as: :points_at
-      # No `given` that the name is present : ArgName already carries that
-      # invariant, and a value object's invariant fires during coercion — before
-      # any given is reached. A rule that cannot be the one to refuse is
-      # decoration, and this language has paid for that mistake before.
+      # No `given` on the name: ArgName's invariant fires first, during coercion.
       attribute :name,    ArgName
       attribute :list,    ArgType
       attribute :optional, ArgType, optional: true
       attribute :pattern,  ArgType, optional: true
       attribute :default, ArgType, optional: true
       attribute :admits,  ArgType, optional: true
-      # See Argument's own :relationship, just above — the same gap, one
-      # verb over.
       attribute :relationship, ArgType, optional: true
 
       sets :attributes, append: { name: :name, type: :points_at, list: :list, default: :default, optional: :optional, pattern: :pattern, admits: :admits, relationship: :relationship }
@@ -276,10 +204,7 @@ Hecks.bluebook "Bluebook" do
       goal "Attach one mutation to the command"
 
       attribute :target, FieldRef
-      # NAMED ON THE ARGUMENT, not only on the Change row it fills. The row is
-      # what the IR holds ; THIS is what a caller hands in, so this is where a
-      # bad op has to be refused — `OpName`'s deleted invariant was refusing
-      # exactly here, and the link has to reach the same door to replace it.
+      # Named on the argument: this is what a caller hands in, so a bad op is refused here.
       attribute :op,     OpName, admits: "Vocabulary::MutationOp"
       attribute :field,  FieldRef
       attribute :kind,   FieldRef
@@ -297,11 +222,6 @@ Hecks.bluebook "Bluebook" do
       attribute :value, String
     end
 
-    # THE SET IT ADMITS IS NAMED, NOT RESTATED. This carried
-    # `set || append || increment || decrement` — Vocabulary::MutationOp written
-    # out a second time, one level in, which is exactly the kind of copy
-    # that drifts. `Change.op` now says `admits:
-    # Vocabulary::MutationOp`, so there is no second list left to drift.
     value_object "OpName" do
       attribute :value, String
     end
@@ -310,9 +230,7 @@ Hecks.bluebook "Bluebook" do
       role "Language"
       goal "Name the aggregate this command reaches through"
 
-      # NAMED `root`, not `references` : a command argument SHADOWS the aggregate
-      # field of the same name inside a given, so a once-only rule cannot read
-      # the state it guards unless the two differ.
+      # Named `root`, not `references`: an argument shadows the aggregate field of that name.
       attribute :root, EventName
 
       given("a command names what it acts on") { !root.value.to_s.empty? }
@@ -336,9 +254,7 @@ Hecks.bluebook "Bluebook" do
       emits AnnouncementNamed
     end
 
-    # HOW COMMAND IS SPELLED. These rows live with the concept
-    # they describe; SyntaxBoot discovers every aggregate-local seed table.
-    # Contexts represented here: Command.
+    # Keyword rows for this chapter; SyntaxBoot discovers aggregate-local seed tables.
     value_object "KeywordSeed" do
       attribute :word,          String
       attribute :context,       String, admits: "Syntax::Context"
@@ -357,37 +273,18 @@ Hecks.bluebook "Bluebook" do
       member word: "reference_to",    context: "Command", body: "none",   inner: "", opens: "", fills: "references", calls: "reference_to_impl"
       member word: "given",           context: "Command", body: "source", inner: "", opens: "", fills: "givens", resolves_via: "hash_chain", calls: "given_impl"
       member word: "sets",            context: "Command", body: "none",   inner: "", opens: "", fills: "mutations", calls: "sets_impl"
-      # RENAMED spelling of `sets`, above — its own dedicated, deprecated row
-      # (not `sets`'s own `was:`, syntax_conformance_spec.rb's own "no
-      # renamed-away spelling as a row of its own AND a was:" rule), kept
-      # here refusing live ONLY so `MetaValidator.shadow_parsing?` can still
-      # read frozen era text that used it (CommandBuilder#then_set_impl's
-      # own comment).
+      # Deprecated spelling of `sets`, still refused live so MetaValidator.shadow_parsing? can
+      # read frozen era text that used it.
       member word: "then_set",        context: "Command", body: "none",   inner: "", opens: "", fills: "mutations", status: "deprecated", calls: "then_set_impl"
-      # A command's synchronous handoff into one nested entity command
-      # (CommandBuilder#delegates_to_impl's own comment gives the full
-      # reasoning) — a new word, not a migrated one.
+      # Synchronous handoff into one nested entity command (CommandBuilder#delegates_to_impl).
       member word: "delegates_to",    context: "Command", body: "none",   inner: "", opens: "", fills: "mutations", calls: "delegates_to_impl"
       member word: "emits",           context: "Command", body: "none",   inner: "", opens: "", fills: "emits"
-      # A VALUE, NOT A DECLARATION — `state(:field)` is written INSIDE a
-      # `sets` (`append: { knights: state(:knights) }`, `to: state(:ply)`)
-      # and names the record's own field as that mutation's source; it
-      # fills nothing of its own, the `sets` it sits in fills `mutations`.
+      # A value written inside a `sets` (`to: state(:ply)`); it fills nothing of its own.
       member word: "state",           context: "Command", body: "none",   inner: "", opens: "", fills: "mutations"
       member word: "attribute",       context: "Command", body: "none",   inner: "", opens: "", fills: "attributes", calls: "attribute_impl"
       member word: "ensures", context: "Command", body: "source", inner: "", opens: "", fills: "ensures"
-      # RETROACTIVE CORRECTION — a command that amends a specific past
-      # event rather than acting fresh (see this domain's own ADR on why:
-      # sagas only compensate their OWN anticipated failures, eras only
-      # reinterpret stored shape, and the event log stays append-only —
-      # so nothing existing lets a command say "this is amending a fact
-      # we already announced, and here is why"). STORED AS A MUTATION,
-      # not a new Command field — the same reasoning `delegates_to`'s own
-      # comment gives in full: `mutations:` is ALREADY a fully round-
-      # tripped part of the self-hosted meta-domain's own contract, and a
-      # genuinely new top-level Command field is not. `corrects` rides the
-      # SAME multi-binding wire shape `append`/`delegate` already use
-      # (CommandBuilder#corrects_impl's own comment has the rest).
+      # Amends a specific past event. Stored as a mutation so it round-trips with the other
+      # mutation words (CommandBuilder#corrects_impl).
       member word: "corrects",        context: "Command", body: "none",   inner: "", opens: "", fills: "mutations", calls: "corrects_impl"
 
     end
@@ -436,14 +333,7 @@ Hecks.bluebook "Bluebook" do
       member keyword: "then_set",        context: "Command", at: "",  named: "remove",     kind: "literal",  required: "false", fills: "source", selects: "op=remove"
       member keyword: "delegates_to",    context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "target"
       member keyword: "delegates_to",    context: "Command", at: "",  named: "with",      kind: "literal",  required: "false", fills: "source", selects: "op=delegate"
-      # BARE CONSTANT ACCEPTED (ADR 0025, S6 — "events first-class"),
-      # `emits Account::AccountFrozen`, same `kind: "constant"` +
-      # `kind: "text"` pair `on`'s own row in `policy.bluebook` carries
-      # — both stay admitted, the old spelling not refused, for the
-      # same reason (event names aren't 100% corpus-migrated the way
-      # command references are). `CommandBuilder#emits` (hand-written,
-      # no `calls:` needed — the single-fill path already invokes it by
-      # its own word name) resolves either shape via `Naming.event_ref`.
+      # A bare constant (`emits Account::AccountFrozen`) or text; both go through Naming.event_ref.
       member keyword: "emits",           context: "Command", at: "1", named: "",          kind: "constant", required: "true",  fills: "emits"
       member keyword: "emits",           context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "emits"
       member keyword: "state",           context: "Command", at: "1", named: "",          kind: "symbol",   required: "true",  fills: "source"
@@ -454,14 +344,7 @@ Hecks.bluebook "Bluebook" do
       member keyword: "attribute",       context: "Command", at: "",  named: "pattern",   kind: "text",     required: "false", fills: "pattern"
       member keyword: "attribute",       context: "Command", at: "",  named: "admits",    kind: "text",     required: "false", fills: "admits"
       member keyword: "attribute",       context: "Command", at: "",  named: "one_of",    kind: "list",     required: "false", fills: "one_of"
-      # `corrects` — see the KeywordSeed row's own comment. `event` is the
-      # only positional and the only required-by-the-grammar argument;
-      # `reason` is required IN PRACTICE (CommandBuilder#corrects_impl
-      # refuses its absence by hand, the same way `sets` refuses two ops
-      # at once — a fact about runtime state, not a pure per-row fill, so
-      # it stays hand-enforced rather than declared `required: "true"`
-      # here, which would only gate the row's OWN presence, not a sibling
-      # kwarg's).
+      # `reason` is required in practice; CommandBuilder#corrects_impl refuses its absence.
       member keyword: "corrects",        context: "Command", at: "1", named: "",          kind: "text",     required: "true",  fills: "target"
       member keyword: "corrects",        context: "Command", at: "",  named: "as",        kind: "symbol",   required: "false", fills: "source"
       member keyword: "corrects",        context: "Command", at: "",  named: "reason",    kind: "text",     required: "false", fills: "source"