hecks 1.3.0 → 1.4.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
@@ -87,21 +110,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)

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

@@ -2,23 +2,22 @@ require "json"
 
 module Hecks
   module Translation
-    # The closed, PURE half of Postgres's own SQL compiler
-    # (adapters/driven/postgres_era/lineage/head_compiler.rb) — the part
-    # that turns one TranslationAggregate's declared rules into a
-    # jsonb-transforming SQL expression. No database connection, no
-    # watermark, no era chain, no catalog lookup: those stay exactly
-    # where they were, in head_compiler.rb's own per-mint assembly,
-    # which calls into this module instead of defining these methods
-    # itself.
+    # The closed, pure half of Postgres's own SQL compiler
+    # (ports/persistence/plugins/era/postgres_era/lineage/head_compiler.rb)
+    # — the part that turns one TranslationAggregate's declared rules into
+    # a jsonb-transforming SQL expression. No database connection, no
+    # watermark, no era chain, no catalog lookup: those live in
+    # head_compiler.rb's own per-mint assembly, which calls into this
+    # module instead of defining these methods itself.
     #
-    # Extracted here — not left as private methods on
-    # Adapters::PostgresEra::Lineage — so a SECOND, adapter-agnostic
+    # A module of its own — not private methods on
+    # Adapters::PostgresEra::Lineage — so a second, adapter-agnostic
     # caller (Exporter.translation_aggregate's build-time SQL export,
     # feeding rust/host's own future boot-time mint) can call the exact
-    # SAME code Ruby's own mint path runs, not a hand-ported duplicate
-    # that could silently drift the way `Exporter.translation_hash`
-    # drifted from `hecks_eras`/`hecks_approvals`' real schema before
-    # this file existed (rekeys/backfills were missing for years).
+    # same code Ruby's own mint path runs, not a hand-ported duplicate
+    # that could silently drift the way a hand-kept
+    # `Exporter.translation_hash` can drift from `hecks_eras`/
+    # `hecks_approvals`' real schema (leaving out rekeys and backfills).
     module RuleCompiler
       module_function
 
@@ -51,7 +50,7 @@ module Hecks
         expression
       end
 
-      # Whether THIS edge's declared rules for this aggregate include a
+      # Whether this edge's declared rules for this aggregate include a
       # rekey — checked directly off the raw IR object, the same way
       # every other rule kind is already read in `compile_rules`
       # (`declared.computes`, `declared.moves`, ...), not through the
@@ -60,16 +59,16 @@ module Hecks
       # module builds SQL straight off the IR either way.
       def rekeyed?(declared) = declared && !declared.rekeys.empty?
 
-      # THE ONLY TWO PLACES `aggregate_id` NEEDS TO CHANGE — guarded so
+      # The only two places `aggregate_id` needs to change — guarded so
       # the generated SQL for the overwhelming common case (no rekey
       # declared) stays the bare `aggregate_id` passthrough it always
-      # was — this CASE only appears in an edge that actually declares
+      # was — this case only appears in an edge that actually declares
       # one.
       def id_case(guard, declared)
         "CASE WHEN #{guard} THEN #{compile_id_expression(declared)} ELSE aggregate_id END AS aggregate_id"
       end
 
-      # THE REKEY'S OWN SQL — reading `state` directly, not the
+      # The rekey's own SQL — reading `state` directly, not the
       # progressively-built `expression` chain `compile_compute` reads
       # from. A rekey doesn't consume or move any field the way a move
       # or compute does, so there is no same-edge rename/move ordering
@@ -96,7 +95,7 @@ module Hecks
           "LATERAL (SELECT (__s ->> #{text_literal(from)}) AS #{quote(from)}) __fields)"
       end
 
-      # `PG::Connection.quote_ident` needs the `pg` gem LOADED, not
+      # `PG::Connection.quote_ident` needs the `pg` gem loaded, not
       # connected — required here, lazily, the same "a domain that
       # never wires PostgresEra should never need the gem" reasoning
       # `PostgresEra.connect_for`'s own `require "pg"` already holds

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/differ.rb

@@ -32,7 +32,7 @@ module Hecks
         end
 
         # A vanished aggregate whose full shape reappears under exactly one
-        # new name was renamed. `retired` is only confident when NOTHING
+        # new name was renamed. `retired` is only confident when nothing
         # remains it could plausibly have become — a vanished aggregate
         # beside an unmatched new one might be a rename-plus-reshape, and
         # writing `retired` there would be a guess that strands data.
@@ -61,7 +61,7 @@ module Hecks
         end
 
         # Every changed path in one aggregate, resolved into rules by
-        # signature matching over the FULL path set — top-level names and
+        # signature matching over the full path set — top-level names and
         # dotted members alike. Unique signature pair: a rename (both
         # top-level) or a move (any dotted end). Same path, same members,
         # new type name: a retype. Anything else: unresolved, carrying its
@@ -81,7 +81,7 @@ module Hecks
           appeared = appeared_paths(held_attrs, current_attrs, retyped)
 
           # Mutates `rules` in place (not build-and-concat, like the two
-          # passes above) because it must READ its own earlier writes:
+          # passes above) because it must read its own earlier writes:
           # `taken`, below, is recomputed from `rules` at the top of every
           # iteration, so a target this same loop already claimed for an
           # earlier vanished path is excluded from a later one. Passing a
@@ -92,7 +92,7 @@ module Hecks
         end
 
         # retype pass: same attribute name, same member structure, the
-        # TYPE's own name changed
+        # type's own name changed
         def retype_rules(held_attrs, current_attrs)
           (held_attrs.keys & current_attrs.keys).filter_map do |name|
             held = held_attrs[name]
@@ -166,7 +166,7 @@ module Hecks
           paths
         end
 
-        # THE ONE THING `attribute_rules` COULD NOT SEE BEFORE — the shape
+        # The one thing `attribute_rules` could not see before — the shape
         # projection already carries `"identity"` (`StorageShape
         # .project_aggregate`), it was simply never read here. An
         # unresolved placeholder, not a guess: `coverage_check.rb`'s own

data/lib/hecks/ports/persistence/plugins/era/translation/scaffold/writer.rb

@@ -8,7 +8,7 @@ module Hecks
       module Writer
         # The edge file, regenerated in place when one for the same shape
         # pair already exists (matched textually — an unresolved file
-        # cannot be LOADED to ask, that being the whole point of
+        # cannot be loaded to ask, that being the whole point of
         # unresolved).
         def write!(directory, edge)
           translations_dir = File.join(directory, "translations")

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

@@ -6,13 +6,13 @@ module Hecks
   module Translation
     # The scaffold writes translations; humans resolve ambiguity. It
     # diffs the held era's storage-shape projection against the current
-    # one (scaffold/differ.rb) and WRITES the edge file
+    # one (scaffold/differ.rb) and writes the edge file
     # (scaffold/renderer.rb, scaffold/writer.rb): confident rules inline
     # (unique signature pairs → rename/move, aggregate renames → `was:`,
     # type renames with identical members → retype, aggregates gone
     # without a successor → retired), ambiguities as parse-refusing
     # `unresolved` constructs — never comments, so an unresolved file can
-    # only boot into a refusal, never a guess. It NEVER proposes a
+    # only boot into a refusal, never a guess. It never proposes a
     # `compute` (a computation takes domain judgment no mechanical diff
     # can infer) — an empty-candidate `unresolved` is what points the
     # author there. It never proposes a `drop` either: data loss is a