hecks 1.4.0 → 1.5.1

data/lib/hecks/runtime/rebuild_sweep.rb

@@ -32,6 +32,12 @@ module Hecks
       # `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.
+      #
+      # @param registry [Runtime::Registry] the booted registry to read repositories from
+      # @param domain [String] the domain the aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose `projected_fields` to
+      #   refresh
+      # @return [Integer] the number of records actually changed and saved
       def call(registry, domain, aggregate)
         return 0 if aggregate.projected_fields.empty?
 
@@ -39,6 +45,16 @@ module Hecks
         repository.all.count { |record| refresh(registry, domain, aggregate, record, repository) }
       end
 
+      # Refreshes one record's own projected fields in place, saving it if any changed.
+      #
+      # @param registry [Runtime::Registry] the booted registry to read the target's
+      #   repository from
+      # @param domain [String] the domain the aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate `record` is an instance of
+      # @param record [Runtime::Instance] the record to refresh, mutated in place
+      # @param repository [Ports::Persistence::AppendOnly] the repository to save `record`
+      #   through when it changes
+      # @return [Boolean] true if any projected field's value changed and `record` was saved
       def refresh(registry, domain, aggregate, record, repository)
         changed = false
 
@@ -55,10 +71,22 @@ module Hecks
         changed
       end
 
+      # Reads the current value of one projected field's remote target field.
+      #
       # `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.
+      #
+      # @param registry [Runtime::Registry] the booted registry to read the target's
+      #   repository from
+      # @param domain [String] the domain the aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate declaring `field`
+      # @param record [Runtime::Instance] the record holding the reference to follow
+      # @param field [Bluebook::ProjectedField] the projected field to resolve
+      # @return [Object, nil] the target record's own `field.remote_field` value; nil if the
+      #   reference type does not resolve, the record names no target, or the target record
+      #   cannot be found
       def remote_value(registry, domain, aggregate, record, field)
         target = aggregate.attribute(field.reference)&.type&.resolve
         return nil unless target

data/lib/hecks/runtime/reference_hop.rb

@@ -31,6 +31,21 @@ module Hecks
     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 no longer resolves (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?
@@ -39,6 +54,18 @@ module Hecks
         Folded.new(declared, local + folded)
       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 no longer resolves
       def fold(clause, args, registry:, domain:, aggregate:)
         step = QuerySpecification::HopPath.next_hop(clause.field, aggregate.attributes)
         hop, rest = step
@@ -70,6 +97,16 @@ module Hecks
       # 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` no longer resolves
       def matching_ids(domain, target, wheres, args, registry:)
         spec       = apply(QuerySpecification::Common::Options.new(wheres: wheres), args,
                            registry: registry, domain: domain, aggregate: target)
@@ -87,6 +124,11 @@ module Hecks
       # same reason: SimpleDelegator only intercepts calls made
       # directly on the wrapper.
       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

@@ -31,9 +31,18 @@ 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`
       def render(refusal, site, **values)
         substitute(template(refusal, site), values)
       end
@@ -46,6 +55,16 @@ module Hecks
       #   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 }
@@ -62,6 +81,12 @@ module Hecks
       # `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
@@ -73,6 +98,12 @@ module Hecks
       # 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"
@@ -83,10 +114,22 @@ 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 " \
@@ -94,9 +137,16 @@ 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`
       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

@@ -40,6 +40,15 @@ module Hecks
         # 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
@@ -67,6 +76,8 @@ module Hecks
         # 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 = []|

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

@@ -10,9 +10,19 @@ module Hecks
       # loading, and the smaller checks are also called piecemeal by the
       # repository factory.
       module Verification
+        # Runs the whole wiring gate against this registry's loaded bluebooks,
+        # hexagons, ports and adapters.
+        #
+        # @return [Runtime::Registry] self
+        # @raise [Runtime::WiringError] if a bind names an undeclared aggregate, an
+        #   adapter cannot satisfy its port's verb or declared `answers`, a world
+        #   setting names a field its adapter does not declare, the default adapter
+        #   is unusable, or a command declares a role with no authorization provider
+        #   attached
         def verify!
           verify_default_adapter!
           verify_singleton_port_answers!
+          refuse_cross_package_bluebook_merge!
 
           @hecksagons.each_value do |hexagon|
             refuse_ungoverned_roles!(hexagon)
@@ -50,6 +60,13 @@ module Hecks
           self
         end
 
+        # Checks that the framework-wide default persistence adapter (used by any
+        # aggregate left out of an explicit bind list) is itself wired correctly.
+        #
+        # @return [Runtime::Registry] self
+        # @raise [Runtime::WiringError] if the default adapter cannot satisfy the
+        #   persistence port's verb, is missing a declared `answers` method, or has
+        #   no Ruby implementation
         def verify_default_adapter!
           name = Ports::Persistence::DEFAULT_ADAPTER
 
@@ -68,6 +85,14 @@ module Hecks
                 "aggregate with no bind could not be given one: #{e.message}"
         end
 
+        # Checks that `bind`'s adapter implements the port it names and satisfies
+        # the verb the bind declares.
+        #
+        # @param bind [Bluebook::Bind] the bind to check
+        # @return [void]
+        # @raise [Runtime::WiringError] if `bind`'s adapter is unknown, declares an
+        #   unknown port, is missing a declared `answers` method, or cannot satisfy
+        #   `bind`'s own verb
         def check_verb(bind)
           port = port_for(bind)
           check_answers(port, bind.adapter)
@@ -85,6 +110,13 @@ module Hecks
         # actually call. `answers` is optional per port (an empty list is
         # today's pre-existing behavior, unchecked), so this only ever
         # tightens a port that opted in.
+        #
+        # @param port [Bluebook::Port] the port whose declared `answers` methods
+        #   `adapter_name` must respond to
+        # @param adapter_name [String] the adapter's declared name to check
+        # @return [void]
+        # @raise [Runtime::WiringError] if `adapter_name` has no Ruby implementation,
+        #   or its implementation does not respond to one of `port.answers`
         def check_answers(port, adapter_name)
           answers = Array(port.answers)
           return if answers.empty?
@@ -114,6 +146,12 @@ module Hecks
         # exactly one adapter, wired, missing a method `answers` names.
         PER_AGGREGATE_PORTS = %w[persistence projection loading].freeze
 
+        # Checks every singleton port (not per-aggregate-bound) with exactly one
+        # wired adapter against its own declared `answers` methods.
+        #
+        # @return [Runtime::Registry] self
+        # @raise [Runtime::WiringError] if a singleton port's one wired adapter is
+        #   missing one of its declared `answers` methods
         def verify_singleton_port_answers!
           @ports.each_value do |port|
             next if PER_AGGREGATE_PORTS.include?(port.name)
@@ -127,6 +165,16 @@ module Hecks
           self
         end
 
+        # Checks that every setting `settings` declares (besides `:adapter`) is a
+        # field `bind`'s adapter actually admits.
+        #
+        # @param bind [Bluebook::Bind] the bind naming the adapter to check against;
+        #   a no-op if its adapter is unknown
+        # @param settings [Hash{Symbol => Object}] the world's declared settings for
+        #   this bind
+        # @return [void]
+        # @raise [Runtime::WiringError] if `settings` declares a field `bind`'s
+        #   adapter does not declare
         def check_settings(bind, settings)
           adapter = @adapters[bind.adapter]
           return unless adapter
@@ -141,6 +189,12 @@ module Hecks
                 "Add the field to the adapter, or remove it from the world."
         end
 
+        # Finds the port `bind`'s adapter declares.
+        #
+        # @param bind [Bluebook::Bind] the bind naming the adapter to look up
+        # @return [Bluebook::Port] the port `bind`'s adapter declares
+        # @raise [Runtime::WiringError] if `bind` names an unknown adapter, or one
+        #   declaring an unknown port
         def port_for(bind)
           adapter = @adapters[bind.adapter]
           raise WiringError, "unknown adapter #{bind.adapter.inspect}" unless adapter
@@ -149,6 +203,12 @@ module Hecks
             raise(WiringError, "adapter #{bind.adapter} declares unknown port #{adapter.port.inspect}")
         end
 
+        # Finds the Ruby module implementing the adapter declared `name`.
+        #
+        # @param name [String] the adapter's declared name, such as `"PostgresEra"`
+        # @return [Module] the adapter module or class under `Hecks::Adapters`
+        # @raise [Runtime::WiringError] if no Ruby implementation named `name` exists
+        #   under `Hecks::Adapters`
         def adapter_class(name)
           Adapters.const_get(name)
         rescue NameError
@@ -164,9 +224,9 @@ module Hecks
         # unchecked, exactly the defect ADR 0025 §9 names ("role gates
         # access control by exact string equality ... Governance ...
         # connected to none of it"). Checked here, at `verify!` — recovered
-        # and moved, not new: this used to run per-block, at hecksagon
-        # build time (Bluebook::DSL::HecksagonBuilder#build), which broke
-        # the moment a domain could be split across multiple hecksagon
+        # and moved, not new: running this per-block, at hecksagon
+        # build time (Bluebook::DSL::HecksagonBuilder#build), breaks
+        # the moment a domain is split across multiple hecksagon
         # blocks (base + an `environments/<name>.hecksagon` overlay,
         # Runtime::Loader.boot's `environment:` — see its own comment for
         # the recovery provenance): every block but the one declaring
@@ -179,7 +239,7 @@ module Hecks
         # correct (a check against an incomplete, not-yet-merged
         # hecksagon can never see the real final shape).
         #
-        # A provider is RECOGNISED by its declaration, not its name —
+        # A provider is recognised by its declaration, not its name —
         # `authorization_provider_for` answers for the domain's own
         # chapter too, so Governance (which declares `provides
         # "authorization"`) passes here because of what it declares, and
@@ -217,6 +277,61 @@ module Hecks
           bluebook_ir.aggregates.flat_map { |aggregate| aggregate.commands + aggregate.entities.flat_map(&:commands) }
         end
 
+        # TWO UNRELATED PACKAGES, ONE CHAPTER NAME BY COINCIDENCE — the
+        # real risk `Registry#bluebook_sources` exists to catch (found
+        # live: a stale `vendor/hecksagain` fork's own copy of Governance/
+        # Identity/Deploy, still reachable on 4 consuming apps' own load
+        # paths alongside the real gem). `BluebookBuilder.build`'s own
+        # accumulation (several files declaring the SAME chapter name ON
+        # PURPOSE — `lib/hecks/language/bluebook/*.bluebook` all open
+        # `Hecks.bluebook "Bluebook"`) is never touched here — that merge
+        # stays unconditional, checked only AFTER every file has loaded,
+        # the same "check the merged final result once" timing
+        # `refuse_ungoverned_roles!` already uses and for the same reason
+        # (a check against an incomplete load can never see the real
+        # shape). What distinguishes intentional accumulation from
+        # coincidence is PACKAGE ROOT, not file identity: files a real
+        # gemspec or a `vendor/` boundary already treats as one unit are
+        # expected to share a name; files from two DIFFERENT roots never
+        # legitimately do.
+        def refuse_cross_package_bluebook_merge!
+          @bluebook_sources.each do |name, paths|
+            roots = paths.map { |path| package_root_for(path) }.uniq
+            next if roots.size <= 1
+
+            raise WiringError,
+                  "#{name.inspect} is declared by more than one package: #{roots.join(' and ')} — " \
+                  "these are two unrelated sources sharing a chapter name by coincidence, not one " \
+                  "domain split across files, and merging their declarations into one chapter is " \
+                  "almost certainly a stale/vendored copy left on the load path (paths: " \
+                  "#{paths.join(', ')})"
+          end
+        end
+
+        # THE NEAREST BOUNDARY A PATH ALREADY BELONGS TO — a real
+        # gemspec (this IS a package, whatever depends on it or vendors
+        # it), or a bare `vendor/` path component, treated as its OWN
+        # root regardless of what gemspec might sit above it: vendored
+        # code should never be considered "the same package" as whatever
+        # it's vendored into, even when nothing else marks the boundary.
+        # Neither found, the path's own directory is the root — two
+        # files with no closer marker only "belong together" if they are
+        # literally the same file.
+        def package_root_for(path)
+          return path.to_s if path.nil?
+
+          dir = File.dirname(File.expand_path(path))
+          loop do
+            return "vendor:#{dir}" if File.basename(dir) == "vendor"
+            return dir if Dir.glob(File.join(dir, "*.gemspec")).any?
+
+            parent = File.dirname(dir)
+            return dir if parent == dir
+
+            dir = parent
+          end
+        end
+
         # A domain that declares a `process_manager` but whose
         # `saga_persistence` resolves to `NULL_SAGA_STORE` (no anchor
         # aggregate, a RemoteRuntime-shaped adapter, an adapter that