hecks 0.2.0 → 0.3.0

data/lib/hecks/runtime/refusal_wording.rb

@@ -0,0 +1,124 @@
+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 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

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

@@ -0,0 +1,70 @@
+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`).
+      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.
+        def saga_persistence(domain)
+          (@saga_persistence ||= {})[domain.to_s] ||= resolve_saga_persistence(domain.to_s)
+        end
+
+        # 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
+        # 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`.
+        def rehydrate_sagas!
+          @hecksagons.each_key do |domain|
+            saga_persistence(domain).each_saga do |process_manager, correlation, state, memory|
+              @saga_instances[process_manager][correlation] = { state: state, memory: memory }
+            end
+          end
+          self
+        end
+
+        private
+
+        def resolve_saga_persistence(domain)
+          anchor = hecksagon(domain) && bluebook(domain)&.aggregates&.first
+          return Ports::Persistence::NULL_SAGA_STORE unless anchor
+
+          bind = Ports::Persistence::BindingPolicy.resolve(self, domain, anchor)
+          return Ports::Persistence::NULL_SAGA_STORE if adapter_class(bind.adapter) <= Ports::Persistence::RemoteRuntime
+
+          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.
+          Ports::Persistence::NULL_SAGA_STORE
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,158 @@
+require_relative "../../bluebook/hexagon"
+
+module Hecks
+  module Runtime
+    class Registry
+      # The wiring gate: every bind names a declared aggregate, every
+      # adapter satisfies the verb its port declares, every world setting is
+      # a field the adapter admits, and the default adapter is usable at
+      # all. Included into Registry — `verify!` is what a boot calls after
+      # loading, and the smaller checks are also called piecemeal by the
+      # repository factory.
+      module Verification
+        def verify!
+          verify_default_adapter!
+
+          @hecksagons.each_value do |hexagon|
+            refuse_ungoverned_roles!(hexagon)
+
+            hexagon.binds.each do |bind|
+              # A domain-level default (§0) — `persisted_by "Heki"` bare,
+              # applying to whichever aggregates don't override it — names
+              # no aggregate of its own, so there's nothing to look up in
+              # the bluebook for THIS row specifically. Still validate its
+              # own adapter/verb shape (the same reason
+              # `verify_default_adapter!` checks the framework-wide
+              # default the same way, aggregate-less). Coverage of real
+              # aggregates that only resolve THROUGH this default comes
+              # from their own dispatch-time `BindingPolicy.resolve` —
+              # deliberately not required to be exhaustive here, the same
+              # leniency this method already extended to any aggregate
+              # left out of an explicit bind list entirely (real test
+              # fixtures bind only the aggregates they exercise).
+              if bind.aggregate.nil?
+                check_verb(bind)
+                next
+              end
+
+              aggregate = bluebook(hexagon.domain)&.aggregate(bind.aggregate_name)
+              raise WiringError, "#{bind.aggregate} is bound but not declared in the bluebook" unless aggregate
+
+              check_verb(bind)
+
+              repository(hexagon.domain, aggregate)
+            end
+          end
+          self
+        end
+
+        def verify_default_adapter!
+          name = Ports::Persistence::DEFAULT_ADAPTER
+
+          check_verb(
+            Bluebook::Bind.new(
+              aggregate: "(default)",
+              verb:      Ports::Persistence::VERB,
+              adapter:   name
+            )
+          )
+          adapter_class(name)
+          self
+        rescue WiringError => error
+          raise WiringError,
+                "the default persistence adapter (#{name}) is not usable, so an " \
+                "aggregate with no bind could not be given one: #{error.message}"
+        end
+
+        def check_verb(bind)
+          port = port_for(bind)
+          return if port.verb.to_s == bind.verb.to_s
+
+          raise WiringError,
+                "#{bind.adapter} implements the #{port.name} port (verb #{port.verb}) " \
+                "and cannot satisfy #{bind.verb}"
+        end
+
+        def check_settings(bind, settings)
+          adapter = @adapters[bind.adapter]
+          return unless adapter
+
+          declared = settings.keys - [:adapter]
+          unknown  = declared.reject { |field| adapter.declares?(field) }
+          return if unknown.empty?
+
+          raise WiringError,
+                "#{bind.adapter} does not declare #{unknown.map(&:inspect).join(', ')} — " \
+                "it declares #{adapter.all_fields.map(&:inspect).join(', ')}. " \
+                "Add the field to the adapter, or remove it from the world."
+        end
+
+        def port_for(bind)
+          adapter = @adapters[bind.adapter]
+          raise WiringError, "unknown adapter #{bind.adapter.inspect}" unless adapter
+
+          @ports[adapter.port] ||
+            raise(WiringError, "adapter #{bind.adapter} declares unknown port #{adapter.port.inspect}")
+        end
+
+        def adapter_class(name)
+          Adapters.const_get(name)
+        rescue NameError
+          raise WiringError, "no Ruby adapter implementation for #{name.inspect} " \
+                             "(expected Hecks::Adapters::#{name})"
+        end
+
+        private
+
+        # `role` IS REAL ACCESS CONTROL ONLY WHEN GOVERNANCE CAN CHECK IT
+        # AGAINST SOMETHING — a command that declares a role but whose
+        # domain never attaches Governance would leave that role forever
+        # 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
+        # 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
+        # `uses_framework "Governance"` would be refused there, even
+        # though `Registry#add_hecksagon` merges every block for a domain
+        # into ONE Hecksagon before anything ever dispatches against it.
+        # Checking the MERGED result once, here, after every file for
+        # this domain has loaded, is both more permissive (no need to
+        # repeat `uses_framework` in every file) and strictly more
+        # correct (a check against an incomplete, not-yet-merged
+        # hecksagon can never see the real final shape).
+        #
+        # GOVERNANCE ITSELF IS EXEMPT — it cannot `uses_framework` its own
+        # aggregates, and it IS the source of truth a role check runs
+        # against, the same self-reference `CommandRules::Authorization
+        # #governance_attached?` grants it at dispatch time.
+        def refuse_ungoverned_roles!(hexagon)
+          return if hexagon.domain == "Governance"
+          return if hexagon.framework_members.include?("Governance")
+
+          bluebook_ir = bluebook(hexagon.domain)
+          return unless bluebook_ir
+
+          offender = commands_in(bluebook_ir).find { |command| !command.role.to_s.empty? }
+          return unless offender
+
+          raise WiringError,
+                "#{offender.hecks_fqn} declares role #{offender.role.inspect}, but " \
+                "#{hexagon.domain}'s hecksagon never uses_framework \"Governance\" — role is only " \
+                "real access control once Governance is attached to check it against; without that " \
+                "it is silent decoration, the exact defect this refusal exists to catch"
+        end
+
+        # Every command this domain declares, an aggregate's own AND every
+        # entity nested inside one — the same reach `refuse_role_mismatch`
+        # itself needs at dispatch time, just walked ahead of time here.
+        def commands_in(bluebook_ir)
+          bluebook_ir.aggregates.flat_map { |aggregate| aggregate.commands + aggregate.entities.flat_map(&:commands) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/registry.rb

@@ -0,0 +1,218 @@
+require_relative "registry/verification"
+require_relative "registry/saga_persistence"
+
+module Hecks
+  module Runtime
+    class WiringError < StandardError; end
+
+    # The collections a boot gathers — bluebooks, hexagons, ports, adapters,
+    # worlds, the logs — and how a repository is resolved from them. The
+    # wiring gate lives in registry/verification.rb, saga persistence
+    # resolution in registry/saga_persistence.rb.
+    class Registry
+      include Verification
+      include SagaPersistence
+
+      attr_reader :root, :bluebooks, :hecksagons, :ports, :adapters, :worlds, :event_log,
+                  :reaction_log, :saga_log, :saga_instances, :translations, :saga_mutex,
+                  :saga_dispatch_log, :policy_dispatch_log
+
+      def initialize(root: nil)
+        @root         = root
+        @bluebooks    = {}
+        @hecksagons   = {}
+        @ports = {}
+        @adapters     = {}
+        @worlds       = {}
+        @translations = []
+        @event_log    = []
+        @reaction_log = []
+        @saga_log = []
+        # ADDITIVE, RUBY-ONLY — never merged into saga_log/reaction_log.
+        # rust/src/kernel/orchestrate.rs ports THOSE two arrays' exact
+        # shape byte-for-byte (spec/rust_conformance_spec.rb's own
+        # equality check) — a landmine found by reading that spec before
+        # touching anything, not by hitting it. These carry the raw
+        # inputs a dispatch's own argument binding was resolved from
+        # (SagaInterpreter#deliver_saga_dispatch / PolicyInterpreter#
+        # trigger_args), for Properties.dispatch_binding_fidelity's own
+        # independent re-derivation — a fact neither existing log
+        # records at all, so there is nothing here for Rust to have
+        # matched or drifted from.
+        @saga_dispatch_log   = []
+        @policy_dispatch_log = []
+        @saga_instances = Hash.new { |h, k| h[k] = {} }
+        # GUARDS `saga_instances`' OWN mutation+checkpoint sequence
+        # (`SagaInterpreter`'s 4 write points, §7) — the same shape of
+        # hazard this codebase's own prior audit already flagged for
+        # `@reaction_depth`, a thread-shared dispatcher ivar with no
+        # lock, made meaningfully easier to hit once a persistence write
+        # sits in the same critical section. Held across the in-memory
+        # mutation AND the checkpoint write together, never across a
+        # saga's own dispatch cascade — see `SagaInterpreter#advance_saga`'s
+        # own comment for why that distinction matters (non-reentrant
+        # Mutex, recursive re-entry is real).
+        @saga_mutex = Mutex.new
+        @repositories = {}
+        @projection_repositories = {}
+        @bluebook_builders = {}
+      end
+
+      # THE BUILDER STAYS OPEN FOR THE LIFE OF THIS REGISTRY, keyed by chapter
+      # name — see the comment on `BluebookBuilder.build`. A chapter split across
+      # several files (`language/bluebook/*.bluebook`, all `Hecks.bluebook "Bluebook"`)
+      # needs its declarations to accumulate into ONE builder rather than each
+      # file minting its own and silently discarding the one before.
+      def bluebook_builder(name)
+        @bluebook_builders[name.to_s] ||= yield
+      end
+
+      def add_bluebook(item) = @bluebooks[item.name] = item
+
+      # MERGED, NOT REPLACED — RECOVERED, not new (see Runtime::Loader
+      # .boot's own comment for the provenance). A domain's hecksagon can
+      # now load in more than one block for the same domain (base file
+      # plus an `environments/<name>.hecksagon` overlay), and the second
+      # block should ADD to what the first declared, not silently
+      # discard it.
+      def add_hecksagon(item)
+        existing = @hecksagons[item.domain]
+        @hecksagons[item.domain] = existing ? merge_hecksagons(existing, item) : item
+      end
+
+      def add_port(item) = @ports[item.name] = item
+      def add_adapter(item) = @adapters[item.name] = item
+
+      # MERGED, NOT REPLACED — the same generalization for `World` that
+      # `add_hecksagon` above recovers for `Hecksagon`: an
+      # `environments/<name>.world` overlay (or a host-owned tenancy
+      # overlay world, same mechanism) can now add or override settings
+      # for a domain a base `.world` file already declared, without
+      # restating everything the base file said. Settings merge shallow,
+      # keyed exactly the way WorldBuilder already stores them (both the
+      # bare verb key and the `"verb:adapter"` qualified key point at the
+      # same resolved hash) — an overlay's key wins over the base's same
+      # key; a key only the base declares survives untouched.
+      def add_world(item)
+        existing = @worlds[item.domain]
+        @worlds[item.domain] = existing ? merge_worlds(existing, item) : item
+      end
+
+      def add_translation(item) = @translations << item
+
+      # {domain name => era ordinal} as resolved by the boot-time era
+      # gate. A lineage adapter writes into ITS OWN era's partition —
+      # which, for an old checkout booting a held-but-superseded shape,
+      # is not the newest one.
+      def resolved_eras = @resolved_eras ||= {}
+
+      def bluebook(name)  = @bluebooks[name.to_s]
+      def hecksagon(name) = @hecksagons[name.to_s]
+      def world(name)     = @worlds[name.to_s]
+
+      def verbs = @bluebooks.values.flat_map(&:verbs).sort
+
+      def repository(domain, aggregate)
+        @repositories[[domain.to_s, aggregate.hecks_name]] ||= Ports::Persistence.repository(self, domain, aggregate)
+      end
+
+      # EVERYTHING A DISPATCH WROTE, CLEARED; NOTHING A BOOT DECLARED,
+      # TOUCHED. Bluebooks, hecksagons, ports, adapters, worlds and the
+      # resolved eras are what loading the files produced and stay as
+      # they are; the logs, the saga instances and the repositories are
+      # what running commands against them produced, and go back to
+      # exactly what a fresh boot of the same files hands out. Dropping
+      # the repositories (rather than emptying each) is deliberate: a
+      # fresh boot's own repositories are new adapter instances too, so
+      # a Memory adapter starts empty and a durable one sees whatever
+      # it persisted — the same reading either way. Sagas rehydrate off
+      # that store again, the way `Loader.boot_files` does after
+      # `verify!`.
+      #
+      # What this is for: a test runner that used to boot a runtime per
+      # test to get isolation (`Behaviors::Expectations.run_one`) — ~2s a
+      # boot, 76 chess behaviours = two and a half minutes of booting the
+      # same two files — can now boot once and reset between tests.
+      def reset_runtime_state!
+        @event_log.clear
+        @reaction_log.clear
+        @saga_log.clear
+        @saga_dispatch_log.clear
+        @policy_dispatch_log.clear
+        @saga_instances.clear
+        @repositories = {}
+        @projection_repositories = {}
+        rehydrate_sagas!
+        self
+      end
+
+      def capability_graph
+        @capability_graph ||= CapabilityGraph.new(self)
+      end
+
+      def read_repository(domain, aggregate)
+        key = [domain.to_s, aggregate.hecks_name]
+        binding = Ports::Projection.binds_for(self, domain, aggregate).first
+        return repository(domain, aggregate) unless binding
+
+        projection = (@projection_repositories[key] ||= begin
+          projection = Ports::Persistence::RepositoryFactory.build(self, domain, aggregate, binding,
+                                                                   recover: true, settings_verb: Ports::Projection::VERB)
+          projection
+        end)
+        authoritative = repository(domain, aggregate)
+        projection_current?(projection, authoritative) ? projection : authoritative
+      end
+
+      def projection_current?(projection, authoritative)
+        projected_entries = projection.entries
+        source_entries = authoritative.entries
+        return false unless projected_entries.length == source_entries.length
+        return false unless projected_entries.zip(source_entries).all? do |projected, source|
+          projected.operation == source.operation && projected.id == source.id && projected.state == source.state
+        end
+
+        projected_rows = projection.all.map(&:to_h).sort_by { |row| row.fetch(:id).to_s }
+        source_rows = authoritative.all.map(&:to_h).sort_by { |row| row.fetch(:id).to_s }
+        projected_rows == source_rows
+      rescue StandardError
+        false
+      end
+
+      # RECOVERED — see `add_hecksagon`'s own comment for provenance.
+      # Concatenates every list-shaped fact; `binds` in particular is
+      # additive because an overlay REBINDING an aggregate (a new
+      # `persisted_by` for the same aggregate/verb) is meant to shadow
+      # the base's own bind at resolution time, not erase it outright —
+      # `Ports::Persistence::BindingPolicy.resolve`'s own "exactly one
+      # authoritative bind" check is what actually catches a genuine
+      # double-bind; this merge only concatenates, it does not itself
+      # decide which of two binds for the same aggregate wins.
+      def merge_hecksagons(a, b)
+        Bluebook::Hecksagon.new(
+          domain:             a.domain,
+          binds:              a.binds + b.binds,
+          subscriptions:      a.subscriptions + b.subscriptions,
+          framework_members:  a.framework_members + b.framework_members,
+          vendored_bluebooks: a.vendored_bluebooks + b.vendored_bluebooks
+        )
+      end
+
+      # RECOVERED AND GENERALIZED — see `add_world`'s own comment. `realm`/
+      # `latest` are scalars, so the overlay's value wins when present,
+      # else the base's survives; `settings` is a shallow merge keyed by
+      # verb (and `"verb:adapter"`) — an overlay entry for a key the base
+      # also declares REPLACES that key's whole resolved hash (the same
+      # all-or-nothing shape `WorldBuilder#method_missing` already builds
+      # each entry as), it does not deep-merge field by field within it.
+      def merge_worlds(a, b)
+        Bluebook::World.new(
+          domain:   a.domain,
+          realm:    b.realm || a.realm,
+          latest:   b.latest || a.latest,
+          settings: a.settings.merge(b.settings)
+        )
+      end
+    end
+  end
+end