hecks 1.3.0 → 1.5.0

data/lib/hecks/runtime/refusal_wording.rb

@@ -1,134 +1,161 @@
+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
 
+      # Renders `refusal`/`site`'s template, substituting `values` verbatim.
+      #
       # 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.
+      #
+      # @param refusal [String] the `DomainRefusal` class name, such as `"UnknownArgument"`
+      # @param site [String] the template site within `refusal`, such as `"unknown_args"`
+      # @param values [Hash{Symbol => #to_s}] each `{name}` placeholder's already-formatted
+      #   replacement text
+      # @return [String] the rendered refusal message
+      # @raise [KeyError] if no `RefusalTemplate` row declares `refusal`/`site`
       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"
+      #
+      # @param refusal [String] the `DomainRefusal` class name, such as `"UnknownArgument"`
+      # @param site [String] the template site within `refusal`, such as `"unknown_args"`
+      # @param arguments [Hash{Symbol => Object}] raw values, one per `RefusalSiteArgument`
+      #   row declared for `refusal`/`site`; formatted per row before substitution
+      # @return [String] the rendered refusal message
+      # @raise [ArgumentError] if `arguments` is missing a declared argument or offers one
+      #   `refusal`/`site` does not declare
+      # @raise [KeyError] if no `RefusalTemplate`/`RefusalSiteArgument` rows declare
+      #   `refusal`/`site`
+      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.
+      #
+      # @param template [String] the raw template, `{name}` placeholders unsubstituted
+      # @param specs [Array<Hash>] the `RefusalSiteArgument` rows to format `arguments`
+      #   against, one per declared argument name
+      # @param arguments [Hash{Symbol => Object}] raw values, one per entry in `specs`
+      # @return [String] the rendered refusal message
+      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.
+      #
+      # @param spec [Hash] the argument's `RefusalSiteArgument` row (`"shape"`, `"quoting"`,
+      #   and, for a list, `"sorted"`, `"separator"`, `"when_empty"`)
+      # @param value [Object, Array] the raw value to format; an Array (or anything
+      #   `Array()`-coercible) for a `"list"`-shaped spec, a scalar otherwise
+      # @return [String] the formatted 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
+
+      # Replaces each `{name}` placeholder in `template` with its value's text.
+      #
+      # @param template [String] the raw template, `{name}` placeholders unsubstituted
+      # @param values [Hash{Symbol => #to_s}] each placeholder name mapped to its
+      #   replacement text
+      # @return [String] `template` with every `{name}` placeholder substituted
+      def substitute(template, values)
+        values.reduce(template) { |text, (key, value)| text.gsub("{#{key}}", value.to_s) }
+      end
+
+      # Looks up the raw template text declared for one refusal site.
+      #
+      # @param refusal [String] the `DomainRefusal` class name, such as `"UnknownArgument"`
+      # @param site [String] the template site within `refusal`, such as `"unknown_args"`
+      # @return [String] the raw `RefusalTemplate` text, `{name}` placeholders unsubstituted
+      # @raise [KeyError] if no `RefusalTemplate` row declares `refusal`/`site`
+      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
+
+      # The declared arguments for one refusal site.
+      #
+      # 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.
+      #
+      # @param refusal [String] the `DomainRefusal` class name, such as `"UnknownArgument"`
+      # @param site [String] the template site within `refusal`, such as `"unknown_args"`
+      # @return [Array<Hash>] the `RefusalSiteArgument` rows declared for `refusal`/`site`
+      # @raise [KeyError] if no `RefusalSiteArgument` rows declare `refusal`/`site`
+      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

data/lib/hecks/runtime/registry/saga_persistence.rb

@@ -3,43 +3,52 @@ require_relative "../saga_pending_dispatch"
 module Hecks
   module Runtime
     class Registry
-      # SAGA PERSISTENCE — no new DSL verb, no new world setting.
+      # **Saga persistence** — no new DSL verb, no new world setting.
       # Whatever adapter a domain's own aggregates already use for
       # durability, its sagas use the same one, automatically: three
-      # OPTIONAL adapter methods (`save_saga`/`delete_saga`/`each_saga`),
+      # optional adapter methods (`save_saga`/`delete_saga`/`each_saga`),
       # `respond_to?`-checked the same way `Ports::Persistence::AppendOnly`
       # already treats an adapter's own optional methods
       # (`find`/`all`/`count`/`reset!`/`events`/`record_event`).
       module SagaPersistence
-        # Resolved and memoized per domain — the FIRST real aggregate
+        # Resolved and memoized per domain — the first real aggregate
         # declared in the domain's own bluebook is the resolution
         # anchor. `Ports::Persistence::BindingPolicy.resolve` for that
         # aggregate already falls back to a domain-level default bind
         # (§0's `Hecksagon#bind_for`) before falling back to Memory, so
         # this needs no separate "was a default declared" branch of its
-        # own — whatever adapter that anchor resolves to already IS the
+        # own — whatever adapter that anchor resolves to already is the
         # domain's own default in the normal case (every aggregate
         # shares one adapter), and is the honest, documented fallback
         # for the rarer domain genuinely split across more than one
         # local adapter with no default declared.
         #
-        # GENUINELY LAZY, GENUINELY POST-BOOT — unlike `rehydrate_sagas!`
+        # Genuinely lazy, genuinely POST-boot — unlike `rehydrate_sagas!`
         # below (boot-only), this is called from live dispatch
         # (`SagaInterpreter#checkpoint`/`#end_saga`, on every saga
-        # transition), so the FIRST call for a given domain can come from
+        # transition), so the first call for a given domain can come from
         # any dispatching thread, not just the boot thread. `@saga_persistence`
         # itself is a plain Hash stood up once in `Registry#initialize` (no
         # race on the container), but `resolve_saga_persistence` is real work
         # (a `BindingPolicy.resolve` plus a lazy `repository` build) whose
-        # RESULT — the actual adapter instance a domain's sagas persist
-        # through — must be the SAME object for every caller: two threads
+        # result — the actual adapter instance a domain's sagas persist
+        # through — must be the same object for every caller: two threads
         # racing the first lookup and each building their own adapter would
         # silently split one domain's saga writes across two adapter
         # instances (worse than `Dispatcher#reaction_depth`'s M20 — that bug
-        # corrupted a counter; this one can corrupt WHICH STORE a saga's
-        # state lands in). Double-checked locking against a DEDICATED mutex
+        # corrupted a counter; this one can corrupt which store a saga's
+        # state lands in). Double-checked locking against a dedicated mutex
         # — never `@saga_mutex` — see `Registry#initialize`'s own comment for
         # why reusing that one would deadlock.
+        # Resolves and memoizes the adapter a domain's sagas persist through.
+        #
+        # @param domain [String, Symbol] the domain to resolve saga persistence for
+        # @return [Adapters::Heki, Adapters::Postgres, Adapters::Sqlite, Adapters::D1,
+        #   Ports::Persistence::Plugins::Era::PostgresEra, Ports::Persistence::NullSagaStore]
+        #   the same adapter instance the domain's anchor aggregate persists through, when it
+        #   implements `save_saga`; `NULL_SAGA_STORE` for a domain with no anchor aggregate, an
+        #   adapter that does not implement the capability, a `RemoteRuntime`-shaped adapter,
+        #   or a `Runtime::WiringError` resolving the anchor's own bind
         def saga_persistence(domain)
           key = domain.to_s
           @saga_persistence[key] || @saga_persistence_mutex.synchronize do
@@ -47,26 +56,28 @@ module Hecks
           end
         end
 
-        # WALKS EVERY LOADED DOMAIN, repopulating `saga_instances` from
+        # Walks every loaded domain, repopulating `saga_instances` from
         # whatever `saga_persistence(domain)` resolves to — a real store
         # for a domain whose adapter answers the capability, `each_saga`
         # yielding real rows; `NULL_SAGA_STORE`'s own `each_saga` for
         # everything else, which never yields at all, so this needs no
-        # `respond_to?` branch of its own — the SAME reason every other
+        # `respond_to?` branch of its own — the same reason every other
         # call site in this capability never needs one. Called once at
         # boot (`Loader.boot`, between `verify!` and dispatcher
         # construction) — a process that's been running has no reason to
         # re-walk its own already-current `saga_instances`.
         #
-        # BOOT-TIME-ONLY (OR ITS TEST-RUNNER EQUIVALENT) — this method's
+        # Boot-time-only (or its test-runner equivalent) — this method's
         # only callers are `Loader.run_boot_gates!` (single-threaded, before
         # `dispatcher_for` ever exists) and `Registry#reset_runtime_state!`
         # (single-threaded test runner — see that method's own comment).
         # Never called from live dispatch, so `@saga_instances` mutation
-        # here has no concurrent caller to race, unlike its OTHER two write
+        # here has no concurrent caller to race, unlike its other two write
         # points inside `@saga_mutex.synchronize` blocks (`saga_interpreter.
         # rb`), which genuinely do and are guarded accordingly.
         # rubocop:disable-next Hecks/ThreadSharedIvarMutation
+        #
+        # @return [Hecks::Runtime::Registry] self
         def rehydrate_sagas!
           @hecksagons.each_key do |domain|
             saga_persistence(domain).each_saga do |process_manager, correlation, state, memory, completed_compensations = []|
@@ -81,28 +92,28 @@ module Hecks
 
         private
 
-        # THE OTHER HALF OF THE OUTBOX-SHAPED FIX (see saga_pending_
+        # The other half of the outbox-shaped fix (see saga_pending_
         # dispatch.rb) — `SAGA_PENDING_DISPATCH_KEY`, if the crashed
         # process left it standing, means the row's own `state` was
         # checkpointed but the dispatch cascade that justifies it may
         # never have run. Stripped out of `memory` before it becomes
-        # this instance's LIVE `:memory` (so nothing downstream — a
+        # this instance's live `:memory` (so nothing downstream — a
         # `given`, a `with:` mapping, the fuzzer — ever sees it), and
-        # surfaced loudly instead: a WARNING plus a `saga_log` entry,
+        # surfaced loudly instead: a warning plus a `saga_log` entry,
         # never an automatic redrive (see saga_pending_dispatch.rb for
         # why redriving without idempotent delivery would be worse than
-        # the stall). This is real, durable crash-recovery VISIBILITY —
+        # the stall). This is real, durable crash-recovery visibility —
         # still not the reconciliation itself, which stays a human's
         # call until hecks has idempotent redelivery to make it safe.
         # rubocop:disable-next Hecks/ThreadSharedIvarMutation -- same
         # justification as `rehydrate_sagas!`'s own disable comment
-        # above: this method's ONLY caller is that boot-time-only walk,
+        # above: this method's only caller is that boot-time-only walk,
         # never live dispatch, so `@saga_log` has no concurrent writer
         # to race here.
         def warn_stalled_saga(domain, process_manager, correlation, state, pending)
           # `.transform_keys(&:to_sym)` — Heki's own `each_saga` only
-          # symbolizes `memory`'s TOP-level keys (`SagaStore#each_saga`'s
-          # own `transform_keys`, one level deep); a value NESTED under
+          # symbolizes `memory`'s top-level keys (`SagaStore#each_saga`'s
+          # own `transform_keys`, one level deep); a value nested under
           # one of those keys, like this marker, comes back with plain
           # string keys from Heki specifically, symbol keys already from
           # Postgres/SQLite/D1's own `symbolize_names: true` parse. Normalizing