hecks 2.8.0 → 2.9.0

data/lib/hecks/runtime/reference_hop.rb

@@ -7,45 +7,12 @@ 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.
+    # Folds each hop where-clause into a synthetic local `in` clause, the same trick
+    # `TenantScope` uses, so any engine that already reads `.wheres` handles a hop for free.
     module ReferenceHop
       module_function
 
       # Folds every hop clause in `declared.wheres` into a synthetic local `in` clause.
-      #
-      # @param declared [Bluebook::Query, Runtime::TenantScope::Scoped,
-      #   QuerySpecification::Common::Options] the declared query specification to fold hop
-      #   clauses of
-      # @param args [Hash] the query's arguments, read when resolving each hop's own query
-      # @param registry [Runtime::Registry] the booted registry to resolve each hop's target
-      #   repository from
-      # @param domain [String] the domain `aggregate` belongs to
-      # @param aggregate [Bluebook::Aggregate] the aggregate `declared` queries
-      # @return [Bluebook::Query, Runtime::TenantScope::Scoped, QuerySpecification::Common::
-      #   Options, Hecks::Runtime::ReferenceHop::Folded] `declared` unchanged when it has no
-      #   hop clauses; otherwise a `Folded` wrapper whose `#wheres` replaces each hop clause
-      #   with its folded `in` clause
-      # @raise [Runtime::WiringError] if a hop's target does not resolve (see `fold`)
       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?
@@ -55,28 +22,12 @@ module Hecks
       end
 
       # Folds one hop clause into a synthetic `in` clause over the hop attribute's own ids.
-      #
-      # @param clause [QuerySpecification::Common::WhereClause] the hop clause to fold; its
-      #   `field` names the hop path, dotted past the first segment
-      # @param args [Hash] the query's arguments, read when resolving the inner query
-      # @param registry [Runtime::Registry] the booted registry to resolve the hop's target
-      #   repository from
-      # @param domain [String] the domain `aggregate` belongs to
-      # @param aggregate [Bluebook::Aggregate] the aggregate `clause` is declared against
-      # @return [QuerySpecification::Common::WhereClause] a synthetic `in` clause on the hop
-      #   attribute's name, whose value is every id the inner clause admits on the target
-      # @raise [Runtime::WiringError] if the hop's target aggregate does not resolve
       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 cannot resolve (a
-        # target aggregate unloaded after boot, say) is a real fact
-        # worth a real error, not a query that quietly stops filtering.
+        # BluebookBuilder#validate_query_hops! already checked this hop at boot; if it
+        # still fails to resolve here, raise rather than silently matching everything.
         unless hop&.target
           raise WiringError,
                 "#{clause.field} hops through a reference this domain cannot resolve " \
@@ -90,23 +41,8 @@ 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
-      # 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.
-      #
-      # @param domain [String] the domain `target` belongs to
-      # @param target [Bluebook::Aggregate] the hop's target aggregate to query
-      # @param wheres [Array<QuerySpecification::Common::WhereClause>] the inner clause(s) to
-      #   run against `target`
-      # @param args [Hash] the outer query's arguments, read when resolving the inner query
-      # @param registry [Runtime::Registry] the booted registry to resolve `target`'s
-      #   repository from
-      # @return [Array<String>] every distinct id the inner clause(s) admit on `target`
-      # @raise [Runtime::WiringError] if a hop nested inside `wheres` does not resolve
+      # Every id the inner clause(s) admit on `target`, queried through `target`'s own
+      # repository — which may be bound to a different engine than the outer aggregate.
       def matching_ids(domain, target, wheres, args, registry:)
         spec       = apply(QuerySpecification::Common::Options.new(wheres: wheres), args,
                            registry: registry, domain: domain, aggregate: target)
@@ -117,18 +53,9 @@ module Hecks
         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.
+      # SimpleDelegator only intercepts calls made directly on this wrapper, so never
+      # hand it to a caller that reads `wheres` via an IR-level method like `to_h`.
       class Folded < SimpleDelegator
-        # @param declared [Bluebook::Query, Runtime::TenantScope::Scoped,
-        #   QuerySpecification::Common::Options] the wrapped query specification, delegated to
-        #   for everything but `#wheres`
-        # @param wheres [Array<QuerySpecification::Common::WhereClause>] the replacement
-        #   where-clauses, hop clauses folded to synthetic `in` clauses
         def initialize(declared, wheres)
           super(declared)
           @wheres = wheres

data/lib/hecks/runtime/refusal_wording.rb

@@ -2,25 +2,8 @@ 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
-    # wording for every domain, not authored per-bluebook.
-    #
-    # 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.
+    # Language-level DomainRefusal wording, the same for every domain.
+    # Templates and argument formats are read from the generated Vocabulary tables.
     module RefusalWording
       TEMPLATES = Hecks::Vocabulary.rows("RefusalTemplate")
                                    .to_h { |row| [[row["refusal"], row["site"]].freeze, row["template"]] }
@@ -31,40 +14,13 @@ module Hecks
 
       module_function
 
-      # Renders `refusal`/`site`'s template, substituting `values` verbatim.
-      #
-      # Plain text substitution, never expression syntax — a template is
-      # 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`
+      # Renders `refusal`/`site`'s template, substituting already-formatted `values`.
       def render(refusal, site, **values)
         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`
+      # Renders a site's template from raw `arguments`, formatting each per its row.
+      # Raises ArgumentError on a missing or undeclared argument, KeyError on an unknown site.
       def render_site(refusal, site, **arguments)
         specs    = argument_rows(refusal, site)
         declared = specs.map { |spec| spec["argument"].to_sym }
@@ -78,15 +34,7 @@ module Hecks
         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
+      # `render_site` without the registry lookups; the Rust projection calls it with its own rows.
       def render_with(template, specs, arguments)
         values = specs.to_h do |spec|
           name = spec["argument"].to_sym
@@ -95,15 +43,7 @@ module Hecks
         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
+      # A list is sorted, then quoted, then joined; an empty list reads `when_empty`.
       def format_argument(spec, value)
         inspect = spec.fetch("quoting") == "inspect"
         return inspect ? value.inspect : value.to_s unless spec.fetch("shape") == "list"
@@ -114,22 +54,10 @@ module Hecks
         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 " \
@@ -137,16 +65,7 @@ module Hecks
         end
       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`
+      # Read lazily: bin/project_vocabulary boots this file before it writes these rows.
       def argument_rows(refusal, site)
         @argument_rows ||= Hecks::Vocabulary.rows("RefusalSiteArgument")
                                             .group_by { |row| [row["refusal"], row["site"]] }

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

@@ -3,52 +3,10 @@ require_relative "../saga_pending_dispatch"
 module Hecks
   module Runtime
     class Registry
-      # **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`),
-      # `respond_to?`-checked the same way `Ports::Persistence::AppendOnly`
-      # already treats an adapter's own optional methods
-      # (`find`/`all`/`count`/`reset!`/`events`/`record_event`).
+      # A domain's sagas persist through whatever adapter its aggregates already use;
+      # `save_saga`/`delete_saga`/`each_saga` are optional, `respond_to?`-checked capabilities.
       module SagaPersistence
-        # 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
-        # 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!`
-        # 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
-        # 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
-        # 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
-        # — 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
+        # Memoized per domain via double-checked locking; never reuse @saga_mutex, see #initialize.
         def saga_persistence(domain)
           key = domain.to_s
           @saga_persistence[key] || @saga_persistence_mutex.synchronize do
@@ -56,34 +14,11 @@ module Hecks
           end
         end
 
-        # Every domain whose sagas can persist somewhere: one with a hecksagon, or one a
-        # world's `default_adapter` binds though it has none.
-        #
-        # @return [Array<String>] the domain names, hecksagon domains first
         def saga_domains = @hecksagons.keys | @bluebooks.keys.select { |domain| default_adapter_for(domain) }
 
-        # Walks every loaded domain in `saga_domains`, 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
-        # 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
-        # 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
-        # points inside `@saga_mutex.synchronize` blocks (`saga_interpreter.
-        # rb`), which genuinely do and are guarded accordingly.
+        # Boot-time-only (Loader.run_boot_gates!, before dispatch exists); no concurrent
+        # writer to race here, unlike saga_interpreter.rb's writes under @saga_mutex.
         # rubocop:disable-next Hecks/ThreadSharedIvarMutation
-        #
-        # @return [Hecks::Runtime::Registry] self
         def rehydrate_sagas!
           saga_domains.each do |domain|
             saga_persistence(domain).each_saga do |process_manager, correlation, state, memory, completed_compensations = []|
@@ -98,33 +33,12 @@ module Hecks
 
         private
 
-        # 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
-        # `given`, a `with:` mapping, the fuzzer — ever sees it), and
-        # 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 —
-        # still not the reconciliation itself, which stays a human's
-        # call until hecks has idempotent redelivery to make it safe.
+        # A pending dispatch marker left by a crash: state was checkpointed but the dispatch
+        # cascade it justifies may never have run. Surfaced as a warning, never auto-redriven.
         # 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,
-        # 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
-          # 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
-          # here, once, is simpler than teaching every adapter's own
-          # shallow/deep parsing convention about this one reserved key.
+          # Heki's each_saga only symbolizes memory's top-level keys, not nested values;
+          # Postgres/SQLite/D1 already return symbol keys. Normalize here once for all adapters.
           pending    = pending.transform_keys(&:to_sym)
           dispatches = Array(pending[:dispatches]).join(", ")
           warn "[hecks] #{domain} rehydrated #{process_manager} instance #{correlation.inspect} in state " \
@@ -146,13 +60,7 @@ module Hecks
           adapter = repository(domain, anchor).adapter
           adapter.respond_to?(:save_saga) ? adapter : Ports::Persistence::NULL_SAGA_STORE
         rescue WiringError
-          # A domain not cleanly wired for its own anchor aggregate's
-          # persistence (a test fixture binding only the aggregates it
-          # exercises, say) degrades saga persistence to the same no-op
-          # default an unbound domain gets — never raises out of a
-          # dispatch that would otherwise have succeeded. Matches this
-          # capability's own framing throughout: automatic wherever it's
-          # cleanly supported, silently absent wherever it isn't.
+          # An unwired domain degrades to no saga persistence rather than raising mid-dispatch.
           Ports::Persistence::NULL_SAGA_STORE
         end
       end