hecks 2.8.0 → 3.0.0

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

@@ -1,32 +1,16 @@
 module Hecks
   module Ports
     module Persistence
-      # **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
-      # any `RemoteRuntime`-shaped adapter (Lambda; the real durability
-      # for those lives on the other side of the call — Phase 1, not
-      # here). `SagaInterpreter`'s hook points call through
-      # `saga_persistence(domain)` unconditionally; this is what makes
-      # that safe without a `respond_to?` check at every call site,
-      # mirroring the same optional-capability shape
-      # `Ports::Persistence::AppendOnly` already gives adapters that
-      # don't implement `reset!`/`events`/`record_event`.
+      # A saga store that keeps nothing, for adapters without the optional saga-persistence
+      # capability; callers call through it unconditionally instead of checking `respond_to?`.
       class NullSagaStore
-        # Accepts and discards a saga checkpoint, whatever keywords it carries.
-        #
-        # @return [nil] always; nothing is stored
+        # Discards the checkpoint.
         def save_saga(**) = nil
 
-        # Accepts and ignores a request to forget a saga.
-        #
-        # @return [nil] always; there is nothing to delete
+        # Ignores the request; 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

@@ -1,28 +1,12 @@
 module Hecks
   module Ports
-    # Reopened to hold the persistence-plugin registry (`Plugin`, below) and
-    # its call surface (`register_plugin`/`plugin?`/`each_plugin`) — see ADR
-    # 0033 and `Plugin`'s own header for the seam this fills.
+    # Holds the persistence-plugin registry and its `register_plugin`/`plugin?`/`each_plugin`
+    # surface.
     module Persistence
-      # A tiny, real seam — ADR 0033. Core never names a persistence plugin;
-      # 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
-      # must satisfy: anything responding to `contribute_boot_gates(registry,
-      # gates)` (a no-op is a valid implementation).
+      # The persistence-plugin registry (ADR 0033). A plugin registers itself when required, and
+      # need only respond to `contribute_boot_gates(registry, gates)`; a no-op is valid.
       #
-      # 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
-      # 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
-      # module-level hash is the right shape here, not an instantiable class.
+      # Process-wide and name-keyed: a plugin is either required into this process or it is not.
       module Plugin
         @plugins = {}
 
@@ -37,33 +21,25 @@ module Hecks
             @plugins[name.to_sym] = plugin
           end
 
-          # Reports whether a plugin of that name has been required into this process.
+          # Whether a plugin is registered under `name`.
           #
-          # @param name [Symbol, String] the plugin's name
-          # @return [Boolean] true when a plugin is registered under `name`
+          # @return [Boolean]
           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.
+          # Whether at least one plugin is registered.
           #
-          # @return [Boolean] true when at least one plugin is registered
+          # @return [Boolean]
           def any? = !@plugins.empty?
         end
       end
 
-      # `Ports::Persistence.plugin?(:era)` / `.each_plugin` — the ordinary
-      # call surface; `Plugin.register`/`.registered?`/`.each` stay reachable
-      # 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.
@@ -73,22 +49,17 @@ module Hecks
       # @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.
+      # 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`
+      # @return [Boolean]
       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.
+      # Whether any persistence plugin is loaded in this process.
       #
-      # @return [Boolean] true when at least one plugin is registered
+      # @return [Boolean]
       def plugins_loaded? = Plugin.any?
     end
   end

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

@@ -3,57 +3,29 @@ require_relative "../../../../ports/persistence/binding_policy"
 require_relative "lineage"
 require_relative "../../../../naming"
 require_relative "../../../../framework"
+require_relative "../../../../chapters"
 require_relative "../../../../runtime/registry"
 require_relative "expected_era"
 
 module Hecks
   module Runtime
-    # 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
-    # history about data nothing can act on.
-    #
-    # 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
-    # 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.
-    #
-    # The capability is asked of the adapter, never of its name: a
-    # second adapter that grows an era story declares lineage_capable?
-    # and era_check! and needs no change here.
-    #
-    # Detection and identity are separate jobs: this check never hashes
-    # anything — era names come from the store, already minted (by the
-    # scaffold) or absent. Refusal wordings are contract, pinned by the
-    # corpus.
+    # The boot-time era gate for lineage-capable adapters (Postgres today):
+    # each capable adapter's own era_check! decides hold, recognize, mint, or refuse.
     module EraCheck
       module_function
 
       # 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
-      # reconstructs a completely different shape, and every boot after
-      # the first refuses toward a scaffold that was never the real
-      # drift.
+      # Looks up each bluebook's own source separately: `uses_framework` can share a boot between
+      # the domain's own bluebook and a differently-sourced one, so one file read once and reused
+      # for every bluebook would attribute the wrong text.
       #
       # @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
+      # @param directory [String] the domain's bluebook directory, searched for each 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
+      # @raise [Runtime::WiringError] if a compute rule is bound to a non-lineage-capable adapter,
+      #   a persistence binding cannot be resolved, a lineage-bound bluebook has no findable
+      #   source, or `era_check!` refuses the boot
       def check!(registry, directory)
         check_compute_rules_for_registry!(registry)
         check_lineage!(registry, directory)
@@ -61,12 +33,8 @@ module Hecks
 
       # 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
-      # `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.
+      # Runs unconditionally for every registry, unlike check_lineage!'s
+      # capability-gated pass below (ADR 0031).
       #
       # @param registry [Runtime::Registry] the registry whose bluebooks are all checked
       # @return [void]
@@ -78,11 +46,8 @@ module Hecks
 
       # 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.
+      # Capability-gated (ADR 0031): check_bluebook! below still returns
+      # early for any bluebook whose own binding isn't lineage-capable.
       #
       # @param registry [Runtime::Registry] the registry being booted
       # @param directory [String] path of the domain's own bluebook directory
@@ -98,12 +63,9 @@ module Hecks
 
       # 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.
+      # Mirrors check_bluebook!'s own per-bluebook anchor check, asked
+      # once up front so a registry with nothing lineage-capable never
+      # registers the `:era_check` 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
@@ -121,51 +83,15 @@ module Hecks
 
       # 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 cannot 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
-      # 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
-      # 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 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.
+      # Matched by declared name, not position: a domain directory using
+      # `uses_framework` may hold more than one file, and a framework
+      # member or vendored bluebook is excluded from the single-file
+      # fallback so its own real source is read, not a sibling's.
       #
       # @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
+      # @param registry [Runtime::Registry, nil] nil skips the vendored-bluebook lookup
+      # @return [String, nil] UTF-8 text of every matching file joined with `"\n"`, or nil
       def source_text_for(bluebook, directory, registry: nil)
         domain_files = Dir[File.join(directory, "*.bluebook")]
         own = domain_files.select { |path| declares_bluebook?(path, bluebook.name) }
@@ -190,26 +116,23 @@ module Hecks
 
       # 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.
+      # Tries, in order: a chapter the gem carries (the QA ledger's QualityControl), the domain's
+      # own single remaining file, a framework member, then 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
+      # @return [Array<String>] file paths to read, in load order; `[]` when none applies
       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]
+        attached = Chapters.index.fetch(bluebook.name, [])
 
-        if domain_files.size == 1 && !framework_path && !vendored_name
+        if attached.any? && !framework_path && !vendored_name
+          attached
+        elsif domain_files.size == 1 && !framework_path && !vendored_name
           domain_files
         elsif framework_path
           [framework_path]
@@ -222,13 +145,8 @@ module Hecks
 
       # 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.
+      # Matched by Pascal-casing: the vendored name Pascal-cases to this
+      # bluebook's own declared name.
       #
       # @param registry [Runtime::Registry] the registry whose hecksagons are searched
       # @param bluebook_name [String] the bluebook's declared Pascal-case name
@@ -244,17 +162,9 @@ module Hecks
 
       # 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.
+      # Listed in `Dir.glob` order, matching load order at boot, since a
+      # later reconstruction of this text depends on seeing files in the
+      # order that built the live shape.
       #
       # @param directory [String] path of the domain's own bluebook directory, whose parent
       #   holds `vendor/embryonaut_bluebooks`
@@ -269,16 +179,12 @@ module Hecks
 
       # 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.
+      # The first aggregate is the anchor: its binding alone decides the adapter asked.
       #
       # @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
+      # @param current_text [String, nil] the bluebook's source; nil means none was found
+      # @param directory [String, nil] the domain's bluebook directory, named in the refusal
       # @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!`
@@ -305,10 +211,8 @@ module Hecks
 
       # 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.
+      # A compute rule's SQL is its only implementation, so it cannot
+      # boot on any adapter but Postgres, independent of shape checks.
       #
       # @param registry [Runtime::Registry] the registry holding the declared translations
       #   and the aggregate's bindings
@@ -343,17 +247,13 @@ module Hecks
 
       # 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.
+      # Postgres alone answers true today; the seam lets a second
+      # lineage-capable adapter 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)
+      # @return [Boolean] the adapter's own answer; false if unlisted, not lineage-capable, or
+      #   any `StandardError` is raised
       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

@@ -1,37 +1,18 @@
 module Hecks
   module Runtime
     module EraGuard
-      # The pure half: computing an aggregate's structural signature and
-      # diffing two eras' shapes. No file I/O — everything here answers
-      # from the IR it is handed, which is why the Postgres mint path can
-      # call it too.
+      # Structural signature and diff of aggregate shapes, computed from the IR alone
+      # (no file I/O), so 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
+        # Structural signature of an aggregate: sorted `[name, signature]` pairs per attribute.
         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
+        # Expands a declared type so same-named types with different members never compare equal.
+        # Primitives and references come back as-is; `seen` stops self-referencing types.
         def attribute_signature(aggregate, type_name, seen = [])
           container = nested_type(aggregate, type_name)
           return type_name if container.nil? || seen.include?(type_name)
@@ -42,42 +23,13 @@ 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` 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
-        # via `Instance.hydrate_with_defaults`. Only the fourth case — a
-        # 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
-        # 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
+        # Names of new, non-optional attributes that no default, list, defaulted value object
+        # or translation rule (`Lineage#fills?`) can fill on an existing record.
+        # Destination-side check: a rename can add a name that never existed to "vanish".
         def unsafe_additions(aggregate, held_aggregate, lineage)
           held_names = held_aggregate.attributes.map(&:name)
 
@@ -88,17 +40,7 @@ module Hecks
                    .map(&:name)
         end
 
-        # 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
+        # True when a new attribute could be genuinely absent from an existing record (ADR 0025).
         def possibly_absent?(aggregate, attribute)
           return false if attribute.optional?
           return false unless attribute.default.nil?
@@ -110,24 +52,8 @@ 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
-        # 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
+        # Held attribute paths that vanished or changed type with no rule explaining them,
+        # recursing into value objects as dotted paths ("price.currency"). Additions never count.
         def uncovered_attributes(aggregate, held_aggregate, lineage)
           paths = held_aggregate.attributes.flat_map do |held_attribute|
             current_attribute = aggregate.attribute(held_attribute.name)
@@ -142,38 +68,12 @@ module Hecks
         end
 
         # 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
-        # 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
+        # A `list_of` entity is diffed only for member drift; no per-element translation exists, so
+        # only a top-level `drop` of the whole list satisfies it.
         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
-            # — accept the pair, but still recurse into the members so a
-            # member drift hiding beneath the rename is caught by name.
+            # A declared retype accepts the pair but members are still compared, so drift
+            # hidden under the rename is caught.
             return [path] unless lineage&.retype?(held_type, current_type)
           end
           return [] if seen.include?(current_type)