hecks 1.3.0 → 1.4.0

data/lib/hecks/projections/glossary/html.rb

@@ -3,14 +3,14 @@ require_relative "../../forms/html"
 module Hecks
   module Projections
     module Glossary
-      # THE PAGE, RENDERED FROM THE MARKDOWN — `html/index.html` is
+      # **The page, rendered from the markdown** — `html/index.html` is
       # `glossary.md` read back and dressed: a navigation rail built from
       # its `##` headings, each `###` a term entry, every ```mermaid fence
       # a diagram, every `[x](#y)` an in-page link. Nothing here reads
       # the bluebook; if the page shows it, the Markdown says it, so the
       # two cannot drift.
       #
-      # A SUBSET RENDERER, NOT A MARKDOWN LIBRARY — the projector emits
+      # A subset renderer, not a markdown library — the projector emits
       # a fixed handful of constructs (`Markdown`'s own header lists
       # them), and this reads exactly those. The Gemfile keeps every
       # dependency justified in its own comment; a full Markdown engine
@@ -89,7 +89,7 @@ module Hecks
         # The same slugs GitHub would give these headings, in the same
         # order — so the links the Markdown carries land here too.
         #
-        # KEYED BY THE BLOCK ITSELF, NOT ITS VALUE — a Struct compares by
+        # Keyed by the block itself, not its value — a Struct compares by
         # members, so two "### Open" headings in different sections would
         # otherwise be one key, and the first would answer with the
         # second's "-1" slug, leaving `#open` with nothing to land on.

data/lib/hecks/projections/glossary/markdown.rb

@@ -6,7 +6,7 @@ require_relative "../statements"
 module Hecks
   module Projections
     module Glossary
-      # THE DOCUMENT ITSELF — `glossary.md`, the one source the page is
+      # **The document itself** — `glossary.md`, the one source the page is
       # rendered from. Written in the handful of Markdown constructs
       # GitHub renders as-is (headings, blockquotes, ```mermaid fences,
       # lists, in-page links), so the file is a complete, readable
@@ -62,7 +62,7 @@ module Hecks
           parts.join("\n\n")
         end
 
-        # What an aggregate IS, what it can be, how it fits and moves,
+        # What an aggregate is, what it can be, how it fits and moves,
         # and what is always true of it — before a single term.
         def opening(aggregate, bluebook)
           parts = []
@@ -75,7 +75,7 @@ module Hecks
           parts
         end
 
-        # THE STATEMENTS PROJECTION'S OWN SENTENCES, SPOKEN. An invariant
+        # The statements projection's own sentences, spoken. An invariant
         # is the author's words and stays exactly so. A relationship
         # sentence is built mechanically from construct names ("An
         # ATMCard references an Account."), and a construct name is the

data/lib/hecks/projections/glossary/mermaid.rb

@@ -3,7 +3,7 @@ require_relative "../../naming"
 module Hecks
   module Projections
     module Glossary
-      # THE THREE PICTURES THE GLOSSARY DRAWS, each kept to the handful of
+      # The three pictures the glossary draws, each kept to the handful of
       # things that matter — Evans' "three to five objects central to the
       # issue at hand", never the whole model at once.
       #

data/lib/hecks/projections/glossary/sections.rb

@@ -1,7 +1,7 @@
 module Hecks
   module Projections
     module Glossary
-      # THE THREE SECTIONS NOTHING HOMES TO ONE AGGREGATE. In their own
+      # The three sections nothing homes to one aggregate. In their own
       # file because `Markdown` reads them and loads before the
       # projector's own body does.
       ROLES       = "Roles".freeze

data/lib/hecks/projections/glossary/sentences.rb

@@ -4,7 +4,7 @@ require_relative "../statements"
 module Hecks
   module Projections
     module Glossary
-      # EVERY SENTENCE THE GLOSSARY SAYS, AND THE RULE EACH ONE OBEYS.
+      # Every sentence the glossary says, and the rule each one obeys.
       #
       # Authored text is verbatim: an aggregate's `description`, a
       # command's `goal`, a query's `description`, an invariant's own
@@ -65,7 +65,7 @@ module Hecks
           [value_object_sentence(value_object, index, within), rules_line(rules)].compact
         end
 
-        # A one-field object whose field is just "value" IS its type —
+        # A one-field object whose field is just "value" is its type —
         # "Text.", "A whole number." — the field name would add nothing.
         def value_object_sentence(value_object, index, within)
           return closed_set_sentence(value_object.members) if value_object.closed_set?
@@ -92,7 +92,7 @@ module Hecks
           field.list? ? "a list of #{inner}" : inner
         end
 
-        # A CLOSED SET'S ROWS — a one-field set is its values; a set
+        # A closed set's rows — a one-field set is its values; a set
         # whose rows carry more (StatementFrequency's cadence plus a
         # retention and a fee) leads with the first field and keeps the
         # rest beside it, so no row loses what makes it distinct.
@@ -162,7 +162,7 @@ module Hecks
           sentence
         end
 
-        # A NOUN LIST, DELIBERATELY — "Responsible for Credit and Debit",
+        # A noun list, deliberately — "Responsible for Credit and Debit",
         # never "Can credit and debit": banking's System role raises
         # `Debited` and `Credited`, and "can … debited" is a wrong
         # sentence. The headwords are already what people say.
@@ -170,7 +170,7 @@ module Hecks
           "Responsible for #{Naming.to_sentence_list(command_links(issues, index))}."
         end
 
-        # THE SAME WORD FOR TWO DIFFERENT THINGS gets its holder beside it
+        # The same word for two different things gets its holder beside it
         # — a role responsible for CardPayment's Reverse and Transfer's
         # Reverse is responsible for "Reverse (card payment)" and
         # "Reverse (transfer)", not for "Reverse" twice.

data/lib/hecks/projections/glossary.rb

@@ -9,15 +9,15 @@ require_relative "glossary/html"
 
 module Hecks
   module Projections
-    # A CHAPTER, PROJECTED AS ITS UBIQUITOUS LANGUAGE — a glossary for the
-    # whole team, in the sense Evans meant (DDD ch. 2): ONE language,
+    # A chapter, projected as its ubiquitous language — a glossary for the
+    # whole team, in the sense Evans meant (DDD ch. 2): one language,
     # shared by domain experts and developers, written the same way in
     # conversation, diagrams, documents and code, so that a subject-matter
     # expert can read the model and say "yes, that's how it works" or
     # "no, that's wrong". A banker, a support rep, the CEO and an engineer
     # read the same page.
     #
-    # THREE THINGS FOLLOW FROM THAT AUDIENCE. First, no type jargon: a
+    # **Three things follow from that audience**. First, no type jargon: a
     # term is a term, not "an Aggregate" or "a Value Object", and every
     # identifier is spelled as a person says it (`Naming.words`: `ATMCard`
     # is "ATM card"). Second, nothing invented: every sentence is either
@@ -29,7 +29,7 @@ module Hecks
     # reader thinks "what does Account mean" before "what starts with A",
     # and once there reads the way a dictionary reads.
     #
-    # TWO FILES FROM ONE SOURCE. `glossary.md` is the document — every
+    # **Two files from one source**. `glossary.md` is the document — every
     # construct in it renders on GitHub as-is (headings, blockquotes,
     # ```mermaid fences, lists, in-page links). `html/index.html` is that
     # exact Markdown string rendered into a page with a navigation rail;
@@ -72,7 +72,7 @@ module Hecks
         Document.new(bluebook: bluebook, sections: sections, index: Index.new(sections))
       end
 
-      # AGGREGATES FIRST, A TO Z BY THEIR SPOKEN NAME ("Account" before
+      # Aggregates first, a to Z by their spoken name ("Account" before
       # "ATM card"), then the three groups nothing homes to one aggregate.
       def sections(bluebook, entries)
         grouped = entries.group_by(&:section)
@@ -87,7 +87,7 @@ module Hecks
         list
       end
 
-      # A HEADWORD IS QUALIFIED ONLY WHEN IT WOULD REPEAT within its own
+      # A HEADWORD is qualified only when it would repeat within its own
       # section — "Open" the action and "Open (the list)" the question;
       # "Return (key issuance)" beside another Return — never numbered
       # (Chicago 18.9, MDN's disambiguation pages: qualify the headword).
@@ -111,14 +111,14 @@ module Hecks
 
       # ── gathering ────────────────────────────────────────────────────
 
-      # AN ENTITY CAN CARRY ITS OWN COMMANDS AND QUERIES TOO — walked the
+      # An entity can carry its own commands and queries too — walked the
       # same one level down `DocsProjector` and `Projections::Diagrams`
       # already walk it.
       def holders(bluebook)
         bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
       end
 
-      # EVERY HOLDER'S OWN AGGREGATE, ONE HOP OR ZERO — an aggregate maps
+      # Every holder's own aggregate, one hop or zero — an aggregate maps
       # to itself, an entity to whichever aggregate declared it. The one
       # fact the grouping is built on.
       def holder_aggregate(bluebook)
@@ -128,8 +128,8 @@ module Hecks
         end
       end
 
-      # EVERY EVENT'S RAISERS — an event is never declared, only emitted,
-      # so its home is whichever aggregate the FIRST command that raises
+      # Every event's raisers — an event is never declared, only emitted,
+      # so its home is whichever aggregate the first command that raises
       # it belongs to; a policy or saga reacting to it inherits that home.
       def event_raisers(bluebook)
         holders(bluebook).each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |holder, map|
@@ -165,7 +165,7 @@ module Hecks
         end
       end
 
-      # AGGREGATES ONLY — an entity declares no value objects of its own
+      # Aggregates only — an entity declares no value objects of its own
       # (`Bluebook::Entity` deliberately does not answer `value_objects`).
       def value_object_entries(bluebook)
         bluebook.aggregates.flat_map do |aggregate|
@@ -213,7 +213,7 @@ module Hecks
         end
       end
 
-      # CROSS-CUTTING BY NATURE — `System` and `Customer` issue commands
+      # Cross-cutting by nature — `System` and `Customer` issue commands
       # across half the aggregates here — so a role belongs to no single
       # one and gets its own section.
       def role_entries(bluebook)
@@ -236,7 +236,7 @@ module Hecks
 
       # ── anchors ──────────────────────────────────────────────────────
 
-      # GITHUB'S OWN HEADING SLUGS, REPRODUCED — lowercase, punctuation
+      # **GitHub's own heading slugs, reproduced** — lowercase, punctuation
       # dropped, spaces to hyphens, a repeat gets "-1", "-2" in document
       # order. Computed here, once, in the order the headings will appear,
       # so a link written into the Markdown lands on the same heading
@@ -261,8 +261,8 @@ module Hecks
         end
       end
 
-      # WHERE A DECLARED REFERENCE POINTS — keyed structurally (a command
-      # by its holder AND name, an event by its bare name), never by
+      # **Where a declared reference points** — keyed structurally (a command
+      # by its holder and name, an event by its bare name), never by
       # searching prose for a matching word. Anything not declared here
       # (a cross-domain command like `Notifications.Send`) answers nil,
       # and the sentence says it in words with no link.

data/lib/hecks/projections/ir.rb

@@ -7,7 +7,7 @@ module Hecks
     # The canonical IR, as a constant. The implementation already existed
     # and is already golden-tested (`Projector::IRProjector`, registered
     # as `:ir`) — this only gives it the constant spelling every other
-    # target has, by re-registering the SAME module under the same key.
+    # target has, by re-registering the same module under the same key.
     #
     # Deliberately not a new implementation: two things named `IR` that
     # each rendered IR their own way is exactly the drift this namespace

data/lib/hecks/projections/model/deviations.rb

@@ -1,32 +1,19 @@
 module Hecks
   module Projections
     module Model
-      # HOW THE MODEL'S SHAPE DIFFERS FROM THE LANGUAGE'S, and why.
+      # How the model's shape differs from the language's, and why.
       #
       # Every construct's `emits_ir` restates what the grammar declares —
       # and the two legitimately differ, in seven ways. These lived only
       # as prose in Ruby comments until spec/model_shape_conformance_spec
-      # made them checkable; they live HERE so the generator and the gate
+      # made them checkable; they live here so the generator and the gate
       # read one source rather than two that must agree.
       #
       # A reason is carried beside each entry because the generated file
-      # will CARRY it: a deviation is exactly the kind of thing whose
+      # will carry it: a deviation is exactly the kind of thing whose
       # explanation must survive regeneration, and the only way it can is
       # to be emitted rather than typed into the output.
       module Deviations
-        # The grammar is relational — a Command points UP at its
-        # Aggregate — where the model composes. An explicit `as:` still
-        # keeps its `_id` (Command's own `entity_id`, kept as data); the
-        # parent link itself mints bare now (ADR 0025) — `aggregate` or
-        # `bluebook`, whichever this category's creating command declares
-        # first — so both spellings are checked. Entity spells its own
-        # (separate, non-colliding) text twin of the parent link `owner`.
-        PARENT_REF = ->(field) { field.to_s.match?(/_id\z/) || %i[owner aggregate bluebook].include?(field) }
-
-        # The judge's own field, never the model's — contracts.rb already
-        # says so with `derived: { position: :walk }`.
-        JUDGE_ONLY = %i[position].freeze
-
         # What the model holds that the grammar declares elsewhere: the
         # containment edges, stated in syntax.bluebook's Keyword rows as
         # `context` -> `opens`.
@@ -64,7 +51,7 @@ module Hecks
           "Policy"      => { where_ast:      "the structured form of `where`, derived from the same text at emission" }
         }.freeze
 
-        # DECLARED, AND DELIBERATELY NOT EMITTED. The category that had no
+        # **Declared, and deliberately not emitted**. The category that had no
         # home anywhere before — each of these was a comment and nothing
         # more.
         OFF_THE_WIRE = {
@@ -85,6 +72,20 @@ module Hecks
 
         module_function
 
+        # The grammar is relational — a Command points up at its
+        # Aggregate — where the model composes. An explicit `as:` still
+        # keeps its `_id` (Command's own `entity_id`, kept as data); the
+        # parent link itself mints bare now (ADR 0025) — `aggregate` or
+        # `bluebook`, whichever this category's creating command declares
+        # first. Entity spells its own (separate, non-colliding) text twin
+        # of the parent link `owner`. Not restated here: the one list is
+        # `Assembly::PARENT_POINTERS`, which the assembly gate reads too.
+        def parent_ref?(field) = Hecks::Bluebook::Assembly.parent_pointer?(field)
+
+        # The judge's own fields, never the model's — read off the
+        # category's contract (`derived: { position: :walk }`), not restated.
+        def judge_only(name) = Hecks::Bluebook::Assembly.contract(name).walked
+
         # The tables that carry a reason answer with names only when the
         # caller wants the set rather than the explanations.
         def off_the_wire(name) = OFF_THE_WIRE.fetch(name, {}).keys

data/lib/hecks/projections/model.rb

@@ -3,22 +3,22 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # THE MODEL CLASSES, PROJECTED FROM THE LANGUAGE THAT DECLARES THEM.
+    # The model classes, projected from the language that declares them.
     #
-    # A construct's HOLDING half — its readers, its emission, a
+    # A construct's holding half — its readers, its emission, a
     # constructor that assigns declared fields and hands off — restates
     # what `bluebook.bluebook` already says, three times over in Ruby.
     # This renders it instead.
     #
-    # ONLY THE HOLDING HALF. `Behaviour::X` is hand-written and permanent,
+    # **Only the holding half**. `Behaviour::X` is hand-written and permanent,
     # and `settle` is the seam: everything a declaration cannot state
     # lives behind it, so regenerating can never be lossy. That property
     # was established construct by construct before any of this was
     # written — the chapter looked generatable and was not, until its
     # `@hecks_root`, ports table and child stamping moved behind `settle`.
     #
-    # THE HOST MANIFEST IS THE HONEST PART. The grammar states the fields;
-    # it does not state which constructs are Ruby CLASSES rather than
+    # The HOST manifest is the honest part. The grammar states the fields;
+    # it does not state which constructs are Ruby classes rather than
     # instances, what a constructor's defaults are, or how a value is
     # coerced on the way in. Those are facts about Ruby, not about
     # bluebooks, so they are declared here rather than pretended into the
@@ -29,7 +29,7 @@ module Hecks
 
       projects_as :model, declares: "Bluebook", emits: :files
 
-      # PER-CONSTRUCT RUBY FACTS. `coerce` is the only fiddly column: a
+      # **Per-construct Ruby facts**. `coerce` is the only fiddly column: a
       # declared field arrives as whatever the builder handed over, and
       # each construct has always normalised its own on the way in.
       HOST = {
@@ -37,21 +37,25 @@ module Hecks
           construct: "Policy",
           file:      "policy.rb",
           behaviour: "Behaviour::Policy",
-          readers:   %i[name on_event trigger_command target_domain where for_each with_spec],
+          readers:   %i[name on_event trigger_command target_domain expect_undelivered where for_each with_spec],
           accessors: %i[aggregate],
           defaults:  { name: nil, on_event: "nil", trigger_command: "nil",
-                       target_domain: "nil", where: "nil", for_each: "nil",
+                       target_domain: "nil", expect_undelivered: "false", where: "nil", for_each: "nil",
                        with_spec: "[]", aggregate: "nil" },
-          coerce:    { name: ".to_s", aggregate: "&.to_s" },
-          # A LIST OF BINDINGS IS NOT A SCALAR ON THE WIRE. Every other
+          # A flag on the wire is a boolean — the language holds it as
+          # text ("true"), the builder hands over `true`, and a
+          # reconstruction hands back whichever it read; all three land
+          # as the same `true`/`false`.
+          coerce:    { name: ".to_s", aggregate: "&.to_s", expect_undelivered: ".to_s == \"true\"" },
+          # A list of bindings is not a scalar on the wire. Every other
           # field emits as itself; this one has to render the way
           # `DispatchSpec`'s own `with_spec` does — keys to strings, and
-          # `render_value` KEEPING the leading colon on a Symbol, because
+          # `render_value` keeping the leading colon on a Symbol, because
           # a binding that reads an event field and one that supplies a
           # literal string are otherwise indistinguishable once written
           # down (see `MetaValidator::Readings`' own note on exactly that).
           renders:   { with_spec: "-> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } }",
-                       # COMPUTED (Deviations::COMPUTED["Policy"]): the structured
+                       # Computed (Deviations::COMPUTED["Policy"]): the structured
                        # form of `where`, a pure function of that text, the same
                        # `ast` every rule row carries beside its `canonical`.
                        where_ast: "-> { where_ast }" },
@@ -67,8 +71,8 @@ module Hecks
 
       def render(bluebook, name, host)
         <<~RUBY
-          # GENERATED — projected from the language's own #{name} aggregate.
-          # DO NOT EDIT: the holding half is rendered, and #{host.fetch(:behaviour)}
+          # Generated — projected from the language's own #{name} aggregate.
+          # Do not edit: the holding half is rendered, and #{host.fetch(:behaviour)}
           # is where anything hand-written belongs.
           require_relative "behaviour/#{File.basename(host.fetch(:file), '.rb')}"
 
@@ -91,9 +95,9 @@ module Hecks
 
       # The emission, keyed as the model spells it and sourced as the
       # language declares it.
-      # A COMPUTED field (Deviations::COMPUTED) is emitted too — it is
+      # A computed field (Deviations::COMPUTED) is emitted too — it is
       # model-only by definition, so it rides after the declared fields
-      # and MUST have a `renders` entry, there being nothing to `send`.
+      # and must have a `renders` entry, there being nothing to `send`.
       def emits(bluebook, name)
         fields  = emitted_fields(bluebook, name) + Deviations.computed(name)
         renders = HOST.fetch(name).fetch(:renders, {})
@@ -102,14 +106,14 @@ module Hecks
         "emits_ir(\n#{fields.map { |f| "  #{"#{f}:".ljust(width + 1)} #{renders.fetch(f, ":#{f}")}" }.join(",\n")}\n)"
       end
 
-      # WHAT THE CONSTRUCT EMITS: what the language declares, less every
+      # What the construct emits: what the language declares, less every
       # deviation the tables account for. The generator and
       # spec/model_shape_conformance_spec compute this the same way, from
       # the same tables, which is the point of the tables being in lib.
       def emitted_fields(bluebook, name)
         bluebook.aggregate(name).attributes.map(&:name)
-                .reject { |f| Deviations::PARENT_REF.call(f) } -
-          Deviations::JUDGE_ONLY -
+                .reject { |f| Deviations.parent_ref?(f) } -
+          Deviations.judge_only(name) -
           Deviations.off_the_wire(name) -
           Deviations.dynamic_tail(name) -
           Deviations.folded(name).values.flatten -
@@ -122,13 +126,13 @@ module Hecks
         return lines.join("\n") if accessors.empty?
 
         # A declared field the model deliberately does not emit still
-        # needs a reader, and the REASON it is off the wire is carried
+        # needs a reader, and the reason it is off the wire is carried
         # here rather than typed in — a comment that survives
         # regeneration is one the generator writes.
         reasons = Deviations::OFF_THE_WIRE.fetch(host.fetch(:construct, ""), {})
         (lines + accessors.map do |a|
           why = reasons[a]
-          (why ? "\n# #{a.upcase}, DECLARED AND DELIBERATELY OFF THE WIRE\n# #{wrap(why)}\n" : "") +
+          (why ? "\n# #{a.to_s.capitalize}, declared and deliberately off the wire\n# #{wrap(why)}\n" : "") +
             "attr_accessor :#{a}"
         end).join("\n")
       end

data/lib/hecks/projections/oidc.rb

@@ -3,16 +3,16 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # AN OIDC CLIENT/SCOPE MANIFEST derived from a domain's own IR: what
+    # An OIDC client/scope manifest derived from a domain's own IR: what
     # an identity provider has to know about this domain before it can
     # issue a token that means anything here.
     #
-    # THE ARTIFACT HALF OF SOMETHING ALREADY HALF-BUILT.
-    # `spec/oidc_projection_spec.rb` covers the INTEGRATION half — verified
+    # The artifact half of something already half-built.
+    # `spec/oidc_projection_spec.rb` covers the integration half — verified
     # claims in, `IdentityResolution.resolve` → `Authorization.holds_role?`
     # → a dispatch scoped by `Hecks.as_caller(role:)`. That half enforces
     # a role per command. It just had no way to say, up front and as data,
-    # WHICH role each command wants — every answer came from asking the
+    # which role each command wants — every answer came from asking the
     # live runtime one dispatch at a time.
     #
     # This is that catalogue, and the two are checked against each other
@@ -24,12 +24,12 @@ module Hecks
     # `Ports::Authorization.holds_role?` compares against a real
     # `Governance::RoleAssignment`.
     #
-    # ROLES COME FROM THE COMMANDS, NOT FROM GOVERNANCE. A command's own
+    # Roles come from the commands, not from governance. A command's own
     # `role "Compliance officer"` is in the bluebook IR
     # (`Command#role`), whereas `uses_framework "Governance"` is
     # declared in the `.hecksagon` — which `call(bluebook:, options:)`
     # cannot see at all. Reading the commands is both the only thing
-    # available here AND the more accurate source: it says what each
+    # available here and the more accurate source: it says what each
     # command actually demands, not merely which role vocabulary the
     # application happened to mount.
     #
@@ -93,7 +93,7 @@ module Hecks
       end
 
       # `banking:account.open` — the shape an OIDC scope is conventionally
-      # spelled in, and snake_cased through the SAME `Naming.snake` the
+      # spelled in, and snake_cased through the same `Naming.snake` the
       # facade uses to name a command's own door method, so a scope and
       # the Ruby call that satisfies it cannot drift apart.
       def command_scopes(commands, verb_prefix, scope_prefix)

data/lib/hecks/projections/parser_table.rb

@@ -2,12 +2,12 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # THE RUST PARSER'S KEYWORD TABLE, projected from the chapter's own
-    # Syntax aggregate — "the parser's grammar knowledge is DERIVED from
+    # The Rust parser's keyword table, projected from the chapter's own
+    # Syntax aggregate — "the parser's grammar knowledge is derived from
     # hecks's self-description, not hand-typed a second time", which
     # is the anti-drift idea the whole Rust-parser plan rests on.
     #
-    # A REGISTERED TARGET NOW, rather than a module living inside its own
+    # A registered target now, rather than a module living inside its own
     # bin/ script. It was already a projection in everything but call
     # shape; this only stops it being a fifth way of spelling one.
     module ParserTable
@@ -20,7 +20,7 @@ module Hecks
 
       module_function
 
-      # THE CHAPTER IS HANDED OVER, not reached for. This used to open the
+      # The chapter is handed over, not reached for. This used to open the
       # grammar registry itself, which meant the projection could only ever
       # project one chapter — the language's own. Taking it as an argument is
       # what the projector protocol asks for, and it costs nothing.
@@ -64,7 +64,7 @@ module Hecks
 
       # S14, ADR 0026 — Keyword/Argument are genuine entities of Syntax
       # now, dispatched (not merely declared) so their own `status`
-      # really is a lifecycle. `SyntaxBoot.call` reads the STILL-STATIC
+      # really is a lifecycle. `SyntaxBoot.call` reads the still-static
       # seed rows (`KeywordSeed`/`ArgumentSeed`), dispatches each one
       # through the real admission/lifecycle door, and hands back the
       # exact same shape `rows` used to read straight off the closed set

data/lib/hecks/projections/reference.rb

@@ -3,18 +3,18 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # THE DSL REFERENCE PAGES, projected from the chapter's own Syntax
+    # The DSL reference pages, projected from the chapter's own Syntax
     # aggregate — the tables come from the declaration, the prose is
     # preserved from whatever is already committed.
     #
-    # THE FIRST PROJECTION THAT EMITS A TREE. `emits: :files` says so,
+    # The first projection that emits a tree. `emits: :files` says so,
     # and the framework writes the map rather than inferring one: a Hash
     # of path => contents and a Hash that merely holds strings are the
     # same object to Ruby, so only the projection can know which it
     # meant. This is the case the output contract was designed for and
     # deliberately left unimplemented until something real needed it.
     #
-    # NOT PURE, and it cannot be. `Doc::Reference.pages` READS the
+    # Not pure, and it cannot be. `Doc::Reference.pages` reads the
     # committed pages to harvest their prose, so the existing directory
     # is an input — passed as `from:` rather than assumed, so the
     # projection never reaches for a path of its own choosing.