hecks 1.3.0 → 1.5.0

data/lib/hecks/ports/persistence/codec_boundary.rb

@@ -0,0 +1,178 @@
+require_relative "state_codec"
+require_relative "../../runtime/errors"
+
+module Hecks
+  module Ports
+    module Persistence
+      # No adapter can build an `Instance` from undecoded state (Phase 2,
+      # Track A, PR A3). Routing every adapter through `StateCodec` is a
+      # convention until something refuses the bypass; this is that
+      # something, and it is installed by `RepositoryFactory.build` — the
+      # one place every runtime repository is made — so no adapter can opt
+      # out of it.
+      #
+      # ## The mechanism, two halves
+      #
+      # 1. `guard!(adapter)` extends the adapter object (not its class,
+      #    not a proxy — `is_a?`, `class`, and `===` stay the adapter's
+      #    own) with a module that wraps every public method the adapter's
+      #    class defines. Each call runs inside the boundary: a
+      #    thread-local flag, re-entrant, restored on the way out. A block
+      #    the caller passes (`transaction`, `with_write_lock`,
+      #    `each_saga`) runs outside it — that block is the dispatch
+      #    itself (hydrate, entity views, mutation), not adapter code.
+      #    Reaching the adapter through `repository.adapter` (the query
+      #    port, saga persistence, `bin/heki_compact`) is guarded all the
+      #    same: the wrapper is on the object.
+      #
+      # 2. `Runtime::Instance#initialize` asks `check_state!` whenever it
+      #    is handed `state:`. Outside the boundary that is a no-op; inside
+      #    it, state `StateCodec.decoded?` rejects refuses by name. An
+      #    `entries` answer is checked the same way on its way out, since a
+      #    journal `Entry` is not an `Instance`.
+      #
+      # ## Checked, not silently decoded
+      #
+      # An adapter that forgets the codec is a bug in that adapter, and
+      # decoding for it here would hide the forgetting. Hydration does not
+      # respell keys either (A4) — `Value.hydrate` refuses a non-Symbol
+      # top-level key everywhere — so this boundary's deep check and
+      # hydration's shallow one agree.
+      module CodecBoundary
+        KEY = :hecks_persistence_codec_boundary
+
+        module_function
+
+        # Extends an adapter object so every public method its class defines runs inside the
+        # boundary; guarding an adapter twice wraps it once.
+        #
+        # @param adapter [Object] a driven persistence adapter instance
+        # @return [Object] the same adapter object, now including `Guarded`
+        def guard!(adapter)
+          adapter.extend(wrapper_for(adapter.class)) unless adapter.singleton_class.include?(Guarded)
+          adapter
+        end
+
+        # Reports whether the current thread is executing inside a guarded adapter call.
+        #
+        # @return [Boolean] true between entering a guarded adapter method and yielding to the
+        #   caller's block or returning
+        def active? = Thread.current[KEY] == true
+
+        # Runs the block with the boundary switched on for this thread, restoring the earlier
+        # setting afterwards.
+        #
+        # @yield adapter code whose `Instance` construction is to be checked
+        # @return [Object] the block's value
+        def within(&) = with_flag(true, &)
+
+        # Runs the block with the boundary switched off for this thread, restoring the earlier
+        # setting afterwards.
+        #
+        # @yield caller code, such as a dispatch running inside the adapter's transaction
+        # @return [Object] the block's value
+        def outside(&) = with_flag(false, &)
+
+        # Refuses state an adapter is about to build an `Instance` from unless it is decoded;
+        # outside the boundary it checks nothing.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct the state
+        #   belongs to
+        # @param state [Hash, Runtime::Value] the state handed to `Runtime::Instance.new`
+        # @return [nil] when the boundary is inactive or the state is decoded
+        # @raise [Runtime::WiringError] if the boundary is active and
+        #   `StateCodec.decoded?` rejects the state
+        def check_state!(aggregate, state)
+          return unless active?
+          return if StateCodec.decoded?(aggregate, state)
+
+          raise Runtime::WiringError,
+                "a persistence adapter built a #{aggregate.name} record from undecoded state " \
+                "(#{state.keys.inspect}) — decode stored state through " \
+                "Hecks::Ports::Persistence::StateCodec.decode before handing it to Runtime::Instance"
+        end
+
+        # Refuses a guarded adapter's `entries` answer if any entry's state is undecoded.
+        #
+        # @param adapter [Object] the guarded adapter, asked for its `aggregate` and class name
+        # @param entries [Array<Persistence::Entry>, Object] what the adapter's `entries`
+        #   returned; anything that is not an Array passes through unchecked
+        # @return [Array<Persistence::Entry>, Object] `entries` itself
+        # @raise [Runtime::WiringError] if an `Entry` in the Array carries state
+        #   `StateCodec.decoded?` rejects
+        def check_entries!(adapter, entries)
+          return entries unless entries.is_a?(Array)
+
+          entries.each do |entry|
+            next unless entry.is_a?(Entry) && !StateCodec.decoded?(adapter.aggregate, entry.state)
+
+            raise Runtime::WiringError,
+                  "#{adapter.class} answered a #{adapter.aggregate.name} journal entry #{entry.id.inspect} with " \
+                  "undecoded state — decode it through Hecks::Ports::Persistence::StateCodec.decode"
+          end
+          entries
+        end
+
+        # Sets the thread-local boundary flag for the length of the block, which is what makes
+        # the boundary re-entrant.
+        #
+        # @param value [Boolean] true to switch the boundary on, false to switch it off
+        # @yield the code to run under that setting
+        # @return [Object] the block's value; the earlier flag is restored even when the
+        #   block raises
+        def with_flag(value)
+          previous = Thread.current[KEY]
+          Thread.current[KEY] = value
+          yield
+        ensure
+          Thread.current[KEY] = previous
+        end
+
+        # Marks a guarded adapter so a second `guard!` (a projection and an
+        # authoritative repository built over one object) never wraps twice.
+        module Guarded; end
+
+        # Filled lazily under `WRAPPERS_LOCK`, one entry per adapter class —
+        # a cache, deliberately mutable.
+        WRAPPERS = {} # rubocop:disable Style/MutableConstant
+        WRAPPERS_LOCK = Mutex.new
+
+        # Builds, or fetches from the cache, the module that guards one adapter class.
+        #
+        # One wrapper module per adapter class, built once: every public
+        # instance method the class (and its ancestors below Object)
+        # defines, each forwarding to `super` inside the boundary.
+        #
+        # @param klass [Class] the adapter's class
+        # @return [Module] an anonymous module including `Guarded`, meant to be `extend`ed onto
+        #   instances of `klass`
+        def wrapper_for(klass)
+          WRAPPERS_LOCK.synchronize do
+            WRAPPERS[klass] ||= Module.new do
+              include Guarded
+
+              (klass.public_instance_methods - Object.public_instance_methods).each do |name|
+                define_method(name) do |*args, **kwargs, &block|
+                  result = CodecBoundary.within { super(*args, **kwargs, &CodecBoundary.outside_block(block)) }
+                  name == :entries ? CodecBoundary.check_entries!(self, result) : result
+                end
+              end
+            end
+          end
+        end
+
+        # Wraps the caller's own block so it runs outside the boundary
+        # whenever the adapter yields to it.
+        #
+        # @param block [Proc, nil] the block the caller passed to the adapter method
+        # @return [Proc, nil] a proc forwarding its arguments to `block` under `outside`; nil
+        #   when no block was given
+        def outside_block(block)
+          return nil unless block
+
+          proc { |*yielded, **yielded_kwargs, &inner| outside { block.call(*yielded, **yielded_kwargs, &inner) } }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/execution.rb

@@ -10,6 +10,10 @@ module Hecks
         # `Runtime::StaleWrite` (runtime/errors.rb) and `AppendOnly#save`.
         STATUSES = %i[inserted replaced updated conflicted missing saved stale].freeze
 
+        # @param status [Symbol, String] one of `STATUSES`; stored as a Symbol
+        # @param instance [Runtime::Instance, Object, nil] the record the write concerned, as
+        #   the repository reports it; nil when there is none
+        # @raise [ArgumentError] if `status` is not one of `STATUSES`
         def initialize(status:, instance: nil)
           normalized = status.to_sym
           raise ArgumentError, "unknown persistence outcome #{status.inspect}" unless STATUSES.include?(normalized)

data/lib/hecks/ports/persistence/null_saga_store.rb

@@ -1,7 +1,7 @@
 module Hecks
   module Ports
     module Persistence
-      # THE NO-OP SAGA STORE — what `Registry#saga_persistence` hands
+      # **The no-op saga store** — what `Registry#saga_persistence` hands
       # back for a domain whose resolved adapter doesn't implement the
       # (optional) saga-persistence capability: Memory, deliberately
       # (sagas stay in-memory-only, exactly as they always have), and
@@ -14,8 +14,19 @@ module Hecks
       # `Ports::Persistence::AppendOnly` already gives adapters that
       # don't implement `reset!`/`events`/`record_event`.
       class NullSagaStore
+        # Accepts and discards a saga checkpoint, whatever keywords it carries.
+        #
+        # @return [nil] always; nothing is stored
         def save_saga(**) = nil
+
+        # Accepts and ignores a request to forget a saga.
+        #
+        # @return [nil] always; there is nothing to delete
         def delete_saga(**) = nil
+
+        # Yields nothing, because no saga is ever stored here.
+        #
+        # @return [nil] always; a block, if given, is never called
         def each_saga(*) = nil
       end
 

data/lib/hecks/ports/persistence/plugin.rb

@@ -8,17 +8,17 @@ module Hecks
       # a plugin makes itself known as a side effect of being `require`d, the
       # same way an adapter's own `.rb` file already registers itself
       # (`Runtime::Registry#add_adapter`) rather than core listing adapter
-      # names anywhere. `register_plugin` is the ENTIRE contract a plugin
+      # names anywhere. `register_plugin` is the entire contract a plugin
       # must satisfy: anything responding to `contribute_boot_gates(registry,
       # gates)` (a no-op is a valid implementation).
       #
-      # This is deliberately NOT the same registry `Hecks::Projector` uses
+      # This is deliberately not the same registry `Hecks::Projector` uses
       # (ADR 0027) or `Runtime::BootGates` (ADR 0031) — each of those is
       # scoped to its own seam (IR-in/artifact-out; per-boot phased gates).
       # A shared base is deferred until a third registry actually wants one.
       #
-      # NAME-KEYED, PROCESS-WIDE, NOT PER-BOOT — unlike `BootGates` (one
-      # instance per `Loader.boot` call, because gate REGISTRATION is
+      # **Name-keyed, process-wide, not per-boot** — unlike `BootGates` (one
+      # instance per `Loader.boot` call, because gate registration is
       # capability-conditional per registry), a persistence plugin is either
       # `require`d into this process or it isn't; there is no "this boot's
       # registry doesn't need it" case to isolate against, so a plain
@@ -27,18 +27,36 @@ module Hecks
         @plugins = {}
 
         class << self
+          # Adds a plugin under a name, replacing any plugin already registered under it.
+          #
+          # @param name [Symbol, String] the plugin's name, such as `:era`; stored as a Symbol
+          # @param plugin [Object] anything responding to
+          #   `contribute_boot_gates(registry, gates)`
+          # @return [Object] the plugin just registered
           def register(name, plugin)
             @plugins[name.to_sym] = plugin
           end
 
+          # Reports whether a plugin of that name has been required into this process.
+          #
+          # @param name [Symbol, String] the plugin's name
+          # @return [Boolean] true when a plugin is registered under `name`
           def registered?(name)
             @plugins.key?(name.to_sym)
           end
 
+          # Yields every registered plugin, in registration order.
+          #
+          # @yieldparam plugin [Object] a registered plugin
+          # @return [Hash{Symbol => Object}, Enumerator] the plugin table when a block is
+          #   given, otherwise an Enumerator over the plugins
           def each(&)
             @plugins.each_value(&)
           end
 
+          # Reports whether any persistence plugin is loaded at all.
+          #
+          # @return [Boolean] true when at least one plugin is registered
           def any? = !@plugins.empty?
         end
       end
@@ -48,9 +66,29 @@ module Hecks
       # directly for a plugin's own file to call at require-time.
       module_function
 
+      # Registers a persistence plugin; a plugin's own file calls this when it is required.
+      #
+      # @param name [Symbol, String] the plugin's name, such as `:era`
+      # @param plugin [Object] anything responding to `contribute_boot_gates(registry, gates)`
+      # @return [Object] the plugin just registered
       def register_plugin(name, plugin) = Plugin.register(name, plugin)
+
+      # Reports whether the named persistence plugin is loaded in this process.
+      #
+      # @param name [Symbol, String] the plugin's name
+      # @return [Boolean] true when a plugin is registered under `name`
       def plugin?(name) = Plugin.registered?(name)
+
+      # Yields every loaded persistence plugin, in registration order.
+      #
+      # @yieldparam plugin [Object] a registered plugin
+      # @return [Hash{Symbol => Object}, Enumerator] the plugin table when a block is given,
+      #   otherwise an Enumerator over the plugins
       def each_plugin(&) = Plugin.each(&)
+
+      # Reports whether any persistence plugin is loaded in this process.
+      #
+      # @return [Boolean] true when at least one plugin is registered
       def plugins_loaded? = Plugin.any?
     end
   end

data/lib/hecks/ports/persistence/plugins/era/era_check.rb

@@ -7,7 +7,7 @@ require_relative "../../../../runtime/registry"
 
 module Hecks
   module Runtime
-    # The boot-time era gate, run for the adapters that HAVE eras — the
+    # The boot-time era gate, run for the adapters that have eras — the
     # lineage-capable ones. An era is a fact about stored data that some
     # adapter can carry across a shape change; an adapter that cannot
     # translate has no era to hold, and holding one for it would record
@@ -15,7 +15,7 @@ module Hecks
     #
     # The whole domain is handed to the capable adapter's own era check
     # (Postgres: hold, recognize, mint, or refuse toward the scaffold),
-    # which keeps its era facts as rows BESIDE its data. That
+    # which keeps its era facts as rows beside its data. That
     # co-location is load-bearing — a watermark only means something
     # against the journal it was cut from, and an approval recorded
     # anywhere but the reviewed database binds to nothing.
@@ -31,50 +31,84 @@ module Hecks
     module EraCheck
       module_function
 
-      # EACH BLUEBOOK'S OWN SOURCE, not one file read once and reused
+      # Runs both halves of the era gate over every bluebook in a registry.
+      #
+      # Each bluebook's own source, not one file read once and reused
       # for every bluebook in the registry — true as long as a domain
       # directory only ever held exactly one, and silently wrong the
       # moment `uses_framework` made a second, differently-sourced
       # bluebook (Governance, Identity — `lib/hecks/framework/bluebook/`,
       # not the domain's own directory) share a boot with the first.
       # Caught the hard way: three domains booted together, one real
-      # source text (the domain's own), and every OTHER domain's era-1
-      # held THAT text under its own name — a shadow-parse of it later
+      # source text (the domain's own), and every other domain's era-1
+      # held that text under its own name — a shadow-parse of it later
       # reconstructs a completely different shape, and every boot after
       # the first refuses toward a scaffold that was never the real
       # drift.
+      #
+      # @param registry [Runtime::Registry] the registry being booted
+      # @param directory [String] path of the domain's own bluebook directory, searched for
+      #   each bluebook's `.bluebook` source
+      # @return [void]
+      # @raise [Runtime::WiringError] if a compute rule is bound to an adapter that is not
+      #   lineage-capable, a persistence binding cannot be resolved, a lineage-bound bluebook
+      #   has no findable source, or the adapter's own `era_check!` refuses the boot
       def check!(registry, directory)
         check_compute_rules_for_registry!(registry)
         check_lineage!(registry, directory)
       end
 
+      # Refuses the boot when any bluebook's compute rule is bound away from Postgres.
+      #
       # The domain-agnostic half, split out for ADR 0031's boot-gate
       # registry: a compute rule requires Postgres whatever adapter is
-      # actually bound, so this must run for EVERY registry, the same way
+      # actually bound, so this must run for every registry, the same way
       # `registry.verify!` does — it is not conditional on any adapter
       # being lineage-capable, and must never be skipped by
       # `check_lineage!`'s own capability gate below.
+      #
+      # @param registry [Runtime::Registry] the registry whose bluebooks are all checked
+      # @return [void]
+      # @raise [Runtime::WiringError] if an aggregate carrying a compute rule is bound to an
+      #   adapter that is not lineage-capable, or its persistence binding cannot be resolved
       def check_compute_rules_for_registry!(registry)
         registry.bluebooks.each_value { |bluebook| check_compute_rules!(registry, bluebook) }
       end
 
+      # Hands every bluebook, with its own source text, to its adapter's era check.
+      #
       # The capability-gated half — ADR 0031's registered `:era_check`
       # gate. Registration is conditional on `lineage_capable_registry?`;
       # `check_bluebook!` below still carries its own per-bluebook
       # `lineage_capable?` return-early, unchanged, for a registry with a
       # mix of lineage-capable and plain-adapter bluebooks.
+      #
+      # @param registry [Runtime::Registry] the registry being booted
+      # @param directory [String] path of the domain's own bluebook directory
+      # @return [void]
+      # @raise [Runtime::WiringError] if a persistence binding cannot be resolved, a
+      #   lineage-bound bluebook has no findable source, or the adapter's own `era_check!`
+      #   refuses the boot
       def check_lineage!(registry, directory)
         registry.bluebooks.each_value do |bluebook|
-          check_bluebook!(registry, bluebook, source_text_for(bluebook, directory), directory: directory)
+          check_bluebook!(registry, bluebook, source_text_for(bluebook, directory, registry: registry), directory: directory)
         end
       end
 
+      # Decides whether a registry binds anything that carries eras.
+      #
       # The `:era_check` gate's own registration predicate: true iff at
       # least one bluebook's own anchor (first) aggregate resolves to a
       # lineage-capable adapter — mirrors `check_bluebook!`'s existing
       # per-bluebook anchor check, just asked once, up front, of the
       # whole registry, so a registry with nothing lineage-capable bound
       # anywhere never registers the gate at all.
+      #
+      # @param registry [Runtime::Registry] the registry whose bluebooks are asked
+      # @return [Boolean] true when some bluebook's first aggregate is bound to a
+      #   lineage-capable adapter; false for an empty registry or one with no such binding
+      # @raise [Runtime::WiringError] if a first aggregate's persistence binding is missing,
+      #   ambiguous, or carries an unsupported role
       def lineage_capable_registry?(registry)
         registry.bluebooks.each_value.any? do |bluebook|
           first = bluebook.aggregates.first
@@ -84,38 +118,170 @@ module Hecks
         end
       end
 
+      # Reads the source text one bluebook was declared in, wherever that source lives.
+      #
       # The domain's own directory first, matched by name — a real app's
       # directory may hold more than one file once `uses_framework`
       # exists, so ".first" alone can no longer be trusted, the exact
       # way it silently wasn't the day this was found: three domains
       # booted together, one real source text read once (the domain's
-      # own, ".first"'d), and every OTHER domain's era-1 held THAT text
+      # own, ".first"'d), and every other domain's era-1 held that text
       # under its own name — a later shadow-parse of it reconstructs a
       # completely different shape, and every boot after the first
       # refuses toward a scaffold that was never the real drift.
       #
-      # A single-file directory whose one file names something ELSE
+      # A single-file directory whose one file names something else
       # falls back to it anyway (a fixture may legitimately name its
-      # file differently from the `Hecks.bluebook` it declares) — UNLESS
-      # this bluebook is a known framework member, in which case that
-      # one file is certainly some OTHER domain's, not this one's, and
-      # the framework registry is asked instead — the only other place a
-      # bluebook in this registry could have come from, per
-      # `uses_framework`.
-      def source_text_for(bluebook, directory)
+      # file differently from the `Hecks.bluebook` it declares) — unless
+      # this bluebook is a known framework member or a vendored
+      # embryonaut bluebook (see `vendored_source_for` below), in which
+      # case that one file is certainly some other domain's, not this
+      # one's, and the real registry is asked instead — the only other
+      # two places a bluebook in this registry could have come from, per
+      # `uses_framework` and `uses_embryonaut_bluebook`.
+      #
+      # The bug this guards against, found live: `Framework.members` was
+      # the only exclusion checked here, so a domain attaching a
+      # vendored bluebook instead (`uses_embryonaut_bluebook`, which has
+      # no equivalent registry — see embryonaut_bluebook.rb's own
+      # header) fell straight through the single-file fallback: a
+      # directory holding exactly one `.bluebook` file (the target
+      # domain's own) handed that same text back for the vendored
+      # bluebook's era check too. PostgresEra minted era 1 for the
+      # vendored domain with the target's own source stamped as its
+      # `held_text` — the label computed from it, too — so the very
+      # next boot re-derived the vendored domain's real shape, found it
+      # didn't match what got (wrongly) stored, and refused to boot
+      # toward a scaffold for drift that never actually happened.
+      # `registry:` is what lets this check the one thing
+      # `Framework.members` cannot: whether some hecksagon in this
+      # registry declared `uses_embryonaut_bluebook` for this exact
+      # bluebook name, the same way `EmbryonautBluebook.load!` itself
+      # already resolves the vendored package's own directory.
+      #
+      # @param bluebook [Bluebook::Chapter] the bluebook whose source is wanted
+      # @param directory [String] path of the domain's own bluebook directory
+      # @param registry [Runtime::Registry, nil] the registry asked whether some hecksagon
+      #   vendored this bluebook; nil skips the vendored lookup
+      # @return [String, nil] the UTF-8 text of every matching file joined with `"\n"`; nil
+      #   when no source file could be found
+      def source_text_for(bluebook, directory, registry: nil)
         domain_files = Dir[File.join(directory, "*.bluebook")]
-        own = domain_files.select do |path|
-          File.foreach(path, encoding: "UTF-8").any? do |line|
-            line.match?(/\A\s*Hecks\.bluebook\s+#{Regexp.escape(bluebook.name.inspect)}/)
-          end
-        end
-        own = domain_files if own.empty? && domain_files.size == 1 && !Framework.members.key?(bluebook.name)
-        own = [Framework.members[bluebook.name]].compact if own.empty?
+        own = domain_files.select { |path| declares_bluebook?(path, bluebook.name) }
+        own = fallback_source_files(bluebook, directory, domain_files, registry) if own.empty?
         return if own.empty?
 
         own.map { |path| File.read(path, encoding: "UTF-8") }.join("\n")
       end
 
+      # Scans a file for a `Hecks.bluebook "<name>"` line opening the named bluebook.
+      #
+      # @param path [String] path of the `.bluebook` file to scan, read as UTF-8
+      # @param bluebook_name [String] the declared bluebook name, matched in its `inspect`
+      #   (double-quoted) spelling
+      # @return [Boolean] true when some line, after leading whitespace, starts with
+      #   `Hecks.bluebook` followed by that quoted name
+      def declares_bluebook?(path, bluebook_name)
+        File.foreach(path, encoding: "UTF-8").any? do |line|
+          line.match?(/\A\s*Hecks\.bluebook\s+#{Regexp.escape(bluebook_name.inspect)}/)
+        end
+      end
+
+      # Picks the files to read for a bluebook no file in the domain directory declares.
+      #
+      # Only reached once nothing in the domain's own directory actually
+      # declares this bluebook by name. Three remaining sources, in
+      # order: a genuinely single-file domain directory whose one file
+      # just happens to name something else (but only when this
+      # bluebook isn't already known to come from somewhere else
+      # entirely — the exact guard the bug below was missing half of);
+      # a framework member; a vendored embryonaut bluebook.
+      #
+      # @param bluebook [Bluebook::Chapter] the bluebook whose source is wanted
+      # @param directory [String] path of the domain's own bluebook directory
+      # @param domain_files [Array<String>] paths of every `.bluebook` file in `directory`
+      # @param registry [Runtime::Registry, nil] the registry asked for a vendored name; nil
+      #   skips the vendored lookup
+      # @return [Array<String>] file paths to read, in load order; `[]` when the bluebook
+      #   comes from none of the three sources
+      def fallback_source_files(bluebook, directory, domain_files, registry)
+        vendored_name = registry && vendored_bluebook_name_for(registry, bluebook.name)
+        framework_path = Framework.members[bluebook.name]
+
+        if domain_files.size == 1 && !framework_path && !vendored_name
+          domain_files
+        elsif framework_path
+          [framework_path]
+        elsif vendored_name
+          vendored_source_for(directory, vendored_name)
+        else
+          []
+        end
+      end
+
+      # Recovers the vendored package name behind a bluebook, if some hecksagon vendored it.
+      #
+      # The name `uses_embryonaut_bluebook` was actually called with —
+      # recovered from whichever hecksagon in this registry recorded it
+      # (`HecksagonBuilder#uses_embryonaut_bluebook`'s own
+      # `@vendored_bluebooks`), matched the same way
+      # `EmbryonautBluebook.load!` itself decides idempotency: the
+      # vendored name Pascal-cases to this bluebook's own declared name.
+      # Nil for an ordinary bluebook nothing ever vendored.
+      #
+      # @param registry [Runtime::Registry] the registry whose hecksagons are searched
+      # @param bluebook_name [String] the bluebook's declared Pascal-case name
+      # @return [String, nil] the package name as written in `uses_embryonaut_bluebook`; nil
+      #   when no hecksagon vendored a package whose name Pascal-cases to `bluebook_name`
+      def vendored_bluebook_name_for(registry, bluebook_name)
+        registry.hecksagons.each_value do |hecksagon|
+          match = hecksagon.vendored_bluebooks.find { |name| Naming.pascal(name) == bluebook_name }
+          return match if match
+        end
+        nil
+      end
+
+      # Lists the `.bluebook` files a vendored embryonaut package ships.
+      #
+      # The same path `EmbryonautBluebook.load!` itself resolves from —
+      # `<registry.root>/vendor/embryonaut_bluebooks/<name>/bluebook/`,
+      # rebuilt here from `directory` (the domain's own bluebook
+      # directory, always `registry.root`'s immediate child — see
+      # `Runtime::Loader.boot`) rather than threading `registry.root`
+      # through as a second parameter. Every `.bluebook` file the
+      # package ships, in the same `Dir.glob` order actually loaded at
+      # boot time — order matters here because this text is later
+      # re-parsed whole (`EraCheck::shadow`) to reconstruct the shape a
+      # held era claims, and that reconstruction must see the files in
+      # the order that actually built the live shape.
+      #
+      # @param directory [String] path of the domain's own bluebook directory, whose parent
+      #   holds `vendor/embryonaut_bluebooks`
+      # @param name [String] the vendored package name, as `vendored_bluebook_name_for`
+      #   returns it
+      # @return [Array<String>] paths of the package's `.bluebook` files in `Dir.glob` order;
+      #   `[]` when the package directory is missing or empty
+      def vendored_source_for(directory, name)
+        dir = File.join(File.dirname(directory), "vendor", "embryonaut_bluebooks", name, "bluebook")
+        Dir.glob(File.join(dir, "*.bluebook"))
+      end
+
+      # Hands one bluebook to its adapter's `era_check!`, when that adapter carries eras.
+      #
+      # The bluebook's first aggregate is the anchor: its binding alone decides
+      # which adapter is asked, and a bluebook with no aggregates, or one bound
+      # to an adapter that is not lineage-capable, is skipped without a word.
+      #
+      # @param registry [Runtime::Registry] the registry being booted
+      # @param bluebook [Bluebook::Chapter] the bluebook to check
+      # @param current_text [String, nil] the bluebook's source, as `source_text_for` found
+      #   it; nil means no source file was found
+      # @param directory [String, nil] the domain's bluebook directory, named in the
+      #   missing-source refusal and passed through to the adapter
+      # @return [void]
+      # @raise [Runtime::WiringError] if the first aggregate's binding cannot be resolved,
+      #   `current_text` is nil for a lineage-bound bluebook, or the adapter's `era_check!`
+      #   refuses the boot
       def check_bluebook!(registry, bluebook, current_text, directory: nil)
         first = bluebook.aggregates.first
         return unless first
@@ -136,10 +302,19 @@ module Hecks
         )
       end
 
-      # The per-rule capability gate — NOT an era fact, and so it
+      # Refuses the boot when one bluebook's compute rule is bound away from Postgres.
+      #
+      # The per-rule capability gate — not an era fact, and so it
       # survives on every adapter: a compute rule's SQL is its only
       # implementation, so an aggregate carrying one cannot boot
       # anywhere but Postgres, whatever any shape comparison would say.
+      #
+      # @param registry [Runtime::Registry] the registry holding the declared translations
+      #   and the aggregate's bindings
+      # @param bluebook [Bluebook::Chapter] the bluebook whose aggregates are checked
+      # @return [void]
+      # @raise [Runtime::WiringError] if an aggregate carrying a compute rule is bound to an
+      #   adapter that is not lineage-capable, or its persistence binding cannot be resolved
       def check_compute_rules!(registry, bluebook)
         bluebook.aggregates.each do |aggregate|
           lineage = Ports::Persistence::Lineage.for(registry, bluebook.name, aggregate)
@@ -152,14 +327,32 @@ module Hecks
         end
       end
 
+      # Names the adapter an aggregate's authoritative persistence bind points at.
+      #
+      # @param registry [Runtime::Registry] the registry holding the domain's hecksagon
+      # @param domain [String, Symbol] name of the domain the aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose binding is resolved
+      # @return [String] the bound adapter's name, such as `"PostgresEra"`; `"Memory"` when
+      #   the domain declares no hecksagon
+      # @raise [Runtime::WiringError] if the aggregate has no persistence bind, more than one
+      #   authoritative bind, or a bind with a role the port does not support
       def adapter_for(registry, domain, aggregate)
         Ports::Persistence::BindingPolicy.resolve(registry, domain, aggregate).adapter
       end
 
-      # The capability idiom: an adapter CLASS that answers
+      # Asks a named adapter whether it carries eras.
+      #
+      # The capability idiom: an adapter class that answers
       # lineage_capable? with true carries eras and may act on drift
       # (translate, fork, merge). Postgres alone does today; the seam is
       # what lets a second one arrive without touching this file.
+      #
+      # @param registry [Runtime::Registry] the registry whose `adapters` must list the name
+      # @param adapter_name [String] the adapter's name, as `adapter_for` returns it
+      # @return [Boolean] the adapter's own `lineage_capable?` answer; false when the registry
+      #   does not list the adapter, the adapter does not respond to `lineage_capable?`, or
+      #   any `StandardError` is raised on the way (including an adapter with no Ruby
+      #   implementation)
       def lineage_capable?(registry, adapter_name)
         adapter_class = registry.adapters[adapter_name] && registry.adapter_class(adapter_name)
         adapter_class.respond_to?(:lineage_capable?) && adapter_class.lineage_capable?