hecks 1.3.0 → 1.5.0

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

@@ -12,28 +12,32 @@ module Hecks
     # the declared routing `version:` — is excluded, so editing behavior
     # never bumps an era and editing shape always does.
     #
-    # Three attribute facts on the wire are constraints on PERSISTED
-    # VALUES, not behavior, and are still excluded — each decided, not
+    # ## Constraints left out on purpose
+    #
+    # Three attribute facts on the wire are constraints on persisted
+    # values, not behavior, and are still excluded — each decided, not
     # overlooked:
     #
     #   `optional`  — required-ness is enforced at dispatch; stored rows
     #                 are never re-validated on read, so flipping it
     #                 strands nothing already written. Excluded.
-    #   `pattern`   — same argument: a fact about what may be WRITTEN
+    #   `pattern`   — same argument: a fact about what may be written
     #                 next, not about what was stored. Excluded.
     #   `admits`    — the sharpest of the three: narrowing a closed set
-    #                 CAN strand stored rows outside it, and the wire
-    #                 carries only the set's NAME, so a set whose members
+    #                 can strand stored rows outside it, and the wire
+    #                 carries only the set's name, so a set whose members
     #                 changed under a stable name is invisible even to a
     #                 projection that included the fact (the same lesson
     #                 recursive value-object drift taught). Excluded, and
-    #                 NAMED as a gap: constraint tightening has no
+    #                 named as a gap: constraint tightening has no
     #                 translation-rule vocabulary to acknowledge it yet,
     #                 so including it would mint era bumps nothing can
     #                 explain. When the translation language grows a
     #                 constraint-acknowledgment rule, `admits` (by member
     #                 list, not by name) is first in line, and that
-    #                 change bumps FORM_VERSION.
+    #                 change bumps `FORM_VERSION`.
+    #
+    # ## Structural comparison over the dump form
     #
     # Projection runs over the canonical dump form (`to_h`, JSON
     # round-tripped), so a verdict depends only on the IR — never on live
@@ -41,6 +45,11 @@ module Hecks
     module StorageShape
       module_function
 
+      # Reduces a bluebook to the parts of its IR that decide what stored data looks like.
+      #
+      # @param bluebook [Bluebook::Chapter] the bluebook whose `to_h` dump is projected
+      # @return [Hash{String => Object}] `"name"` (the bluebook's name) and `"aggregates"`, an
+      #   Array of the Hashes `project_aggregate` builds, sorted by aggregate name
       def project(bluebook)
         domain = JSON.parse(JSON.generate(bluebook.to_h))
         {
@@ -51,30 +60,55 @@ module Hecks
         }
       end
 
+      # Compares two bluebooks by storage shape alone, ignoring every behavioral difference.
+      #
+      # @param held [Bluebook::Chapter] the bluebook a held era was minted from
+      # @param current [Bluebook::Chapter] the bluebook booting now
+      # @return [Boolean] true when both project to an equal structure
       def same?(held, current) = project(held) == project(current)
 
-      # The canonical serialization the Ruby scaffold hashes at MINT time
+      # The canonical serialization the Ruby scaffold hashes at mint time
       # — the one moment identity is computed. Nothing ever recomputes a
       # stored era name to verify it, so this form can evolve freely.
+      #
+      # @param bluebook [Bluebook::Chapter] the bluebook to serialize
+      # @return [String] compact JSON text of `project(bluebook)`
       def canonical(bluebook) = JSON.generate(project(bluebook))
 
+      # Computes the era identity of a bluebook's storage shape.
+      #
+      # @param bluebook [Bluebook::Chapter] the bluebook being minted
+      # @return [String] 64 lowercase hex characters, the SHA-256 of `canonical(bluebook)`
       def mint_hash(bluebook) = Digest::SHA256.hexdigest(canonical(bluebook))
 
       LABEL_LENGTH = 6
+
+      # Shortens the era identity to the label translation edges and refusals use.
+      #
+      # @param bluebook [Bluebook::Chapter] the bluebook being minted
+      # @return [String] the first `LABEL_LENGTH` hex characters of `mint_hash(bluebook)`
       def mint_label(bluebook) = mint_hash(bluebook)[0, LABEL_LENGTH]
 
       # The version of the canonical serialization above. Minted-once
       # means a stored name stays valid across form changes — but only
-      # if each name records WHICH form minted it, so v1-named and
+      # if each name records which form minted it, so v1-named and
       # v2-named eras coexist legibly. Stored beside every minted hash
       # (names.tsv fourth field / hecks_eras.canon_form); bump this in
       # the same change that alters project/canonical output.
       FORM_VERSION = 1
 
+      # Projects one dumped aggregate down to its identity, lifecycle field and attributes.
+      #
+      # @param aggregate [Hash{String => Object}] one entry of the dumped bluebook's
+      #   `"aggregates"` list, string-keyed after the JSON round-trip
+      # @return [Hash{String => Object}] `"name"`, `"identity"` (Array<String> of declared
+      #   identity paths, `[]` when none is declared), `"lifecycle_field"` (String, or nil
+      #   without a lifecycle) and `"attributes"` (Array of `project_attribute` Hashes, sorted
+      #   by name)
       def project_aggregate(aggregate)
         {
           "name"            => aggregate["name"],
-          # The declared identity paths, AS A LIST, in declaration order —
+          # The declared identity paths, as a list, in declaration order —
           # order is semantic (the paths join in order to form the id).
           # No "id" fallback: an aggregate that declares nothing has [],
           # and that is a real declared state, distinct from an aggregate
@@ -87,6 +121,16 @@ module Hecks
         }
       end
 
+      # Projects one dumped attribute to its name, cardinality and full type signature.
+      #
+      # @param aggregate [Hash{String => Object}] the dumped aggregate that owns the attribute,
+      #   searched for the value objects and entities its type may name
+      # @param attribute [Hash{String => Object}] the dumped attribute, read for `"name"`,
+      #   `"list"` and `"type"`
+      # @param seen [Array<String>] type names already being expanded, which stops a
+      #   self-referencing type from recursing forever
+      # @return [Hash{String => Object}] `"name"` (String), `"list"` (Boolean) and `"type"`
+      #   (whatever `type_signature` returns)
       def project_attribute(aggregate, attribute, seen)
         {
           "name" => attribute["name"].to_s,
@@ -99,6 +143,14 @@ module Hecks
       # members' full signatures for a value object or entity — so two
       # attributes with the same declared type name but different
       # internals are never mistaken for unchanged.
+      #
+      # @param aggregate [Hash{String => Object}] the dumped aggregate whose value objects and
+      #   entities are searched for `type_name`
+      # @param type_name [String] the attribute's declared type name
+      # @param seen [Array<String>] type names already being expanded
+      # @return [String, Hash{String => Object}] `type_name` itself for a primitive or a type
+      #   already in `seen`; otherwise `"type"` plus `"members"`, the member attributes'
+      #   `project_attribute` Hashes sorted by name
       def type_signature(aggregate, type_name, seen)
         container = nested_type(aggregate, type_name)
         return type_name if container.nil? || seen.include?(type_name)
@@ -111,6 +163,12 @@ module Hecks
         }
       end
 
+      # Looks a type name up among a dumped aggregate's value objects, then its entities.
+      #
+      # @param aggregate [Hash{String => Object}] the dumped aggregate to search
+      # @param type_name [String] the declared type name to find
+      # @return [Hash{String => Object}, nil] the dumped value object or entity; nil when the
+      #   name is a primitive or belongs to nothing this aggregate declares
       def nested_type(aggregate, type_name)
         (aggregate["value_objects"] || []).find { |vo| vo["name"] == type_name } ||
           (aggregate["entities"] || []).find { |entity| entity["name"] == type_name }

data/lib/hecks/ports/persistence/plugins/era/translation/audit/approval_digest.rb

@@ -7,21 +7,27 @@ module Hecks
       # ── the human gate, made real ──────────────────────────────────
       #
       # For the five portable rule kinds the mint verifies the edge
-      # mechanically (Layer 2 IS the cross-execution equivalence gate).
+      # mechanically (Layer 2 is the cross-execution equivalence gate).
       # A compute has no mechanical verification — the Layer-3 sample a
       # human reads is the only one there is — so a compute edge cannot
       # mint until someone has run `bin/translation_audit … --approve`.
       #
-      # The approval binds to WHAT WAS ACTUALLY REVIEWED, on both axes:
+      # The approval binds to what was actually reviewed, on both axes:
       # a content digest of the parsed edge (change the edge's meaning
       # and the approval lapses; a comment does not), and the journal's
-      # high-water ordinal at review time, recorded IN the target
+      # high-water ordinal at review time, recorded in the target
       # database — a token in the repo could not bind to the data, and
       # samples reviewed against staging or against production-as-of-T
       # say nothing about a database that has moved on. Mint stays
       # non-interactive and its lock stays short; the human decision
       # happens in the audit tool, where the samples are.
       module ApprovalDigest
+        # Fingerprints a parsed translation edge, so an approval lapses when the edge's
+        # meaning changes but not when only a comment does.
+        #
+        # @param edge [Bluebook::Translation] the parsed translation edge
+        # @return [String] 64 lowercase hex characters: the SHA-256 of the edge's exported
+        #   JSON (`Projector::Exporter.translation_hash`)
         def edge_digest(edge)
           Digest::SHA256.hexdigest(JSON.generate(Projector::Exporter.translation_hash(edge)))
         end

data/lib/hecks/ports/persistence/plugins/era/translation/audit/layer_one.rb

@@ -8,11 +8,18 @@ module Hecks
     module Audit
       # Layer 1 — from the bluebook alone: every translated state must
       # pass the new era's types, value-object invariants, and lifecycle.
-      # This is also where a NEW, stricter invariant that old records
+      # This is also where a new, stricter invariant that old records
       # violate surfaces — there is no "grandfather old records"
       # construct, and the remedy is relaxing the invariant or explicit
       # remediation, never a translation rule.
       module LayerOne
+        # Hydrates every translated state as a current-era instance and records each one
+        # the era's types, invariants or lifecycle refuse.
+        #
+        # @param violations [Array<String>] collector this method appends messages to
+        # @param aggregate [Bluebook::Aggregate] the current era's IR for the aggregate
+        # @param after [Hash{String => Hash}] translated state per record id, as parsed JSON
+        # @return [void]
         def layer_one!(violations, aggregate, after)
           after.each do |id, state|
             symbolized = JSON.parse(JSON.generate(state), symbolize_names: true)
@@ -25,7 +32,7 @@ module Hecks
             # legitimately declared just as a `from:` (a terminal
             # transition's source, never anyone's target) is real and
             # reachable but invisible to it. `ModelCheck.full_states`
-            # is the full declared set (default, every target, AND
+            # is the full declared set (default, every target, and
             # every from) that `fuzzing/properties.rb`'s own replay
             # check already uses for this identical question — see its
             # comment on this same hole.

data/lib/hecks/ports/persistence/plugins/era/translation/audit/layer_two.rb

@@ -7,8 +7,11 @@ module Hecks
       # Layer 2 — from the edge alone: per-rule value preservation, no
       # leftover source keys, and id-set conservation across the edge.
       module LayerTwo
+        # Checks one aggregate's records across the edge for id conservation and, where a
+        # per-record comparison is possible, agreement with the reference transform.
+        #
         # Per-rule value preservation and leftover source keys are checked
-        # against the reference transform IN FULL — never rule by rule in
+        # against the reference transform in full — never rule by rule in
         # isolation, because rules interact (a rename whose value a later
         # move partially consumes preserves exactly what the transform
         # says it preserves, no more). This makes every mint a run of the
@@ -17,10 +20,20 @@ module Hecks
         # transform produces `expected`; they must agree byte-for-byte on
         # every path a compute doesn't own. Compute paths are exempt — the
         # SQL is their only implementation, and the Layer-3 sample is
-        # their only review. A rekeyed aggregate is exempt from this WHOLE
+        # their only review. A rekeyed aggregate is exempt from this whole
         # per-record check, for the same reason and one more: there is no
         # old-id → new-id correspondence to look `after` up by once the id
         # itself is what changed.
+        #
+        # @param violations [Array<String>] collector this method appends messages to
+        # @param aggregate [Bluebook::Aggregate] the current era's IR for the aggregate
+        # @param declared [Bluebook::TranslationAggregate, nil] this edge's rules for the
+        #   aggregate; nil limits the check to id conservation
+        # @param before [Hash{String => Hash}] source state per record id, as parsed JSON
+        # @param after [Hash{String => Hash}] translated state per record id, as parsed JSON
+        # @return [void]
+        # @raise [Runtime::WiringError] if the reference transform cannot translate a `before`
+        #   state: a convert meets an unmapped value, or a move nests under a non-Hash
         def layer_two!(violations, aggregate, declared, before, after)
           rekeyed = declared && !declared.rekeys.empty?
 
@@ -38,15 +51,25 @@ module Hecks
           check_value_preservation!(violations, aggregate, declared, before, after)
         end
 
+        # Records a violation when the edge loses, gains or collides record ids.
+        #
         # Record-count / id-set conservation — one of the two properties
         # this module's own header names, and independent of the other
         # (per-rule value preservation, below): it needs only `before`,
         # `after`, and whether the edge rekeyed, never the declared rules
         # themselves.
+        #
+        # @param violations [Array<String>] collector this method appends at most one message to
+        # @param aggregate [Bluebook::Aggregate] the aggregate, named in the message
+        # @param before [Hash{String => Hash}] source state per record id
+        # @param after [Hash{String => Hash}] translated state per record id
+        # @param rekeyed [Boolean, nil] truthy when the edge rekeys, which compares record
+        #   counts instead of id sets
+        # @return [void]
         def check_id_conservation!(violations, aggregate, before, after, rekeyed:)
-          # A rekey legitimately changes the id SET (that's the entire
+          # A rekey legitimately changes the id set (that's the entire
           # point) — set-equality would flag every honest rekey as data
-          # loss. What must still hold is RECORD COUNT: a botched rekey
+          # loss. What must still hold is record count: a botched rekey
           # colliding two distinct old ids onto one new id, or dropping one
           # (its SQL returning NULL), shows up as the count going down —
           # caught here without needing to track the old→new mapping
@@ -69,6 +92,12 @@ module Hecks
         # header names. Only reached once `layer_two!` has already ruled
         # out "no declared edge" and "rekeyed" (see its own comment on
         # that second guard); this method assumes both are false.
+        # @param violations [Array<String>] mutated in place with one message per divergent id
+        # @param aggregate [Bluebook::Aggregate] the aggregate being audited
+        # @param declared [Bluebook::Translation] the declared translation to check against
+        # @param before [Hash{String => Hash}] the old world's own records, keyed by id
+        # @param after [Hash{String => Hash}] the new world's own records, keyed by id
+        # @return [void]
         def check_value_preservation!(violations, aggregate, declared, before, after)
           rules = Ports::Persistence::Lineage.from_declared(declared, aggregate.name)
           compute_paths = declared.computes.flat_map { |compute| [compute.from, compute.to] }.map(&:to_s)
@@ -87,21 +116,32 @@ module Hecks
           end
         end
 
+        # Round-trips state through JSON so both sides of the comparison share one spelling.
+        #
+        # @param state [Hash, nil] a state with Symbol or String keys
+        # @return [Hash{String => Object}, nil] a deep copy with String keys at every depth
         def normalize(state) = JSON.parse(JSON.generate(state))
 
+        # Removes the paths a compute owns from a normalized state, in place.
+        #
         # Exempts exactly the paths a compute owns, not the whole
         # top-level attribute it happens to live under. A bare path
         # ("price_cents") is itself the compute's entire value — dropping
         # the whole top-level key is correct, there's nothing else there
-        # to check. A DOTTED path ("price.cents") only owns that one
+        # to check. A dotted path ("price.cents") only owns that one
         # member of the value object it reaches into; every sibling
         # member (e.g. "price.currency") is untouched by the compute and
         # must stay subject to the equivalence check below. Blanket-
-        # dropping the whole top-level key for a dotted compute used to
+        # dropping the whole top-level key for a dotted compute would
         # exempt the entire attribute — silent data loss elsewhere in the
         # same value object (a migration that nulls or drops a sibling
-        # field) produced zero violations, defeating the one gate whose
-        # entire purpose is to catch exactly that.
+        # field) would produce zero violations, defeating the one gate
+        # whose entire purpose is to catch exactly that.
+        #
+        # @param state [Hash{String => Object}] a normalized state; mutated
+        # @param paths [Array<String>] bare (`"price_cents"`) or dotted (`"price.cents"`)
+        #   compute paths
+        # @return [Hash{String => Object}] `state` itself, with those paths deleted
         def strip_compute_paths(state, paths)
           paths.each do |path|
             segments = path.split(".")

data/lib/hecks/ports/persistence/plugins/era/translation/audit/unfed_report.rb

@@ -4,9 +4,11 @@ module Hecks
       # New-era attributes that nothing feeds: absent from every
       # translated state, produced by no rule, and carrying no default.
       # A report, not a violation — the remedy is a `default:` on the
-      # attribute, and the loud refusal for a REQUIRED one comes from
+      # attribute, and the loud refusal for a required one comes from
       # Layer 1 the moment an invariant reads it.
       module UnfedReport
+        # Lists the current era's attributes that no rule, default or translated record feeds.
+        #
         # `fed` build-up plus one ordered guard chain per attribute
         # (already fed, has a default, actually present in some record, no
         # records to check at all) answering a single question — "is
@@ -14,6 +16,13 @@ module Hecks
         # rules out one way the answer is "not unfed after all" before the
         # next is even worth asking. Splitting the guards out would just
         # turn each into a same-shaped one-line predicate call.
+        #
+        # @param aggregate [Bluebook::Aggregate] the current era's IR for the aggregate
+        # @param declared [Bluebook::TranslationAggregate, nil] this edge's rules; the
+        #   destinations of its renames, moves, converts and computes count as fed
+        # @param after [Hash{String => Hash}] translated state per record id
+        # @return [Array<String>] names of unfed attributes, in declaration order; `[]` when
+        #   every attribute is fed or `after` holds no records
         # rubocop:disable-next Metrics/CyclomaticComplexity
         # rubocop:disable-next Metrics/PerceivedComplexity
         def unfed(aggregate, declared, after)
@@ -36,6 +45,12 @@ module Hecks
           end
         end
 
+        # Reads a dotted path out of a state whose keys may be Strings or Symbols.
+        #
+        # @param state [Hash, nil] the state to read
+        # @param path [String, Symbol] a bare or dotted path, such as `"price.cents"`
+        # @return [Object, nil] the value held at the path, `false` included; nil when `state`
+        #   is nil, a segment is absent, or a segment's parent is not a Hash
         def dig_path(state, path)
           return nil if state.nil?
 

data/lib/hecks/ports/persistence/plugins/era/translation/audit.rb

@@ -12,10 +12,14 @@ module Hecks
     # rules), audit/layer_two.rb (the edge against the reference
     # transform), audit/unfed_report.rb (what nothing feeds), and
     # audit/approval_digest.rb (the human gate's binding). Layer 3 — the
-    # before/after sample a HUMAN approves, intent not being derivable —
+    # before/after sample a human approves, intent not being derivable —
     # is assembled right here in `check`.
     module Audit
       Verdict = Struct.new(:violations, :dropped, :unfed, :samples, keyword_init: true) do
+        # Reports whether the mechanical layers found nothing to refuse.
+        #
+        # @return [Boolean] true when `violations` is empty; `dropped`, `unfed` and `samples`
+        #   are reports and never affect the answer
         def ok? = violations.empty?
       end
 
@@ -28,9 +32,20 @@ module Hecks
 
       module_function
 
-      # aggregate — the CURRENT era's IR; declared — this edge's rules
-      # for it (may be nil); before/after — {id => state hash}, source
-      # era's latest vs translated.
+      # Audits one aggregate's records across one translation edge and gathers what a
+      # human reviewer needs to see.
+      #
+      # @param aggregate [Bluebook::Aggregate] the current era's IR for the aggregate
+      # @param declared [Bluebook::TranslationAggregate, nil] this edge's rules for the
+      #   aggregate; nil when the edge declares none
+      # @param before [Hash{String => Hash}] the source era's latest state per record id, as
+      #   parsed JSON
+      # @param after [Hash{String => Hash}] the translated state per record id, as parsed JSON
+      # @return [Translation::Audit::Verdict] `violations` (Layer 1 and 2 messages), `dropped`
+      #   (declared drop paths as Strings), `unfed` (attribute names nothing feeds) and
+      #   `samples` (the Layer 3 before/after pairs)
+      # @raise [Runtime::WiringError] if Layer 2's reference transform cannot translate a
+      #   `before` state: a convert meets an unmapped value, or a move nests under a non-Hash
       def check(aggregate:, declared:, before:, after:)
         violations = []
 
@@ -45,22 +60,38 @@ module Hecks
         )
       end
 
+      # Picks the first `SAMPLE_SIZE` records, by sorted id, for a human to compare.
+      #
+      # @param declared [Bluebook::TranslationAggregate, nil] this edge's rules; a rekey among
+      #   them switches to `rekeyed_samples`
+      # @param before [Hash{String => Hash}] source state per record id
+      # @param after [Hash{String => Hash}] translated state per record id
+      # @return [Array<Hash{Symbol => Object}>] Hashes with `:id`, `:before` and `:after`;
+      #   `:after` is nil for an id missing from `after`
       def samples_for(declared, before, after)
         return rekeyed_samples(before, after) if declared && !declared.rekeys.empty?
 
         before.keys.sort.first(SAMPLE_SIZE).map { |id| { id: id, before: before[id], after: after[id] } }
       end
 
+      # Samples both sides of a rekeying edge separately instead of pairing them by id.
+      #
       # A rekey changes the id itself, so `before`'s and `after`'s
       # keyspaces share nothing — pairing by matching id (the ordinary
       # path above) would show every `after` as nil, telling a human
       # nothing. Nothing in-process can compute the old→new
       # correspondence either (the rekey's SQL is its only
       # implementation, same as compute's own). Shown side by side
-      # instead, each labelled by its OWN id: real records going in,
+      # instead, each labelled by its own id: real records going in,
       # real records coming out — not claimed to correspond one-to-one,
       # but enough for the human this rule's only verification depends
       # on to actually see real shapes and values, not a wall of null.
+      #
+      # @param before [Hash{String => Hash}] source state per old record id
+      # @param after [Hash{String => Hash}] translated state per new record id
+      # @return [Array<Hash{Symbol => Object}>] up to `SAMPLE_SIZE` Hashes whose `:id` ends in
+      #   `" (before)"` with `:after` nil, then up to `SAMPLE_SIZE` ending in `" (after)"` with
+      #   `:before` nil
       def rekeyed_samples(before, after)
         before.keys.sort.first(SAMPLE_SIZE).map { |id| { id: "#{id} (before)", before: before[id], after: nil } } +
           after.keys.sort.first(SAMPLE_SIZE).map { |id| { id: "#{id} (after)", before: nil, after: after[id] } }

data/lib/hecks/ports/persistence/plugins/era/translation/reattest.rb

@@ -6,19 +6,33 @@ require_relative "../storage_shape"
 module Hecks
   module Translation
     # The question re-attestation must answer before anything else: did
-    # the edit change the era's SHAPE, or only its text? Cosmetic edits
+    # the edit change the era's shape, or only its text? Cosmetic edits
     # (comments, whitespace, behavior) re-freeze safely; a shape change
     # would retroactively redefine what era N *meant* for data already
     # written under it, and refuses hard — there is no --accept past
     # this guard.
     #
     # This does not violate minted-once. That prohibition exists so
-    # boot-time RECOGNITION never depends on canonicalization stability;
+    # boot-time recognition never depends on canonicalization stability;
     # this is operator-initiated repair, where a false negative is a
     # loud refusal, never a silent misread.
     module Reattest
       module_function
 
+      # Decides whether an edited era text still projects to the shape the era was frozen
+      # with, refusing the edit when it does not.
+      #
+      # @param domain [String] the domain's name, used in refusal messages
+      # @param ordinal [Integer] the era's ordinal, used in refusal messages
+      # @param text [String] the held era's bluebook source as it now stands
+      # @param stored_hash [String, nil] the era's minted shape hash (SHA-256 hex); nil for an
+      #   era that was never named
+      # @param stored_projection [Hash{String => Object}, nil] the era's stored
+      #   `Runtime::StorageShape.project` result as parsed JSON; nil for a store without one
+      # @return [Symbol] `:cosmetic` when the shape is unchanged, `:unnamed` when neither a
+      #   projection nor a hash is stored so no comparison is possible
+      # @raise [Runtime::WiringError] if `text` does not load as a bluebook, or it projects to
+      #   a shape other than the stored one
       def shape_guard!(domain:, ordinal:, text:, stored_hash:, stored_projection: nil)
         bluebook = shadow(text)
         unless bluebook
@@ -27,7 +41,7 @@ module Hecks
                 "bluebook — a held era text is bootable source; restore a loadable text"
         end
 
-        # The stored PROJECTION is the preferred comparison: structural,
+        # The stored projection is the preferred comparison: structural,
         # version-free, and the same mechanism every boot trusts — so
         # this guard never depends on canonicalization stability, and a
         # future canonical-form version cannot make cosmetic edits to
@@ -57,6 +71,12 @@ module Hecks
               "under it; restore a text with the original shape"
       end
 
+      # Parses bluebook source in a scratch registry, through a temporary file that is
+      # removed afterwards, without touching the live registry.
+      #
+      # @param source [String] bluebook source text
+      # @return [Bluebook::Chapter, nil] the first bluebook the source declares; nil when it
+      #   declares none or fails to parse or load for any reason
       def shadow(source)
         file = Tempfile.new(["hecks-reattest-", ".bluebook"])
         file.write(source)