hecks 1.2.0 → 1.4.0

data/lib/hecks/projector/cli_projector.rb

@@ -2,15 +2,15 @@ require_relative "../naming"
 
 module Hecks
   module Projector
-    # A BLUEBOOK, PROJECTED AS ITS OWN COMMAND-LINE SURFACE.
+    # A bluebook, projected as its own command-line surface.
     #
     # Every verb a domain declares is a subcommand; every argument is an
-    # option whose TYPE, whose admitted values and whose required-ness are
+    # option whose type, whose admitted values and whose required-ness are
     # already stated in the chapter. A hand-written CLI restates all of it and
     # then drifts — and the first thing to drift is the help text, which is the
     # only part anybody reads.
     #
-    # WHAT IS PROJECTED, AND WHAT IS NOT. This answers the SURFACE — the verb
+    # What is projected, and what is not. This answers the surface — the verb
     # tree, the argument spec, the usage text — and nothing executes here. One
     # small generic runner (`bin/run`) boots a domain, asks for this, parses
     # against it and dispatches.
@@ -23,7 +23,7 @@ module Hecks
     # reads. Projecting the surface keeps one dispatcher and a help text that
     # cannot be stale, because it is computed at the moment it is printed.
     #
-    # THE TYPING IS THE POINT. A CLI hands everything over as a String.
+    # **The typing is the point**. A CLI hands everything over as a String.
     # `sequence.value=99` has to become the Integer 99 or the runtime refuses
     # it, and the only honest place to learn that is the value object's own
     # declared field type. A CLI that guessed — "it looks like a number" —
@@ -32,7 +32,7 @@ module Hecks
     module CliProjector
       module_function
 
-      # TWO NAMESPACES, NOT ONE — `{ verbs:, questions:, usage: }`.
+      # Two namespaces, not one — `{ verbs:, questions:, usage: }`.
       #
       # A chapter may legally declare a command and a query of one name: the
       # language namespaces them and `Banking::Account.Open` is both, in the
@@ -62,32 +62,32 @@ module Hecks
             end
           end
 
-          # A PORT IS A VERB TOO, and leaving it off the map was a real gap
+          # A port is a verb too, and leaving it off the map was a real gap
           # rather than a tasteful omission. The runtime has always dispatched
           # a port operation by exactly the same name as a command — the
           # projection simply never listed one, so `run_specs` and `file`
           # answered "no such verb" while working perfectly through Ruby.
           #
           # It matters most for the caller with no other door. An agent that
-          # may not shell out reaches this domain ONLY through the projected
+          # may not shell out reaches this domain only through the projected
           # CLI, and a port it cannot see is a capability it does not have.
           aggregate.ports.each do |port|
             port.operations.each { |o| claim(verbs, name_for(aggregate, o), port_spec(bluebook, aggregate, port, o)) }
           end
         end
 
-        # A REPORT IS A QUESTION TOO, and leaving it off was the same gap the
+        # A report is a question too, and leaving it off was the same gap the
         # ports had: `Dispatcher#query` has always answered `Domain.ReportName`,
         # the projection simply never listed one — so the composed reads worked
         # from Ruby and did not exist for anybody whose only door is the command
         # line.
         #
-        # It matters most for exactly what a report is FOR. Every other question
+        # It matters most for exactly what a report is for. Every other question
         # here answers with rows and leaves the arithmetic to the reader; a
         # `group_by` report is the one that counts. An agent that cannot reach
         # it can list bugs all day and never answer "how are we doing".
         #
-        # ONE DOT, NOT TWO — a report belongs to the chapter rather than to any
+        # **One dot, not two** — a report belongs to the chapter rather than to any
         # aggregate (that is what rootless means), so it is addressed
         # `QualityControl.BugsByStatus` where a query is
         # `QualityControl::Bug.Queue`. `Dispatcher#query` splits on precisely
@@ -96,7 +96,7 @@ module Hecks
           claim(questions, Naming.snake(model.hecks_name), report_spec(bluebook, model))
         end
 
-        # THE SHORT SPELLING, WHERE IT CANNOT BE AMBIGUOUS. `pizzas
+        # The short spelling, where it cannot be ambiguous. `pizzas
         # create_pizza` rather than `pizzas order.create_pizza` — the
         # aggregate is worth typing only when two of them declare the same
         # verb, and in a one-aggregate domain it never is. Both spellings are
@@ -129,7 +129,7 @@ module Hecks
         end
       end
 
-      # A NAME IS CLAIMED ONCE. A command and a query of one name are legal in
+      # A name is claimed once. A command and a query of one name are legal in
       # a chapter — the language namespaces them — and ambiguous as
       # subcommands. Refused here rather than silently resolving to whichever
       # was walked first, which is how `Ticket.Filed` (a command) and
@@ -156,7 +156,7 @@ module Hecks
          entity ? "#{entity.hecks_name}." : "", verb.hecks_name].join
       end
 
-      # THE ARGUMENTS A RECEIVER ADDS, BEFORE ANY VERB-SPECIFIC ONE. Shared by
+      # The arguments a receiver adds, before any verb-specific one. Shared by
       # `command_spec` and `port_spec` — a port operation always addresses an
       # aggregate record (`port_spec` passes `receiver: :aggregate`, never
       # `:entity` or `nil`, because a port is declared on an aggregate, never
@@ -194,7 +194,7 @@ module Hecks
                       (command.creates? ? nil : :aggregate)
                     end
 
-        # THE RECEIVER IS NOT A COMMAND ARGUMENT. An aggregate command names
+        # The receiver is not a command argument. An aggregate command names
         # its record through to; an entity command needs both the aggregate
         # record and the entity element within it. Keeping those paths in the
         # projected option list makes the human-facing request complete while
@@ -215,7 +215,7 @@ module Hecks
           refusals: refusals(command, holder), arguments: arguments }
       end
 
-      # A PORT OPERATION READS AS A VERB BUT REPORTS AS A BOUNDARY.
+      # A port operation reads as a verb but reports as a boundary.
       #
       # `creates: false` because it makes no record, and `refusals: []`
       # because it has none in the sense every other verb means: a command's
@@ -223,7 +223,7 @@ module Hecks
       # outbound operation's failure is somebody else's sentence, unknowable
       # from here.
       #
-      # THE SUMMARY NAMES BOTH ENDINGS, which is the one thing a caller most
+      # The summary names both endings, which is the one thing a caller most
       # needs and cannot infer. `run_specs` looks like it either works or
       # errors; what it actually does is answer `SpecsCompleted` even when the
       # suite is red, and refuse only when rspec could not run. Somebody
@@ -233,7 +233,7 @@ module Hecks
         arguments = receiver_options(:aggregate, aggregate, nil) +
                     operation.attributes.flat_map { |a| options_for(a, aggregate, aggregate) }
 
-        # THE WIRE NAME CARRIES THE PORT, THE TYPED NAME DOES NOT.
+        # The wire name carries the port, the typed name does not.
         #
         # `Dispatcher#dispatch` splits a verb into head and sub and looks the
         # head up as a port, so a port operation is addressed
@@ -244,7 +244,7 @@ module Hecks
         # names it short, which is the same split `shorten` already makes.
         { verb: [fqn(bluebook, aggregate, operation).sub(/\.[^.]+\z/, ""), port.name, operation.hecks_name].join("."),
           kind: :command, creates: false, receiver: :aggregate, refusals: [],
-          # `role:` HERE IS DESCRIPTIVE TEXT, NOT AN AUTHORIZATION GATE —
+          # `role:` here is descriptive text, not an authorization gate —
           # who calls whom through the port, for `--help`/`verb_help`'s
           # "issued by" line. A port operation never reaches
           # `CommandRules::Authorization#refuse_role_mismatch` (only
@@ -266,7 +266,7 @@ module Hecks
         "Ask #{port.name} — answers #{operation.answers}, refuses #{operation.refuses}"
       end
 
-      # A ROOTLESS REPORT TAKES NOTHING; a rooted one takes the id of the
+      # A rootless report takes nothing; a rooted one takes the id of the
       # record it is a view of, under the name the model gave that reference.
       def report_spec(bluebook, model)
         arguments =
@@ -293,14 +293,14 @@ module Hecks
 
       # ── one argument, flattened ───────────────────────────────────────
 
-      # A VALUE OBJECT BECOMES ONE OPTION PER FIELD, dotted. `commit` typed
+      # A value object becomes one option per field, dotted. `commit` typed
       # `CommitRef` is `--commit.value`, because that is the shape the runtime
       # wants and a flat `--commit` would have to guess which field it meant.
       # Single-field value objects — almost all of them — read fine either way,
       # and the runner accepts the short form for exactly those.
-      # RECURSIVE, AND IT HAS TO BE. A value object may hold another one —
+      # Recursive, and it has to be. A value object may hold another one —
       # pizzas' `Pizza` holds a `Price` and a `Size` — so stopping after one
-      # level produced `pizza.price_cents=1500` and sent the STRING "1500"
+      # level produced `pizza.price_cents=1500` and sent the string "1500"
       # where `{ cents: 1500 }` belonged.
       #
       # The runtime took it. `qa/FINDINGS.md` #2 is exactly that gap —
@@ -316,13 +316,13 @@ module Hecks
         value_object = value_object_for(attribute, holder, aggregate)
         return [scalar_option(path, attribute, optional)] unless value_object
 
-        # A LIST SAYS SO, ALL THE WAY DOWN TO ITS LEAVES.
+        # A list says so, all the way down to its leaves.
         #
         # Without this a `list_of(Tag)` projected exactly like a single Tag:
         # one option, `tags.value`, indistinguishable from a scalar. So the
         # help said to pass one, `CliDoor#bury` overwrote the leaf each time,
-        # and passing two tags stored the second and lost the first WITHOUT
-        # SAYING ANYTHING. A missing argument is refused loudly; a forgotten
+        # and passing two tags stored the second and lost the first without
+        # saying anything. A missing argument is refused loudly; a forgotten
         # one is not, which makes it the more expensive of the two by far.
         #
         # The flag is carried on the leaf rather than kept beside the
@@ -390,7 +390,7 @@ module Hecks
         program = options[:program] || "bin/run"
         only    = options[:verb]
 
-        # WHICH NAMESPACE, when both hold the name. `options[:ask]` says so;
+        # Which namespace, when both hold the name. `options[:ask]` says so;
         # without it a `--help` for a question would print the command that
         # shares its name, which banking has and which is how this was found.
         if only
@@ -421,16 +421,16 @@ module Hecks
         name ? "#{spec[:short]} is also #{name}" : ""
       end
 
-      # A QUERY's `description` is written as a paragraph — it argues for why
+      # A query's `description` is written as a paragraph — it argues for why
       # the list is worth reading. A verb table wants the first sentence of
       # that argument; `--help` still prints the whole thing.
       def first_sentence(text)
         text.to_s.split(/(?<=\.)\s/).first.to_s
       end
 
-      # FOUR TEXT BLOCKS, IN FIXED DISPLAY ORDER — meta (name/kind/role),
+      # Four text blocks, in fixed display order — meta (name/kind/role),
       # invocation, arguments, refusals. Each block is independent of the
-      # others' content (only the OUTPUT ORDER is fixed, and stays fixed
+      # others' content (only the output order is fixed, and stays fixed
       # below), so each is its own method returning the lines it
       # contributes — `[]` when it contributes none — concatenated in the
       # same order the original inline version built them in.

data/lib/hecks/projector/docs_projector.rb

@@ -2,38 +2,38 @@ require_relative "../naming"
 
 module Hecks
   module Projector
-    # A BLUEBOOK, PROJECTED AS ITS OWN USAGE DOCUMENTATION.
+    # A bluebook, projected as its own usage documentation.
     #
-    # WHAT THIS IS FOR. A chapter in this corpus already contains everything a
+    # **What this is for**. A chapter in this corpus already contains everything a
     # user of it needs: what each aggregate is (`description`), what each verb
     # is for (`goal`) and who issues it (`role`), which states it moves
     # between, what it refuses and in whose words (`given`, `invariant`,
     # `ensures`), and what each list is worth reading (`description` on a
-    # query). None of that reaches the person who has to CALL the domain.
+    # query). None of that reaches the person who has to call the domain.
     # They read the source, or they read a document somebody wrote beside the
     # source and stopped updating.
     #
     # `docs/implemented/reference/` is the precedent and the contrast. `bin/reference`
     # generates it from the language's own Syntax chapter, so the reference
     # for the DSL cannot drift from the DSL. This is the same trick one level
-    # down: the usage document for a DOMAIN, generated from that domain, so it
+    # down: the usage document for a domain, generated from that domain, so it
     # cannot drift from the domain either.
     #
-    # WHY IT IS A PROJECTION AND NOT A GENERATOR SCRIPT. `Projector` is the
+    # Why it is a projection and not a generator script. `Projector` is the
     # repository's registry of "canonical IR in, external artifact out" (§30
     # of the implementation plan), and this is exactly that shape: one
     # bluebook's IR in, markdown out, no runtime needed and no store touched.
     # Registered as `:docs` beside `:ir`, and reachable the way every
     # projector is — `Projector.call(:docs, bluebook: ...)`.
     #
-    # AND AS A METHOD, which is the half that makes it get used.
+    # And as a method, which is the half that makes it get used.
     # `Facade::Surface` already installs a module per chapter carrying
     # `vision` and `aggregates`; `docs` joins them, so a booted domain answers
     # `QualityControl.docs` and an aggregate door answers
     # `QualityControl::Bug.docs`. A document you have to remember a script for
     # is a document nobody reads.
     #
-    # WHAT IT DELIBERATELY DOES NOT DO: invent. Every sentence below comes out
+    # **What it deliberately does not do**: invent. Every sentence below comes out
     # of the chapter. Where a chapter says nothing — an aggregate with no
     # `description`, a command with no `goal` — the document says nothing
     # rather than filling the gap with a restatement of the name, because a
@@ -55,7 +55,7 @@ module Hecks
         "#{out.compact.join("\n").rstrip}\n"
       end
 
-      # A NAME THAT NAMES NOTHING IS REFUSED, not answered with an empty
+      # A name that names nothing is refused, not answered with an empty
       # document. Shipped the other way first: `options[:aggregate]` that
       # matched no head returned "" and exit 0, which is the silent-wrong-
       # answer shape this repository has already been bitten by twice in the
@@ -75,7 +75,7 @@ module Hecks
 
       def chapter_header(bluebook, depth)
         out = [h(depth, bluebook.name), ""]
-        # THE VISION FIRST AND AS A QUOTE. It is the one sentence in a chapter
+        # The vision first and as a quote. It is the one sentence in a chapter
         # written for somebody who does not know the domain yet.
         out += ["> #{bluebook.vision}", ""] if bluebook.vision
         out << "#{bluebook.classification.to_s.capitalize} domain." if bluebook.classification
@@ -88,7 +88,7 @@ module Hecks
 
       def anchor(name) = Naming.snake(name).tr("_", "-")
 
-      # WHAT HAPPENS WITHOUT ANYBODY ASKING — the part of a domain a caller
+      # What happens without anybody asking — the part of a domain a caller
       # cannot discover from any verb list, and the part most likely to surprise
       # them. A policy means one dispatch causes another, sometimes into a
       # different domain entirely; a saga means a sequence is being driven on
@@ -145,7 +145,7 @@ module Hecks
       def entity_section(aggregate, entity, depth)
         out = [h(depth, "#{entity.hecks_name} (within #{aggregate.hecks_name})"), ""]
         out += [entity.description, ""] if entity.description
-        # THE THING A CALLER GETS WRONG FIRST. An entity has no door of its
+        # The thing a caller gets wrong first. An entity has no door of its
         # own: its verb is spelled through the aggregate that holds it, and
         # the parent's id travels alongside the entity's own identity.
         out << "Addressed through its holder — `#{aggregate.hecks_name}.#{entity.hecks_name}.<Verb>`, " \
@@ -171,7 +171,7 @@ module Hecks
         table(%w[attribute shape rules], rows)
       end
 
-      # A VALUE OBJECT'S FIELDS, NOT ITS NAME. `commit` typed `CommitRef` tells
+      # A value object's fields, not its name. `commit` typed `CommitRef` tells
       # a caller nothing; `{ value: String }` tells them what to send, which is
       # the single most common thing to get wrong at this boundary — a bare
       # scalar where an object is wanted.
@@ -277,7 +277,7 @@ module Hecks
         end
       end
 
-      # EVERY WAY THIS VERB CAN SAY NO, gathered from the three places a
+      # Every way this verb can say no, gathered from the three places a
       # chapter states them — the lifecycle it is an edge of, its own
       # `given`s, and the fact that a reference has to resolve. A caller
       # reading only the argument list learns none of these, and they are

data/lib/hecks/projector/exporter.rb

@@ -5,9 +5,9 @@ module Hecks
   module Projector
     # Registry-wide serialization to Hash/JSON: bluebook IR
     # (`call`/`json`), era-adapter lineage-capability flags (`lineage`),
-    # and translation edges in both their DIGEST-relevant declared shape
+    # and translation edges in both their digest-relevant declared shape
     # (`translation_hash`, what ApprovalDigest hashes) and their
-    # consumer-ready COMPILED shape with precompiled SQL attached
+    # consumer-ready compiled shape with precompiled SQL attached
     # (`translations`/`compiled_translation_aggregate`). Read directly by
     # bin/ir, bin/project_rust, and the translation/audit approval digest.
     module Exporter
@@ -21,15 +21,15 @@ module Hecks
         JSON.pretty_generate(call(registry))
       end
 
-      # A BINDING fact, deliberately NOT folded into `call`/`bluebook.to_h`
+      # A binding fact, deliberately not folded into `call`/`bluebook.to_h`
       # above — the canonical IR is runtime-independent by design (ADR
-      # 0001: it describes what a bluebook DECLARES, never which adapter
+      # 0001: it describes what a bluebook declares, never which adapter
       # a deployment happens to bind it to), and "is this aggregate bound
       # to a lineage-capable adapter" is exactly the kind of fact that
       # answer can change per-deployment without the bluebook's own shape
       # changing at all. Consumers that need it (bin/project_rust's own
       # `ir.json` sidecar, rust/host's runtime era-aware seed overlay —
-      # dispatch.rs) merge this in as a SEPARATE top-level key, the same
+      # dispatch.rs) merge this in as a separate top-level key, the same
       # way `translations` already sits beside `call`'s output rather than
       # inside it.
       #
@@ -54,13 +54,13 @@ module Hecks
         { capable_aggregates: capable.map { |aggregate| { name: aggregate.name, storage_name: aggregate.storage_name } } }
       end
 
-      # A BINDING fact, same shape/reasoning as `lineage` above: every
-      # aggregate's DECLARED persistence adapter name (`persisted_by`),
+      # A binding fact, same shape/reasoning as `lineage` above: every
+      # aggregate's declared persistence adapter name (`persisted_by`),
       # not part of the canonical bluebook shape `call` exports (ADR
       # 0001 — the IR describes what's declared, never which adapter a
       # deployment binds it to). Unlike `lineage`, this needs no era
       # plugin — `BindingPolicy` is core, always loaded — and covers
-      # EVERY aggregate, not just lineage-capable ones: `rust/host`
+      # every aggregate, not just lineage-capable ones: `rust/host`
       # (`ir.rs`'s own `refuse_unsupported_persistence_adapters`) reads
       # this to refuse loudly, at boot, against a domain bound to an
       # adapter it has no backend for (Heki, Memory, Sqlite, D1,
@@ -78,7 +78,28 @@ module Hecks
         { aggregates: aggregates }
       end
 
-      # Translation IR, always as an array, WITH each aggregate's
+      # A binding fact, same shape/reasoning as `lineage`/`persistence`
+      # above: which chapter this domain's role checks resolve against
+      # (`Registry#authorization_provider_for` — the domain's own chapter
+      # or a framework member it attaches that declares `provides
+      # "authorization"`), with that chapter's declared verbs qualified.
+      # `rust/host` (auth.rs) reads this instead of naming Governance.
+      # `{}` when nothing this domain attaches provides authorization.
+      def authorization(registry, domain_name)
+        provider = registry.authorization_provider_for(domain_name)
+        return {} unless provider
+
+        capability = Bluebook::Capabilities::AUTHORIZATION
+        assignments = provider.provided_verb(capability, :assignments)
+        {
+          provider:             provider.name,
+          grant:                provider.provided_verb(capability, :grant),
+          assignments:          assignments,
+          assignment_aggregate: assignments&.split(".")&.first
+        }
+      end
+
+      # Translation IR, always as an array, with each aggregate's
       # precompiled SQL attached (`compiled_translation_aggregate`) —
       # this is the export a consumer embeds (`ir.json`'s `translations`
       # key), never the bare digest-relevant shape `edge_digest` hashes
@@ -104,16 +125,16 @@ module Hecks
         JSON.pretty_generate(translations(registry))
       end
 
-      # THE DIGEST-RELEVANT SHAPE — `ApprovalDigest.edge_digest` hashes
-      # EXACTLY this, and only this, for exactly the reason `compiled_
+      # The digest-relevant shape — `ApprovalDigest.edge_digest` hashes
+      # exactly this, and only this, for exactly the reason `compiled_
       # translation_aggregate` below must never be used for that
-      # purpose: a digest bound to the COMPILED SQL, not just the
-      # DECLARED rules, would invalidate an existing human approval the
+      # purpose: a digest bound to the compiled SQL, not just the
+      # declared rules, would invalidate an existing human approval the
       # moment `Translation::RuleCompiler`'s own output format changed
       # for any reason — a compiler refactor, a cosmetic SQL-formatting
       # change — even when the declared rules an approver actually
-      # reviewed never changed at all. The approval binds to WHAT WAS
-      # DECLARED, not to what a particular compiler build happened to
+      # reviewed never changed at all. The approval binds to what was
+      # declared, not to what a particular compiler build happened to
       # emit from it.
       def translation_hash(translation)
         {
@@ -137,15 +158,15 @@ module Hecks
           drops:     aggregate.drops.map(&:to_s),
           retypes:   aggregate.retypes.map { |retype| { from: retype.from, to: retype.to } },
           computes:  aggregate.computes.map { |compute| { from: compute.from, to: compute.to, sql: compute.sql } },
-          # PREVIOUSLY MISSING — found live while planning Rust-side mint
+          # **Previously missing** — found live while planning Rust-side mint
           # support. An edge carrying only a rekey (no compute) had its
           # approval bind to nothing rekey-specific at all: any two
           # rekey edges with otherwise-identical renames/moves/converts/
-          # drops/retypes/computes produced the SAME digest regardless
+          # drops/retypes/computes produced the same digest regardless
           # of what their `rekey sql:` actually said, and a rekey's own
           # SQL could change without invalidating an existing approval.
           # Same bug shape for `backfills` (present, just never
-          # exported). Fixing this CHANGES every existing rekey/
+          # exported). Fixing this changes every existing rekey/
           # backfill edge's digest — any approval already recorded for
           # one is invalidated by this fix and must be re-reviewed.
           rekeys:    aggregate.rekeys.map { |rekey| { sql: rekey.sql } },
@@ -153,14 +174,14 @@ module Hecks
         }
       end
 
-      # THE EXPORT SHAPE — `translation_aggregate`'s own digest-relevant
+      # The export shape — `translation_aggregate`'s own digest-relevant
       # fields, plus the precompiled SQL (`compiled_state_expression`/
       # `compiled_id_expression`) a consumer embedding this JSON
       # (rust/host's own boot-time mint) needs to execute the edge
-      # without compiling SQL itself. The SAME call head_compiler.rb's
+      # without compiling SQL itself. The same call head_compiler.rb's
       # own `compile_rules(declared)`/`id_case(guard, declared)` make at
       # mint time, run here once at build/export time instead —
-      # `Translation::RuleCompiler` is the ONE place this expression is
+      # `Translation::RuleCompiler` is the one place this expression is
       # built, called from both here and from head_compiler.rb's real
       # per-mint assembly, so a consumer gets Ruby's own compiler's
       # output verbatim, never a second, independently-authored SQL

data/lib/hecks/projector/ir_projector.rb

@@ -1,6 +1,6 @@
 module Hecks
   module Projector
-    # The trivial case, on purpose: canonical IR projected AS canonical
+    # The trivial case, on purpose: canonical IR projected as canonical
     # IR. `Bluebook#to_h` already satisfies every §30 acceptance
     # criterion on its own — no live runtime needed to call it, output is
     # deterministic (the same golden fixtures `spec/ir_golden_spec.rb`

data/lib/hecks/projector/narrate_projector.rb

@@ -3,20 +3,20 @@ require_relative "../forms/field_shape"
 
 module Hecks
   module Projector
-    # A BLUEBOOK, PROJECTED AS PROSE AN SME CAN READ BACK AND CONFIRM.
+    # A bluebook, projected as prose an SME can read back and confirm.
     #
-    # WHAT THIS IS FOR. `DocsProjector` already answers "what can I call and
+    # **What this is for**. `DocsProjector` already answers "what can I call and
     # what does it want" for the person implementing against a domain —
     # tables of arguments, shapes, refusal reasons. That is the wrong
     # register for the person who can actually say whether the domain is
-    # RIGHT: the subject-matter expert who knows what an account is and has
+    # right: the subject-matter expert who knows what an account is and has
     # never read a markdown table in their life. This projects the same IR
     # as sentences instead — "Debit — take money out. Issued by a Teller. It
     # only goes through if the balance covers it." — so a domain can be
     # read back to the person who can validate it without them learning the
     # DSL first.
     #
-    # SAME SOURCE, SAME GUARANTEE `DocsProjector` gives: nothing here is
+    # Same source, same guarantee `DocsProjector` gives: nothing here is
     # invented. Every sentence quotes a `description`, `goal`, or `given`
     # already declared in the chapter; where a chapter says nothing, this
     # says nothing rather than manufacturing a sentence out of an
@@ -24,7 +24,7 @@ module Hecks
     # (`Projector.call(:narrate, bluebook: ...)`), same aggregate-scoping
     # via `options[:aggregate]`.
     #
-    # WHAT IT DOES NOT DO: replace `DocsProjector`. A shape table still says
+    # **What it does not do**: replace `DocsProjector`. A shape table still says
     # "id of a Customer" more precisely than any sentence would, and an
     # implementer still wants that. This is the other document the same IR
     # is owed — one written for the reader who is being asked "is this
@@ -128,7 +128,7 @@ module Hecks
         "#{header}\n\n#{body}"
       end
 
-      # ONE PARAGRAPH, BUILT FROM INDEPENDENT SENTENCES — each sentence
+      # One paragraph, built from independent sentences — each sentence
       # below states one unrelated fact about `command` (its goal, who
       # issues it, whether it creates the holder, what it takes, what it
       # references, what gates it, what it guarantees, what it emits), in
@@ -149,7 +149,7 @@ module Hecks
         ].compact.join(" ")
       end
 
-      # THE GOAL, VERBATIM — same rule `DocsProjector` holds to: quoted
+      # The goal, verbatim — same rule `DocsProjector` holds to: quoted
       # exactly as declared, not recased to fit mid-sentence, because the
       # promise this whole projector makes is that a sentence here is a
       # sentence the chapter actually wrote.
@@ -163,8 +163,8 @@ module Hecks
         "Issued by #{a_or_an(command.role)} #{command.role}."
       end
 
-      # `acts_on.nil?`, NOT `creates?` — `creates?` answers true for every
-      # verb an ENTITY declares (it never references itself; see
+      # `acts_on.nil?`, not `creates?` — `creates?` answers true for every
+      # verb an entity declares (it never references itself; see
       # `Command#acts_on`'s own comment), so reading it directly here would
       # tell an SME that `LedgerEntry.Amend` brings a new ledger entry into
       # being, which is exactly backwards.
@@ -208,7 +208,7 @@ module Hecks
         "It records `#{command.emits.join('`, `')}` as a fact."
       end
 
-      # EVERY REQUIRED CONDITION, STATED AS SOMETHING THAT MUST BE TRUE —
+      # Every required condition, stated as something that must be true —
       # the same three sources `DocsProjector#refusals_of` reads (the
       # lifecycle edge, a reference's existence, and the command's own
       # `given`s), but kept positive rather than phrased as a refusal
@@ -241,7 +241,7 @@ module Hecks
         lines = queries.map do |query|
           shape   = query.to_h
           takes   = Array(shape[:attributes]).map { |a| Forms::Humanize.label(a[:name].to_s).downcase }
-          # `w[:value]` ALREADY WEARS ITS OWN QUOTES OR COLON — it is a
+          # `w[:value]` already wears its own quotes or colon — it is a
           # `Literal.render`ed string (see lib/hecks/literal.rb), not a raw
           # Ruby value, so wrapping it in `.inspect` here would quote an
           # already-quoted string a second time.
@@ -284,18 +284,11 @@ module Hecks
 
       # ── small sentence carpentry ──────────────────────────────────────
 
-      def to_sentence_list(items, conj: "and")
-        case items.size
-        when 0 then ""
-        when 1 then items[0].to_s
-        when 2 then "#{items[0]} #{conj} #{items[1]}"
-        else "#{items[0..-2].join(', ')}, #{conj} #{items[-1]}"
-        end
-      end
+      # Both now live in `Naming` (a second projection, the glossary,
+      # needed them); kept here as names so this file reads as it did.
+      def to_sentence_list(items, conj: "and") = Naming.to_sentence_list(items, conj: conj)
 
-      def a_or_an(word)
-        %w[a e i o u].include?(word.to_s[0].to_s.downcase) ? "an" : "a"
-      end
+      def a_or_an(word) = Naming.a_or_an(word)
     end
   end
 end

data/lib/hecks/projector/target.rb

@@ -1,6 +1,6 @@
 module Hecks
   module Projector
-    # WHAT MAKES A MODULE A PROJECTION TARGET. `Projector.register` has
+    # What makes a module a projection target. `Projector.register` has
     # always accepted anything answering `call(bluebook:, options:)` —
     # this only removes the second step, so a target declares its own key
     # beside its own implementation instead of being registered from
@@ -15,20 +15,20 @@ module Hecks
     #     def call(bluebook:, options: {}) = { ... }
     #   end
     #
-    # NAMED `Target`, NOT `Projection`, on purpose. "Projection" already
+    # Named `Target`, not `Projection`, on purpose. "Projection" already
     # means two other things in this codebase: `Ports::Projection` is
     # read-model catch-up (events folded into view state), and `bin/project`
     # forces that catch-up by hand. Neither has anything to do with
     # "canonical IR in, external artifact out". A third meaning under the
     # same word would make the two impossible to grep apart — and from a
-    # domain's point of view `project(X)` really does read as "project TO
+    # domain's point of view `project(X)` really does read as "project to
     # a target", so the narrower word is also the more accurate one.
     module Target
       # Registering at declaration time means `require`ing a target is
       # the whole of installing it — there is no separate manifest that
       # can silently disagree about which targets exist.
       #
-      # `requires:` NAMES A CAPABILITY, not a shape word.
+      # `requires:` names a capability, not a shape word.
       #
       # This began as `from: :chapter` / `from: :any` — two hand-kept
       # symbols, admitted by duck-typing on `.aggregates`, which is a
@@ -44,26 +44,26 @@ module Hecks
       # It also composes: a projection needing two capabilities names
       # both, instead of a third symbol being invented for the pair.
       #
-      # THE FAIL-QUIET THIS CLOSES, unchanged in substance: every
-      # construct emits its own IR, so handing a projector an AGGREGATE
+      # The fail-quiet this closes, unchanged in substance: every
+      # construct emits its own IR, so handing a projector an aggregate
       # instead of a chapter is the natural thing to try. `bluebook:` was
-      # only ever a PARAMETER NAME, never a contract. `:oidc` failed
+      # only ever a parameter name, never a contract. `:oidc` failed
       # loudly (no `aggregates` method), but `:shape` returned
       # `{"name" => "Order", "aggregates" => []}` — well-formed,
       # confident, and wrong.
-      # `declares:` NAMES AN AGGREGATE THE CHAPTER MUST HAVE.
+      # `declares:` names an aggregate the chapter must have.
       #
-      # A capability says what a construct can DO; this says what it must
-      # CARRY. `:vocabulary` needs a chapter declaring a Vocabulary
+      # A capability says what a construct can do; this says what it must
+      # carry. `:vocabulary` needs a chapter declaring a Vocabulary
       # aggregate, `:parser_table` one declaring Syntax — and both used
       # to state that as a `raise` in their own body, which is a
       # requirement written as behaviour instead of declared. Stated
       # here, the registry refuses before the projection runs and the
       # projection stops carrying a guard about its own admission.
-      # `emits:` SAYS WHAT KIND OF ARTIFACT COMES BACK.
+      # `emits:` says what kind of artifact comes back.
       #
       # `:artifact` (the default) is one thing — a Hash, or a String.
-      # `:files` is a TREE: a Hash of relative path => contents, which is
+      # `:files` is a tree: a Hash of relative path => contents, which is
       # what a reference-page or codegen projection produces.
       #
       # Declared rather than sniffed, deliberately. Inferring a tree from
@@ -81,7 +81,7 @@ module Hecks
 
       def projection_key = @projection_key
 
-      # Empty means "a chapter" — resolved HERE rather than as a default
+      # Empty means "a chapter" — resolved here rather than as a default
       # argument, because Behaviour::Chapter is not loaded yet when this
       # file is.
       def projection_declares = @projection_declares || []