hecks 1.2.0 → 1.4.0

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?

data/lib/hecks/ports/persistence/plugins/era/era_guard/shape_diff.rb

@@ -6,16 +6,32 @@ module Hecks
       # from the IR it is handed, which is why the Postgres mint path can
       # call it too.
       module ShapeDiff
+        # Computes an aggregate's structural signature, for comparing two eras of it.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to describe
+        # @return [Array<Array>] one `[name, signature]` pair per attribute, sorted by name;
+        #   `name` is a Symbol and `signature` is whatever `attribute_signature` returns
         def shape(aggregate)
           aggregate.attributes.map do |attribute|
             [attribute.name, attribute_signature(aggregate, attribute.type)]
           end.sort_by(&:first)
         end
 
+        # Expands a declared type into a signature that exposes its members.
+        #
         # A plain type name for a primitive; `[type_name, member_signatures]`
         # for a value object or entity, walked recursively — so two
         # attributes with the same declared type name but a different
         # internal shape are never mistaken for unchanged.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate whose value objects and entities
+        #   are searched for `type_name`
+        # @param type_name [String, Bluebook::Reference] the attribute's declared type
+        # @param seen [Array<String, Bluebook::Reference>] types already being expanded, which
+        #   stops a self-referencing type from recursing forever
+        # @return [String, Bluebook::Reference, Array] `type_name` itself for a primitive, a
+        #   reference, or a type already in `seen`; otherwise `[type_name, members]`, where
+        #   `members` is an Array of `[member_name, signature]` pairs sorted by member name
         def attribute_signature(aggregate, type_name, seen = [])
           container = nested_type(aggregate, type_name)
           return type_name if container.nil? || seen.include?(type_name)
@@ -26,13 +42,21 @@ module Hecks
           [type_name, members]
         end
 
+        # Looks a type name up among an aggregate's value objects, then its entities.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to search
+        # @param type_name [String, Bluebook::Reference] the declared type to find
+        # @return [Bluebook::ValueObject, Bluebook::Entity, nil] the matching declaration; nil
+        #   when the type is a primitive, a reference, or nothing this aggregate declares
         def nested_type(aggregate, type_name)
           aggregate.value_object(type_name) || aggregate.entities.find { |entity| entity.name == type_name }
         end
 
+        # Lists the new attributes that would leave an existing record with a required gap.
+        #
         # Attributes present now that the held shape never had — the
-        # addition side of drift, which `uncovered_attributes` above never
-        # looks at, since it only walks the HELD shape (vanish/retype).
+        # addition side of drift, which `uncovered_attributes` below never
+        # looks at, since it only walks the held shape (vanish/retype).
         # Most additions are free (ADR 0025, "Added attributes and
         # absence"): a default:, a list_of (frozen []), or a value object
         # whose fields all default fill an existing record automatically
@@ -40,11 +64,20 @@ module Hecks
         # non-optional attribute with no way to fill itself — can leave an
         # existing record with the field genuinely absent, and that is
         # what this reports: unfilled by a declared translation's own
-        # `backfill`, OR by a move/convert that lands an OLD field inside
+        # `backfill`, or by a move/convert that lands an old field inside
         # this brand-new attribute (`Lineage#fills?` — the destination-
         # side question, never `explains?`'s source-side one, since a
         # rename from Crate to Bin can introduce a top-level attribute
         # name that never existed to have "vanished").
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate as currently declared
+        # @param held_aggregate [Bluebook::Aggregate] the same aggregate as the held era's text
+        #   declares it
+        # @param lineage [Ports::Persistence::Lineage, nil] the edge's rules for this aggregate; nil
+        #   when the edge declares none, so nothing can fill an addition
+        # @return [Array<Symbol>] names of new, non-optional attributes with no default, no
+        #   list cardinality, no fully-defaulted value object and no rule filling them; `[]`
+        #   when every addition is safe
         def unsafe_additions(aggregate, held_aggregate, lineage)
           held_names = held_aggregate.attributes.map(&:name)
 
@@ -55,9 +88,17 @@ module Hecks
                    .map(&:name)
         end
 
-        # THE FOUR-ROW TABLE, as a predicate over the fourth row only — the
+        # Decides whether a new attribute could be genuinely absent from an existing record.
+        #
+        # The four-row table, as a predicate over the fourth row only — the
         # other three (default:, list_of, a fully-defaulted value object)
         # all fill an existing record for free and never reach here.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate declaring the attribute, searched
+        #   for the value object its type may name
+        # @param attribute [Bluebook::Attribute] the newly added attribute
+        # @return [Boolean] false when the attribute is optional, has a default, is a list, or
+        #   is a value object whose every field has a default; true otherwise
         def possibly_absent?(aggregate, attribute)
           return false if attribute.optional?
           return false unless attribute.default.nil?
@@ -69,14 +110,24 @@ module Hecks
           true
         end
 
+        # Lists the held paths that vanished or changed type with no rule explaining them.
+        #
         # Paths the translation needs to explain: attributes that vanished
         # by name, attributes that kept their name but changed type (a
         # `convert` is what lets that be declared at all), and — recursing
-        # into a same-named, same-typed value object — its OWN members
+        # into a same-named, same-typed value object — its own members
         # vanishing or changing type one level down, reported as a dotted
         # path ("price.currency"). A pure addition, at any depth, never
         # needs covering; only vanish-or-retype does, matching the
         # top-level rule at every depth.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate as currently declared
+        # @param held_aggregate [Bluebook::Aggregate] the same aggregate as the held era's text
+        #   declares it
+        # @param lineage [Ports::Persistence::Lineage, nil] the edge's rules for this aggregate; nil
+        #   when the edge declares none, so every vanished or retyped path is reported
+        # @return [Array<String>] bare attribute names and dotted member paths such as
+        #   `"price.currency"`; `[]` when the whole diff is explained
         def uncovered_attributes(aggregate, held_aggregate, lineage)
           paths = held_aggregate.attributes.flat_map do |held_attribute|
             current_attribute = aggregate.attribute(held_attribute.name)
@@ -90,20 +141,37 @@ module Hecks
           paths.reject { |path| lineage.explains?(path) }
         end
 
-        # `held_type`/`current_type` are type NAMES, resolved against each
-        # side's OWN value_object AND entity declarations — neither is ever
+        # Compares one path's held and current types, recursing into shared members.
+        #
+        # `held_type`/`current_type` are type names, resolved against each
+        # side's own value_object and entity declarations — neither is ever
         # nested in the DSL, only in the type graph, so both are always
         # looked up flat off their respective aggregate. A `list_of` entity
-        # is only reached here to DETECT a member vanish-or-retype; there is
+        # is only reached here to detect a member vanish-or-retype; there is
         # no per-element translation machinery yet (`move`/`convert`/`drop`
         # only reach into a single nested hash, not each element of an
         # array) — the only way to satisfy a refusal on an entity path
         # today is a top-level `drop` of the whole list attribute, which
         # `explains?` already recognizes as covering everything nested
         # under it. Blunt, but loud beats silent.
+        #
+        # @param path [String] the bare or dotted path being compared, reported on a mismatch
+        # @param held_type [String, Bluebook::Reference] the type the held era declares there
+        # @param current_type [String, Bluebook::Reference] the type declared there now
+        # @param held_aggregate [Bluebook::Aggregate] the held aggregate, searched for
+        #   `held_type`'s declaration
+        # @param aggregate [Bluebook::Aggregate] the current aggregate, searched for
+        #   `current_type`'s declaration
+        # @param lineage [Ports::Persistence::Lineage, nil] the edge's rules, asked whether a retype
+        #   pairs the two type names; nil means no retype is accepted
+        # @param seen [Array<String, Bluebook::Reference>] current types already being
+        #   expanded, which stops a self-referencing type from recursing forever
+        # @return [Array<String>] `[path]` when the types differ with no retype declared; the
+        #   dotted paths of members that vanished or changed type beneath it; `[]` when
+        #   nothing differs or either type is not a value object or entity
         def diff_type(path, held_type, current_type, held_aggregate, aggregate, lineage, seen = [])
           if held_type != current_type
-            # A declared retype says the two TYPE names mean the same shape
+            # A declared retype says the two type names mean the same shape
             # — accept the pair, but still recurse into the members so a
             # member drift hiding beneath the rename is caught by name.
             return [path] unless lineage&.retype?(held_type, current_type)