hecks 0.2.0 → 1.0.0

data/lib/hecks/runtime/read_model_interpreter.rb

@@ -0,0 +1,341 @@
+require_relative "../rendering"
+require_relative "errors"
+require_relative "value"
+require_relative "refusal_wording"
+require_relative "tenant_scope"
+require_relative "../ports/query/in_memory"
+require_relative "../query_specification/field_path"
+
+module Hecks
+  module Runtime
+    class ReadModelInterpreter
+      def initialize(registry) = @registry = registry
+
+      def call(domain, model, args)
+        project(domain, model, args)
+      end
+
+      private
+
+      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.
+        # 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.
+        # Refused up front, identically on every path. Nothing to refuse for
+        # a rootless model — there's no reference argument to have offered
+        # 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
+        # "which head do options apply to" question is about what the
+        # bluebook author declared, not about the synthetic tenant clause
+        # the wrapper adds underneath.
+        eligible = model.filtered_head_name
+        model = TenantScope.apply(model, args)
+        # 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,
+        # 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
+        # aggregate yet, a real, named limit, not a silent one — the
+        # same one `group_by` already accepted, extended here rather
+        # than narrowed.
+        unless rootless || model.group_by.any? || model.count? || model.median_field
+          repository = @registry.read_repository(domain, bluebook.aggregate(model.reference_target))
+          return repository.query_read_model(domain, model, args, bluebook) if repository.respond_to?(:query_read_model) && repository.adapter.respond_to?(:query_read_model)
+        end
+
+        # 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
+        # their literal declared order and match each "many" head
+        # 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
+        # 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,
+        # and correctness here must not depend on it being so by
+        # chance on the current MRI build.
+        root_heads, other_heads = model.aggregate_heads.partition { |head| head[:aggregate] == model.reference_target }
+        projected = []
+        rows_by_as = {}
+        (root_heads + order_other_heads(bluebook, root_heads, other_heads)).each do |head|
+          rows = if head[:aggregate] == model.reference_target
+                   [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 aren't cross-joined
+                   # against each other either — each is its own bulk
+                   # read. A real, deliberate scope limit for now.)
+                   records(bluebook, domain, head[:aggregate])
+                 else
+                   matching(records(bluebook, domain, head[:aggregate])) do |record|
+                     projected.any? do |source|
+                       reference_fields(bluebook.aggregate(head[:aggregate]), source[:aggregate]).any? do |field|
+                         source[:rows].any? { |parent| reference(record[field]) == parent.id }
+                       end
+                     end
+                   end
+                 end
+          rows = Ports::Query::InMemory.execute(rows, model, args) if head[:as] == eligible
+          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
+        # computation above needed reordering, not what a caller sees
+        # back.
+        heads = model.aggregate_heads.each_with_object({}) { |head, report| report[head[:as]] = rows_by_as[head[:as]] }
+        grouped_head = group_by_target(model, bluebook)
+        reduced_head = aggregation_target(model, bluebook)
+        [heads.each_with_object({}) do |(as, value), out|
+          out[as] = if grouped_head && as == grouped_head[:as]
+                      nest(value.map { |record| Value.materialize_unwrapped(row(record)) }, model.group_by_fields)
+                    elsif reduced_head && as == reduced_head[:as] && model.count?
+                      value.length
+                    elsif reduced_head && as == reduced_head[:as]
+                      median(value, model.median_field)
+                    elsif value.is_a?(Array)
+                      value.map { |record| Value.materialize(row(record)) }
+                    else
+                      Value.materialize(row(value))
+                    end
+        end]
+      end
+
+      # 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
+      # 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`
+      # on a read model rooted at Item, where Coupon references
+      # Promotion (which references Item), silently returned an empty
+      # `coupons` array — Coupon's match ran while `projected` held only
+      # Item, one level short of what it needed.
+      #
+      # Fixed the same way root-first was: not by asking bluebook authors
+      # 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
+      # this method's runtime matching ever runs — Kahn's algorithm,
+      # 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
+      # other head at once (not just a straight chain).
+      #
+      # A cycle among non-root heads (A references B which references A)
+      # has no valid topological order at all — falls back to the
+      # remaining heads' declared order rather than looping forever, the
+      # same "whichever runs first finds nothing" behaviour this method
+      # had for every non-root head before root-first existed.
+      def order_other_heads(bluebook, root_heads, other_heads)
+        resolved = root_heads.map { |head| head[:aggregate] }
+        remaining = other_heads.dup
+        ordered = []
+        until remaining.empty?
+          ready, blocked = remaining.partition do |head|
+            depends_on(bluebook, head, other_heads).all? { |target| resolved.include?(target) }
+          end
+          if ready.empty?
+            ordered.concat(remaining)
+            break
+          end
+          ordered.concat(ready)
+          resolved.concat(ready.map { |head| head[:aggregate] })
+          remaining = blocked
+        end
+        ordered
+      end
+
+      # 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
+      # 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.
+      # `bluebook.aggregate` only ever finds the latter
+      # (Behaviour::Chapter#aggregate searches `@aggregates`, which
+      # holds no entities), so it returns nil for an entity-headed
+      # include — a real case, not a malformed one. `records`, below,
+      # already treats that nil as "no rows of its own to fetch" ;
+      # a head with no rows of its own has nothing to check for a
+      # reference field either, so it depends on nothing here, the
+      # same as it always silently read empty before this file's
+      # topological sort existed.
+      def depends_on(bluebook, head, other_heads)
+        aggregate = bluebook.aggregate(head[:aggregate])
+        return [] unless aggregate
+
+        other_heads.reject { |other| other[:aggregate] == head[:aggregate] }
+                   .select { |other| reference_fields(aggregate, other[:aggregate]).any? }
+                   .map { |other| other[:aggregate] }
+      end
+
+      # `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
+      # silently grouping every row into one bucket keyed `nil`.
+      def group_by_target(model, bluebook)
+        return nil unless model.group_by.any?
+
+        target = model.aggregate_heads.find { |head| head[:many] }
+        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
+          # 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
+          # reports exist for.
+          next if aggregate.lifecycle && aggregate.lifecycle.field.to_sym == field.to_sym
+
+          raise ArgumentError,
+                "#{model.name}'s group_by names #{field.inspect}, but #{target[:aggregate]} " \
+                "declares no such attribute (it declares #{aggregate.attributes.map(&:name).join(', ')})"
+        end
+        target
+      end
+
+      # 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
+      # `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
+      # share the same full key path. A real, deliberate scope limit:
+      # true multi-row-per-leaf grouping would change the leaf shape
+      # from "one row" to "an array of rows", which no caller needs yet.
+      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
+          # list — `rest`'s own fields have to survive into the recursive
+          # 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 } }
+          rest.empty? ? stripped.first : nest(stripped, rest)
+        end
+      end
+
+      # `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
+      # there is exactly one to name whenever this is asked at all).
+      # Raises loudly on a `median` field that doesn't exist, or exists
+      # but isn't numeric, rather than silently comparing garbage or
+      # averaging strings.
+      def aggregation_target(model, bluebook)
+        return nil unless model.count? || model.median_field
+
+        target = model.aggregate_heads.find { |head| head[:many] }
+        return target unless model.median_field
+
+        aggregate = bluebook.aggregate(target[:aggregate])
+        attribute = aggregate.attribute(model.median_field)
+        unless attribute
+          raise ArgumentError,
+                "#{model.name}'s median names #{model.median_field.inspect}, but #{target[:aggregate]} " \
+                "declares no such attribute (it declares #{aggregate.attributes.map(&:name).join(', ')})"
+        end
+        unless QuerySpecification::FieldPath.numeric?(attribute, []) { |type| aggregate.value_object(type) }
+          raise ArgumentError,
+                "#{model.name}'s median names #{model.median_field.inspect} on #{target[:aggregate]}, " \
+                "which is not numeric — median needs a numeric field (a bare number, or a " \
+                "value object carrying one)"
+        end
+        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
+      # 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
+      # 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`/
+      # `order_by` already give a value-object-carrying field, so
+      # `median :daily_limit` on a `DailyLimit{cents}` field reads the
+      # same scalar an `order_by :daily_limit` comparison already would.
+      def median(rows, field)
+        values = rows.map { |record| Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row(record), field)) }
+                     .compact.sort
+        return nil if values.empty?
+
+        middle = values.length / 2
+        values.length.odd? ? values[middle] : (values[middle - 1] + values[middle]) / 2.0
+      end
+
+      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)))
+      end
+
+      def records(bluebook, domain, aggregate_name)
+        aggregate = bluebook.aggregate(aggregate_name)
+        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 different thing from the identity unwrap that was removed. An
+      # 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
+      # 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
+      # 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)
+      end
+
+      # A reference is the id, in the argument and in the stored row alike.
+      def reference(value) = value.to_s
+
+      def reference_fields(aggregate, target)
+        aggregate.attributes
+                 .select { |attribute| attribute.reference? && attribute.type.target_name == target.to_s }
+                 .map(&:name)
+      end
+
+      def matching(records) = records.select { |record| yield(record) }.sort_by(&:id)
+      def row(record) = record.to_h
+    end
+  end
+end

data/lib/hecks/runtime/rebuild_sweep.rb

@@ -0,0 +1,74 @@
+module Hecks
+  module Runtime
+    # 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`
+    # through the reference it names, and `save` the local copy.
+    #
+    # 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
+    # ADR section describes; both are deliberately deferred. This is
+    # the mechanism a caller reaches for by hand — `bin/rebuild
+    # Domain::Aggregate`, a scheduled job, whatever the deployment
+    # 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
+    # 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
+    # direct reading before this was built, not assumed.
+    module RebuildSweep
+      module_function
+
+      # One aggregate's own projected fields, refreshed across every
+      # record it holds. Returns how many records actually changed —
+      # `save` only runs when a projected value would differ from what
+      # is already stored, so re-running a sweep with nothing having
+      # moved on the target side touches the append log not at all.
+      def call(registry, domain, aggregate)
+        return 0 if aggregate.projected_fields.empty?
+
+        repository = registry.repository(domain, aggregate)
+        repository.all.count { |record| refresh(registry, domain, aggregate, record, repository) }
+      end
+
+      def refresh(registry, domain, aggregate, record, repository)
+        changed = false
+
+        aggregate.projected_fields.each do |field|
+          value = remote_value(registry, domain, aggregate, record, field)
+          next if value.nil?
+          next if record.key?(field.name) && record[field.name] == value
+
+          record[field.name] = value
+          changed = true
+        end
+
+        repository.save(record) if changed
+        changed
+      end
+
+      # `nil` when the reference itself does not resolve in this
+      # chapter (a cross-domain target left "unfollowed" the same way
+      # References#dereference already leaves one) or when the record
+      # names no target at all — an optional reference nobody set.
+      def remote_value(registry, domain, aggregate, record, field)
+        target = aggregate.attribute(field.reference)&.type&.resolve
+        return nil unless target
+
+        id = record[field.reference]
+        return nil if id.nil?
+
+        remote = registry.repository(domain, target).find(id.to_s)
+        remote&.[](field.remote_field)
+      end
+    end
+  end
+end

data/lib/hecks/runtime/reference_hop.rb

@@ -0,0 +1,99 @@
+require "delegate"
+require_relative "../query_specification/common/where_clause"
+require_relative "../query_specification/common/options"
+require_relative "../query_specification/hop_path"
+require_relative "../ports/query"
+require_relative "registry"
+
+module Hecks
+  module Runtime
+    # `TenantScope`'s sibling — a hop folds to a synthetic `in`
+    # where-clause the exact same way a tenant boundary folds to a
+    # synthetic `eq` one, so every engine that already reads `.wheres`
+    # 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
+    # means running one ordinary, adapter-agnostic query against the
+    # 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
+    # (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
+    # their own ordinary query against their own target, one recursion
+    # level at a time, never by this module trying to see the whole
+    # chain at once. It terminates because each recursion is over a
+    # strictly shorter dotted string, and
+    # BluebookBuilder#validate_query_hops! already refused any chain
+    # deep enough to matter before this ever runs.
+    module ReferenceHop
+      module_function
+
+      def apply(declared, args, registry:, domain:, aggregate:)
+        hopped, local = declared.wheres.partition { |clause| QuerySpecification::HopPath.hop_head?(clause.field, aggregate.attributes) }
+        return declared if hopped.empty?
+
+        folded = hopped.map { |clause| fold(clause, args, registry: registry, domain: domain, aggregate: aggregate) }
+        Folded.new(declared, local + folded)
+      end
+
+      def fold(clause, args, registry:, domain:, aggregate:)
+        step = QuerySpecification::HopPath.next_hop(clause.field, aggregate.attributes)
+        hop, rest = step
+
+        # A guarantee BluebookBuilder#validate_query_hops! already gave
+        # this exact clause before the domain ever booted. Held anyway:
+        # an unresolvable target folding silently to "matches
+        # everything" is precisely the failure shape this whole feature
+        # exists to close, and a hop that can no longer resolve (a
+        # target aggregate unloaded after boot, say) is a real fact
+        # worth a real error, not a query that quietly stops filtering.
+        unless hop&.target
+          raise WiringError,
+                "#{clause.field} hops through a reference this domain cannot resolve " \
+                "right now — the chapter seal already checked this once; something " \
+                "changed between then and this dispatch"
+        end
+
+        inner = QuerySpecification::Common::WhereClause.new(field: rest, op: clause.op, value: clause.value)
+        ids   = matching_ids(domain, hop.target, [inner], args, registry: registry)
+
+        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
+      # 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
+      # second reading of the comparators.
+      def matching_ids(domain, target, wheres, args, registry:)
+        spec       = apply(QuerySpecification::Common::Options.new(wheres: wheres), args,
+                           registry: registry, domain: domain, aggregate: target)
+        repository = registry.repository(domain, target)
+        rows       = Ports::Query.execute(repository, spec, args, context: { domain: domain, aggregate: target }) ||
+                     Ports::Query::InMemory.execute(repository.all, spec, args)
+
+        rows.map { |row| row.id.to_s }.uniq
+      end
+
+      # Never returned to a caller that might call an IR-level method
+      # (`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
+      # directly on the wrapper.
+      class Folded < SimpleDelegator
+        def initialize(declared, wheres)
+          super(declared)
+          @wheres = wheres
+        end
+
+        def wheres = @wheres
+      end
+    end
+  end
+end

data/lib/hecks/runtime/refusal_wording.rb

@@ -0,0 +1,126 @@
+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
+    # 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.
+    module RefusalWording
+      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_as_object]          =>
+                                                         "{command} refused — a reference is an id, and {attribute} arrived as an object{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 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[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
+
+      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.
+      def render(refusal, site, **values)
+        template = 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
+    end
+  end
+end