hecks 1.3.0 → 1.4.0

data/lib/hecks/runtime/read_model_interpreter.rb

@@ -24,9 +24,9 @@ module Hecks
 
       private
 
-      # ROOT-FIRST, THEN THE SQLITE ESCAPE HATCH, THEN THE JOIN LOOP —
+      # **Root-first, then the SQLite escape hatch, then the join loop** —
       # each step's own comment names a real, previously-shipped bug the
-      # current ORDER fixes (the reference/TenantScope refusal ordering
+      # current order fixes (the reference/TenantScope refusal ordering
       # above, the root-first head processing below). Splitting this
       # into smaller methods would scatter that ordering across method
       # boundaries where a future editor could silently break it, and
@@ -40,7 +40,7 @@ module Hecks
       def project(domain, model, args)
         bluebook = @registry.bluebook(domain)
         rootless = model.reference_target.nil?
-        # BEFORE the adapter early-return below, so the SQLite path inherits it.
+        # Before the adapter early-return below, so the SQLite path inherits it.
         # Without this a stale caller passing a wrapped reference gets a
         # path-dependent answer — an adapter could quietly open the wrapped
         # reference while the in-process path reads it whole and finds nothing.
@@ -49,16 +49,16 @@ module Hecks
         # wrong at all.
         refuse_object_reference(model, args) unless rootless
         reference_id = reference(args.fetch(model.reference_name)) unless rootless
-        # Computed off the ORIGINAL model, before TenantScope wraps it — the
+        # Computed off the original model, before TenantScope wraps it — the
         # "which head(s) do options apply to" question is about what the
         # bluebook author declared, not about the synthetic tenant clause
         # the wrapper adds underneath. Plural (ADR 0055) — `on:` lets more
         # than one many-side head be eligible at once.
         eligible = model.filtered_head_names
         model = TenantScope.apply(model, args)
-        # A ROOTLESS, `group_by`-declared, or `count`/`median`-declared
+        # A rootless, `group_by`-declared, or `count`/`median`-declared
         # model skips the SQLite native escape hatch entirely (there is
-        # no root aggregate to look up a repository FOR when rootless,
+        # no root aggregate to look up a repository for when rootless,
         # and `query_read_model` knows nothing about grouping or
         # reducing) — always runs the in-process loop below instead.
         # Correct everywhere ; not SQL-pushed-down for a SQLite-backed
@@ -73,17 +73,17 @@ module Hecks
           end
         end
 
-        # ROOT FIRST, ALWAYS — regardless of `include` order in the
+        # **Root first, always** — regardless of `include` order in the
         # bluebook. `read_model_builder.rb`'s own `include` is
         # documented "Order-independent" (the `:many` flag is resolved
         # at build time, once `@reference_target` is known), but that
-        # promise was never kept HERE: this loop used to run heads in
+        # promise was never kept here: this loop used to run heads in
         # their literal declared order and match each "many" head
-        # against whatever was ALREADY in `projected` — empty, the
+        # against whatever was already in `projected` — empty, the
         # very first time through, if a many-side head happened to be
         # declared before the root. A real, live bug (not a guess):
         # `include Promotion` before `include Item` on a read model
-        # whose root IS Item silently returned an empty array for
+        # whose root is Item silently returned an empty array for
         # Promotion — no error, just a wrong, too-small answer — while
         # the reverse order worked purely by accident. `partition`,
         # not `sort_by`: Ruby's `sort_by` is not guaranteed stable,
@@ -97,14 +97,14 @@ module Hecks
                    [fetch(bluebook, domain, head[:aggregate], reference_id)]
                  elsif rootless
                    # No root to FK-match against — a rootless model reads
-                   # each of its own heads WHOLE, independently. Multiple
-                   # heads on one rootless model are NEVER cross-joined
+                   # each of its own heads whole, independently. Multiple
+                   # heads on one rootless model are never cross-joined
                    # against each other, and there is no DSL to declare
                    # one if you wanted to — `ReadModelBuilder#include_impl`
                    # takes only `type`/`as:` (checked directly, not
                    # assumed), and `group_by` groups this bulk read's own
                    # output, it names no predicate between two heads.
-                   # Building a cross-join here would mean CHOOSING a join
+                   # Building a cross-join here would mean choosing a join
                    # semantics (equality on which fields?) nobody has
                    # declared — a real, deliberate scope limit pending a
                    # future `include ..., joins: ...`-shaped grammar
@@ -124,7 +124,7 @@ module Hecks
           projected << { aggregate: head[:aggregate], rows: rows }
           rows_by_as[head[:as]] = head[:many] ? rows : rows.first
         end
-        # Declared order preserved in the OUTPUT — only the
+        # Declared order preserved in the output — only the
         # computation above needed reordering, not what a caller sees
         # back.
         heads = model.aggregate_heads.to_h { |head| [head[:as], rows_by_as[head[:as]]] }
@@ -145,9 +145,9 @@ module Hecks
         end]
       end
 
-      # THE ROOT-FIRST FIX'S OWN FIX — root-first alone only reaches one
+      # **The root-first fix's own fix** — root-first alone only reaches one
       # level: it guarantees the root is in `projected` before any other
-      # head is matched, but a CHAIN of non-root heads (a head that
+      # head is matched, but a chain of non-root heads (a head that
       # references another non-root head, not the root) is still
       # matched against whatever declaration order happened to put in
       # `projected` so far. `include Coupon` before `include Promotion`
@@ -160,9 +160,9 @@ module Hecks
       # to declare `include` in dependency order (the same promise
       # `read_model_builder.rb` already makes and this file is the one
       # place obligated to keep), but by topologically sorting the
-      # non-root heads on their OWN declared reference fields before
+      # non-root heads on their own declared reference fields before
       # this method's runtime matching ever runs — Kahn's algorithm,
-      # picking ready heads in DECLARED order at each step so declaring
+      # picking ready heads in declared order at each step so declaring
       # order still governs whenever there is no dependency to break a
       # tie. This generalizes root-first (a chain of length 1) to a
       # chain of any depth, and to a head depending on more than one
@@ -192,13 +192,13 @@ module Hecks
         ordered
       end
 
-      # Which OTHER declared (non-root) heads a head's own aggregate
+      # Which other declared (non-root) heads a head's own aggregate
       # holds a reference field toward — the same relationship this
       # file's runtime matching checks record-by-record, asked here
       # statically, once, to order heads before any record is read.
       #
       # `head[:aggregate]` names whatever `include` was given — and
-      # `include` accepts a nested ENTITY (Member, nested under
+      # `include` accepts a nested entity (Member, nested under
       # ValueObject ; Handler and Dispatch, nested under ProcessManager
       # — bluebook.bluebook's own `WholeBluebook` read model includes
       # all three) just as readily as a top-level aggregate.
@@ -220,7 +220,7 @@ module Hecks
                    .map { |other| other[:aggregate] }
       end
 
-      # `group_by`'s own declared fields, checked against the ONE
+      # `group_by`'s own declared fields, checked against the one
       # many-side head they apply to (`seal_group_by` already refuses
       # zero or several) — resolved here, once, rather than re-derived
       # per row. Raises loudly on a typo'd field name rather than
@@ -232,15 +232,15 @@ module Hecks
         aggregate = bluebook.aggregate(target[:aggregate])
         model.group_by_fields.each do |field|
           next if aggregate.attribute(field)
-          # THE LIFECYCLE FIELD IS A FIELD, and refusing it here was a drift
+          # The lifecycle field is a field, and refusing it here was a drift
           # between two halves of the same language: `where(status: "logged")`
           # has always been legal on the same aggregate, because a lifecycle
           # state is stored on the record like anything else — it is simply
           # declared by `lifecycle :status` rather than by `attribute`.
           #
           # It is also the grouping anybody actually wants. "How are we doing"
-          # over a bug ledger IS the count per status, and a report that could
-          # group by every field EXCEPT that one could not answer the question
+          # over a bug ledger is the count per status, and a report that could
+          # group by every field except that one could not answer the question
           # reports exist for.
           next if aggregate.lifecycle && aggregate.lifecycle.field.to_sym == field.to_sym
 
@@ -253,7 +253,7 @@ module Hecks
 
       # One level of nesting per field, in `group_by`'s own declared
       # order — the leaf is the row with every grouped field removed
-      # (already spent, as the keys that reached it). ASSUMES the full
+      # (already spent, as the keys that reached it). Assumes the full
       # `group_by` path uniquely identifies one row (true for grouping by
       # an aggregate's own full identity, ConsoleSettings' own real use)
       # — `leaves.first` silently keeps only the first row when several
@@ -263,9 +263,9 @@ module Hecks
       def nest(rows, fields)
         field, *rest = fields
         rows.group_by { |row| row[field] }.transform_values do |group|
-          # Strip ONLY the field just grouped by, not the whole remaining
+          # Strip only the field just grouped by, not the whole remaining
           # list — `rest`'s own fields have to survive into the recursive
-          # call below, or the NEXT level groups by a key that's already
+          # call below, or the next level groups by a key that's already
           # gone (found by trying it: a two-field group_by's own second
           # level came back keyed `nil` for every group, every time).
           stripped = group.map { |row| row.reject { |key, _| key == field } }
@@ -273,7 +273,7 @@ module Hecks
         end
       end
 
-      # `count`/`median`'s own declared target — the SAME single
+      # `count`/`median`'s own declared target — the same single
       # many-side head `group_by_target` resolves, for the same reason
       # (`seal_aggregation` already refuses zero or several many-side
       # heads, and refuses count/median declared alongside group_by, so
@@ -303,12 +303,12 @@ module Hecks
         target
       end
 
-      # THE STANDARD DEFINITION. An ODD count's median is its one true
-      # middle value, sorted ; an EVEN count's median is the AVERAGE of
+      # **The standard definition**. An odd count's median is its one true
+      # middle value, sorted ; an even count's median is the average of
       # its two middle values — the common convention (as opposed to,
       # say, always taking the lower of the two), and the one this
       # session's own task named explicitly as the deliberate choice.
-      # An EMPTY collection has no median: nil, not zero, so a caller
+      # An empty collection has no median: nil, not zero, so a caller
       # cannot mistake "nothing to average" for "the values averaged to
       # zero". Reuses `Ports::Query::InMemory`'s own field reading
       # (`FieldPath.dig` + `comparable`) — the same unwrap `where`/
@@ -326,8 +326,8 @@ module Hecks
 
       def fetch(bluebook, domain, aggregate_name, id)
         @registry.read_repository(domain, bluebook.aggregate(aggregate_name)).find(id) ||
-          raise(NotFound, RefusalWording.render("NotFound", "read_model_reference_missing",
-                                                aggregate: aggregate_name, offered: Rendering.describe(id)))
+          raise(NotFound, RefusalWording.render_site("NotFound", "read_model_reference_missing",
+                                                     aggregate: aggregate_name, offered: Rendering.describe(id)))
       end
 
       def records(bluebook, domain, aggregate_name)
@@ -335,27 +335,27 @@ module Hecks
         aggregate ? @registry.read_repository(domain, aggregate).all : []
       end
 
-      # A stored reference holds the target's id inside the REFERENCE
-      # ATTRIBUTE's own declared shape, so reading it is reading that shape —
+      # A stored reference holds the target's id inside the reference
+      # attribute's own declared shape, so reading it is reading that shape —
       # a different thing from the identity unwrap that was removed. An
-      # IDENTITY is declared as a path and followed (Runtime::Identity) ; a
+      # identity is declared as a path and followed (Runtime::Identity) ; a
       # reference has no path of its own, and `Value.scalar` refuses a
       # composite rather than guessing which field was meant.
       #
       # Storing the scalar itself would remove this reading altogether. That
-      # is a change to how references are STORED, not to how identities are
+      # is a change to how references are stored, not to how identities are
       # declared, so it is not made here.
       # An ask names itself where a command would name itself, and says the
       # same thing about the same shape. `Value.refuse_object_reference` is
-      # not reused because it speaks of a COMMAND and its attribute ; a read
+      # not reused because it speaks of a command and its attribute ; a read
       # model has a query name and one declared reference.
       def refuse_object_reference(model, args)
         offered = args.fetch(model.reference_name, nil)
         return unless offered.is_a?(Hash) || offered.is_a?(Value)
 
         raise TypeMismatch,
-              RefusalWording.render("TypeMismatch", "read_model_object_reference",
-                                    query: model.query_name, field: model.reference_name)
+              RefusalWording.render_site("TypeMismatch", "read_model_object_reference",
+                                         query: model.query_name, field: model.reference_name)
       end
 
       # A reference is the id, in the argument and in the stored row alike.

data/lib/hecks/runtime/rebuild_sweep.rb

@@ -1,15 +1,15 @@
 module Hecks
   module Runtime
-    # THE OUT-OF-BAND HALF OF `projects` (S12, ADR 0025 — "Consistency
+    # The out-of-band half of `projects` (S12, ADR 0025 — "Consistency
     # across aggregate boundaries"). A projected field is never written
     # by the command that reads it — nothing at dispatch time takes a
     # live cross-aggregate read the way `CommandRules::References
     # #dereference` still does — so this is the one place a projected
     # field's value actually gets copied over: walk every record of the
-    # OWNING aggregate, resolve each of its own `projected_fields`
+    # owning aggregate, resolve each of its own `projected_fields`
     # through the reference it names, and `save` the local copy.
     #
-    # EXPLICIT AND CALLABLE, NOT AUTOMATIC — no on-boot detection of a
+    # **Explicit and callable, not automatic** — no on-boot detection of a
     # freshly-declared `projects` with no held-era precedent, no
     # generated `Policy#for_each` reaction keeping it live in real
     # time as the target changes. Both are real extensions this same
@@ -19,7 +19,7 @@ module Hecks
     # needs — proven to work end to end before either automatic
     # trigger is built on top of it.
     #
-    # NEEDS NO NEW ADAPTER CAPABILITY. `find`/`all`/`save` are the same
+    # **Needs no new adapter capability**. `find`/`all`/`save` are the same
     # three primitives every real adapter already answers identically
     # (`Ports::Persistence::AppendOnly#save` — append, then project,
     # the same for Memory/Postgres/SQLite/D1/Heki) — confirmed by

data/lib/hecks/runtime/reference_hop.rb

@@ -13,12 +13,12 @@ module Hecks
     # answers a hop for free, with no per-engine code and no way for
     # one engine to forget it.
     #
-    # A hop's own filtering never happens here — RESOLVING one hop
+    # A hop's own filtering never happens here — resolving one hop
     # means running one ordinary, adapter-agnostic query against the
-    # hop's TARGET aggregate (through the same Ports::Query boundary
+    # hop's target aggregate (through the same Ports::Query boundary
     # any other query goes through), and folding the ids it answers
     # back in as a local membership check. A multi-hop chain resolves
-    # from the FAR END inward: `fold` only ever peels off the head hop
+    # from the far end inward: `fold` only ever peels off the head hop
     # (QuerySpecification::HopPath.next_hop, the one-step primitive),
     # and hands everything still left in the tail to a recursive
     # `apply` call — so hop 2, hop 3, and so on each get resolved by
@@ -63,12 +63,12 @@ module Hecks
         QuerySpecification::Common::WhereClause.new(field: hop.attribute.name, op: "in", value: ids)
       end
 
-      # Every id the inner clause admits on the hop's TARGET — one
+      # Every id the inner clause admits on the hop's target — one
       # whole, ordinary query against the target's own repository,
       # through the very same Ports::Query boundary the outer ask
       # uses, so a hop is answered by whatever engine the target
       # aggregate is actually bound to (which may not be the engine
-      # the OUTER aggregate is bound to at all) rather than by a
+      # the outer aggregate is bound to at all) rather than by a
       # second reading of the comparators.
       def matching_ids(domain, target, wheres, args, registry:)
         spec       = apply(QuerySpecification::Common::Options.new(wheres: wheres), args,
@@ -81,7 +81,7 @@ module Hecks
       end
 
       # Never returned to a caller that might call an IR-level method
-      # (`to_h`, …) whose OWN internal `wheres` read would resolve
+      # (`to_h`, …) whose own internal `wheres` read would resolve
       # against the original object, not this override — the exact
       # caution TenantScope::Scoped's own comment gives, for the exact
       # same reason: SimpleDelegator only intercepts calls made

data/lib/hecks/runtime/refusal_wording.rb

@@ -1,134 +1,111 @@
+require_relative "../vocabulary"
+
 module Hecks
   module Runtime
     # Every DomainRefusal wording that is not already data — `given`/
     # `ensures`/a declared `invariant` already carry their own description,
     # read at dispatch time off the command or value object that declared
-    # them. These are different in kind: LANGUAGE-LEVEL refusals, the same
+    # them. These are different in kind: language-level refusals, the same
     # wording for every domain, not authored per-bluebook.
     #
-    # Declared the same way in Vocabulary::RefusalTemplate
-    # (language/bluebook/vocabulary.bluebook) — spec/refusal_wording_
-    # conformance_spec holds this table equal to the language, both
-    # directions. Hand-typed rather than read live off the meta-domain at
-    # every dispatch, the same reason Expression::Evaluator::
-    # SIGN_TEST_OPERATORS is hand-typed beside Vocabulary::SignTest.
+    # Read off the generated table, not typed a second time. The rows are
+    # Vocabulary::RefusalTemplate (language/bluebook/vocabulary.bluebook),
+    # projected into lib/hecks/vocabulary.rb by bin/project_vocabulary and
+    # into rust/src/kernel/vocab/refusal_template.rs by
+    # bin/project_rust_vocabulary; both regenerations are diffed in CI, so
+    # there is no hand copy left here to drift. Declared order is kept.
+    #
+    # **The arguments are data too**. Vocabulary::RefusalSiteArgument names the
+    # values each site takes and how each is written (a list's separator,
+    # its sort, its empty reading, its quoting). Call sites use
+    # `render_site` and hand over raw values; the Rust kernel's typed
+    # `render_args` applies the same rows, and the projection that writes it
+    # pins every site's output against `format_argument`/`substitute` here.
     module RefusalWording
-      # `Layout/HashAlignment`'s repo-wide `table` style (.rubocop.yml)
-      # would force every template string below onto the SAME column —
-      # matching the widest key — leaving the longer wordings almost no
-      # room to wrap under Layout/LineLength's own 130-column limit.
-      # Disabled for exactly this one hash literal (a single statement, so
-      # disable-next rather than a disable/enable pair).
-      # rubocop:disable-next Layout/HashAlignment
-      TEMPLATES = {
-        %w[NotFound creating_no_identity]             =>
-        "{command} creates a {aggregate} — pass {identity}:",
-        %w[AlreadyExists creating_duplicate]          =>
-        "{command} creates a {aggregate} that already exists — {identity} {offered}",
-        %w[AlreadyExists entity_duplicate]            =>
-        "a {entity} already exists on {aggregate} — {identity} {offered}",
-        %w[NotFound acting_no_identity]               =>
-        "{command} acts on an existing {aggregate} — pass {identity}:",
-        %w[NotFound record_missing]                   =>
-        "no {aggregate} with {identity} {offered}",
-        %w[NotFound entity_parent_no_identity]        =>
-        "{command} acts on a {aggregate}'s {entity} — pass {identity}:",
-        %w[UnknownVerb entity_unknown]                =>
-        "{aggregate} has no entity {entity}",
-        %w[NotFound entity_element_no_identity]       =>
-        "{command} acts on one {entity} — pass {identity}:",
-        %w[NotFound entity_element_missing]           =>
-        "no {entity} with {identity} {wants} on {aggregate} {parent_id}",
-        %w[NotFound reference_target_missing]         =>
-        "no {target} with {heads} {key}",
-        %w[NotFound read_model_reference_missing]     =>
-        "no {aggregate} with reference {offered}",
-        %w[TypeMismatch read_model_object_reference]  =>
-        "{query} refused — a reference is an id, and {field} arrived as an object",
-        %w[UnknownVerb no_query]                      =>
-        "{aggregate} has no query {query}",
-        %w[UnknownVerb entity_query_missing]          =>
-        "{entity} has no query {query}",
-        %w[UnknownVerb entity_holds_no_list]          =>
-        "{aggregate} holds no list of {entity}",
-        %w[UnknownVerb entity_no_command]             =>
-        "{entity} has no command {command}",
-        %w[UnknownVerb aggregate_no_command]          =>
-        "{aggregate} has no command {command}",
-        %w[UnknownVerb port_no_operation]             =>
-        "{port} has no operation {operation}",
-        %w[UnknownVerb no_domain]                     =>
-        "no domain {domain} loaded (verb {verb})",
-        %w[UnknownVerb no_read_model]                 =>
-        "{domain} has no read model {query}",
-        %w[UnknownVerb not_fully_qualified]           =>
-        "{verb} is not a fully-qualified verb (Domain::Aggregate.Command)",
-        %w[UnknownVerb no_aggregate]                  =>
-        "{domain} has no aggregate {aggregate}",
-        %w[LifecycleRefused transition_blocked]       =>
-        "{command} refused — {field} is {current}, and {command} moves it only from {allowed}",
-        %w[TypeMismatch value_object_shape]           =>
-        "{name} is a {type} — pass its fields as an object, not {offered}",
-        %w[TypeMismatch reference_wrong_shape]         =>
-        "{command} refused — a reference is an id, and {attribute} arrived as {offered}{known_by}",
-        %w[TypeMismatch multi_field_scalar]           =>
-        "{type} has multiple fields and cannot stand in for a scalar",
-        %w[TypeMismatch composite_identity]           =>
-        "{type} is a composite identity — an identity must have exactly one field",
-        %w[TypeMismatch numeric_field]                =>
-        "{type}.{field} expects {expected}, got {offered}",
-        %w[TypeMismatch non_finite_field]             =>
-        "{type}.{field} must be a finite number, got {offered}",
-        %w[TypeMismatch integer_range]                =>
-        "{type}.{field} must fit in a 64-bit integer, got {offered}",
-        %w[TypeMismatch pattern_mismatch]             =>
-        "{type}.{field} must match {pattern}, got {offered}",
-        %w[TypeMismatch arithmetic_amount]            =>
-        "{op} of {target} needs an Integer, got {offered}",
-        %w[TypeMismatch arithmetic_current]           =>
-        "{op} of {target} needs an Integer {target}, got {offered}",
-        %w[TypeMismatch arithmetic_shared_field]      =>
-        "{op} of {target} needs a value object with one shared Integer field",
-        %w[UnknownArgument unknown_args]              =>
-        "{command} does not declare {unknown} — it takes {declared}",
-        %w[AbsentArgument absent_args]                =>
-        "{command} was not given {absent} — it takes {declared}",
-        %w[InvariantViolation closed_set_member]      =>
-        "{type} admits {admitted} — got {offered}",
-        %w[InvariantViolation value_object_invariant] =>
-        "{name} invariant violated — {description} (given {offered})",
-        %w[InvariantViolation admits_declared_set]    =>
-        "{name} admits {admits} — {admitted} — got {offered}",
-        %w[InvariantViolation undeclared_set]         =>
-        "{name} admits {admits}, which this chapter does not declare — a closed set is named Aggregate::SetName, and it must " \
-        "be one the bluebook actually holds",
-        %w[Unauthorized tenant_required]              =>
-        "{query} declares authorize with tenant: {field} — pass {field}: to name which {field} this ask is scoped to",
-        %w[Unauthorized role_mismatch]                =>
-        "{command} refused — role: {role}, and the caller stated {caller_role}",
-        %w[Unauthorized cross_tenant_reference]        =>
-        "{aggregate} {field} is {tenant}, but {attribute} names a {target} whose own {target_field} " \
-        "is {other} — a cross-tenant reference",
-        %w[AttributeAbsent absent_read]               =>
-        "{aggregate} {field} is absent on this record — declared, not optional, and added since it was written. Backfill it " \
-        "in a translation (backfill :{field}, default: ...), or declare it optional: true",
-        %w[ProjectionAbsent absent_read]              =>
-        "{aggregate} {field} is not yet projected on this record — declared via projects :{field}, but no rebuild sweep has " \
-        "populated it. Run the sweep, or read {reference}.{remote_field} directly if this rule cannot wait"
-      }.freeze
+      TEMPLATES = Hecks::Vocabulary.rows("RefusalTemplate")
+                                   .to_h { |row| [[row["refusal"], row["site"]].freeze, row["template"]] }
+                                   .freeze
+
+      SHAPES   = %w[scalar list].freeze
+      QUOTINGS = %w[none inspect].freeze
 
       module_function
 
       # Plain text substitution, never expression syntax — a template is
-      # read, not evaluated. `render` computes the placeholder VALUES via
-      # whatever the call site already had (a joined list, a rendered
-      # identity reading, …) and this only replaces the markers.
+      # read, not evaluated. Values arrive already formatted; prefer
+      # `render_site`, which formats them off the declared rows.
       def render(refusal, site, **values)
-        template = TEMPLATES.fetch([refusal, site]) do
+        substitute(template(refusal, site), values)
+      end
+
+      # The one door call sites use: exactly the arguments the site
+      # declares (a missing or undeclared one raises ArgumentError before
+      # any wording exists), each formatted by its RefusalSiteArgument row,
+      # substituted in declared order.
+      #
+      #   RefusalWording.render_site("UnknownArgument", "unknown_args",
+      #                              command: "Close", unknown: [:parcel], declared: [])
+      #   # => "Close does not declare parcel — it takes none"
+      def render_site(refusal, site, **arguments)
+        specs    = argument_rows(refusal, site)
+        declared = specs.map { |spec| spec["argument"].to_sym }
+        missing  = declared - arguments.keys
+        extra    = arguments.keys - declared
+        if missing.any? || extra.any?
+          raise ArgumentError, "#{refusal}/#{site} takes #{declared.join(', ')} — " \
+                               "missing: #{missing.join(', ')}; undeclared: #{extra.join(', ')}"
+        end
+
+        render_with(template(refusal, site), specs, arguments)
+      end
+
+      # `render_site` without the registry lookups: a template, its
+      # argument rows, and raw values. The Rust projection calls this with
+      # the chapter's own rows to compute the expected wording it pins.
+      def render_with(template, specs, arguments)
+        values = specs.to_h do |spec|
+          name = spec["argument"].to_sym
+          [name, format_argument(spec, arguments.fetch(name))]
+        end
+        substitute(template, values)
+      end
+
+      # One argument, written the way its row says. A list is sorted first
+      # (before quoting), then each item quoted, then joined; an empty list
+      # reads `when_empty`. A scalar is quoted or taken as its own text.
+      def format_argument(spec, value)
+        inspect = spec.fetch("quoting") == "inspect"
+        return inspect ? value.inspect : value.to_s unless spec.fetch("shape") == "list"
+
+        items = Array(value)
+        items = items.sort if spec.fetch("sorted") == "true"
+        items = items.map(&:inspect) if inspect
+        items.empty? ? spec.fetch("when_empty") : items.join(spec.fetch("separator"))
+      end
+
+      def substitute(template, values)
+        values.reduce(template) { |text, (key, value)| text.gsub("{#{key}}", value.to_s) }
+      end
+
+      def template(refusal, site)
+        TEMPLATES.fetch([refusal, site]) do
           raise KeyError, "no refusal template for #{refusal}/#{site} — declare it in " \
                           "Vocabulary::RefusalTemplate first"
         end
-        values.reduce(template) { |text, (key, value)| text.gsub("{#{key}}", value.to_s) }
+      end
+
+      # Read lazily, not into a constant: bin/project_vocabulary boots
+      # `hecks` (and so this file) before it writes the table a newly
+      # declared site's rows live in.
+      def argument_rows(refusal, site)
+        @argument_rows ||= Hecks::Vocabulary.rows("RefusalSiteArgument")
+                                            .group_by { |row| [row["refusal"], row["site"]] }
+                                            .transform_values(&:freeze)
+                                            .freeze
+        @argument_rows.fetch([refusal, site]) do
+          raise KeyError, "no refusal arguments for #{refusal}/#{site} — declare them in " \
+                          "Vocabulary::RefusalSiteArgument first"
+        end
       end
     end
   end