hecks 2.8.0 → 3.0.0

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

@@ -5,70 +5,73 @@ 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
-    # (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;
-    # this is operator-initiated repair, where a false negative is a
-    # loud refusal, never a silent misread.
+    # Decides whether an edited era text changed the era's shape or only its text.
+    # A shape change refuses hard; no --accept flag gets past it.
     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.
+      # Says how an edited era text stands against the shape the era was frozen with, without
+      # refusing anything: the facts `Era.Permit`'s givens hold, and what `shape_guard!` raises on.
+      #
+      # @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 if unnamed
+      # @param stored_projection [Hash{String => Object}, nil] the stored
+      #   `Runtime::StorageShape.project` result as parsed JSON; nil when absent
+      # @return [Symbol] `:cosmetic` when the shape is unchanged, `:unnamed` when neither a
+      #   projection nor a hash is stored, `:changed` when the text projects to another shape,
+      #   `:unloadable` when the text does not load as a bluebook
+      def verdict(text:, stored_hash:, stored_projection: nil)
+        bluebook = shadow(text)
+        return :unloadable unless bluebook
+
+        # The stored projection is compared first: it is version-free, so a new canonical form
+        # cannot make a cosmetic edit look like a shape change. The hash is the fallback.
+        if stored_projection
+          edited = JSON.parse(JSON.generate(Runtime::StorageShape.project(bluebook)))
+          return edited == stored_projection ? :cosmetic : :changed
+        end
+        return :unnamed unless stored_hash
+
+        Runtime::StorageShape.mint_hash(bluebook) == stored_hash ? :cosmetic : :changed
+      end
+
+      # Refuses an edited era text that projects to another shape than the era froze with.
       #
       # @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
+      # @param stored_hash [String, nil] the era's minted shape hash (SHA-256 hex); nil if unnamed
+      # @param stored_projection [Hash{String => Object}, nil] the stored
+      #   `Runtime::StorageShape.project` result as parsed JSON; nil when absent
       # @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
+      #   projection nor a hash is stored
+      # @raise [Runtime::WiringError] if `text` does not load, or projects to another shape
       def shape_guard!(domain:, ordinal:, text:, stored_hash:, stored_projection: nil)
-        bluebook = shadow(text)
-        unless bluebook
+        found = verdict(text: text, stored_hash: stored_hash, stored_projection: stored_projection)
+        return found if %i[cosmetic unnamed].include?(found)
+
+        if found == :unloadable
           raise Runtime::WiringError,
                 "cannot re-attest era #{ordinal} of #{domain}: the edited text does not load as a " \
                 "bluebook — a held era text is bootable source; restore a loadable text"
         end
+        raise Runtime::WiringError, changed_shape_message(domain, ordinal, text, stored_hash, stored_projection)
+      end
 
-        # 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
-        # old-form eras false-refuse as shape changes. The hash path
-        # survives only as a fallback for stores that predate stored
-        # projections.
+      # The refusal for an edit that changed the era's shape.
+      #
+      # @return [String] names the minted label when the era was compared by hash
+      def changed_shape_message(domain, ordinal, text, stored_hash, stored_projection)
+        head = "cannot re-attest era #{ordinal} of #{domain}: the edit changed the era's SHAPE, not just "
+        tail = "Attesting would retroactively redefine what era #{ordinal} meant for data already written " \
+               "under it; restore a text with the original shape"
         if stored_projection
-          edited = JSON.parse(JSON.generate(Runtime::StorageShape.project(bluebook)))
-          return :cosmetic if edited == stored_projection
-
-          raise Runtime::WiringError,
-                "cannot re-attest era #{ordinal} of #{domain}: the edit changed the era's SHAPE, not just " \
-                "its text — the text no longer projects to the shape frozen for era #{ordinal}. " \
-                "Attesting would retroactively redefine what era #{ordinal} meant for data already written " \
-                "under it; restore a text with the original shape"
+          return "#{head}its text — the text no longer projects to the shape frozen for era #{ordinal}. #{tail}"
         end
-        return :unnamed unless stored_hash
-
-        computed = Runtime::StorageShape.mint_hash(bluebook)
-        return :cosmetic if computed == stored_hash
 
-        raise Runtime::WiringError,
-              "cannot re-attest era #{ordinal} of #{domain}: the edit changed the era's SHAPE, not just " \
-              "its text — its name #{stored_hash[0, Runtime::StorageShape::LABEL_LENGTH]} was minted from " \
-              "a different shape (the text now projects to #{computed[0, Runtime::StorageShape::LABEL_LENGTH]}). " \
-              "Attesting would retroactively redefine what era #{ordinal} meant for data already written " \
-              "under it; restore a text with the original shape"
+        label = Runtime::StorageShape::LABEL_LENGTH
+        "#{head}its text — its name #{stored_hash[0, label]} was minted from a different shape (the text " \
+          "now projects to #{Runtime::StorageShape.mint_hash(shadow(text))[0, label]}). #{tail}"
       end
 
       # Parses bluebook source in a scratch registry, through a temporary file that is

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

@@ -2,37 +2,13 @@ require "json"
 
 module Hecks
   module Translation
-    # 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.
-    #
-    # 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 a hand-kept
-    # `Exporter.translation_hash` can drift from `hecks_eras`/
-    # `hecks_approvals`' real schema (leaving out rekeys and backfills).
+    # Compiles one TranslationAggregate's declared rules into a jsonb-transforming SQL
+    # expression, shared by Ruby's own mint path and any other SQL-emitting caller.
     module RuleCompiler
       module_function
 
-      # One edge's rules over one jsonb state, compiled as a nested
-      # expression tree — hecks_tr_* helpers composed innermost-first
-      # in the reference transform's phase order (renames, moves,
-      # converts, drops), computes last. `retype` compiles to nothing:
-      # stored state never carries a type name.
-      # Compiles a declared edge's rename/move/convert/drop/compute rules into one nested SQL
-      # expression over the `state` jsonb column.
-      #
-      # @param declared [Bluebook::TranslationAggregate] this edge's declared rules for one
-      #   aggregate
-      # @return [String] a SQL expression, `"state"` unchanged when `declared` declares none
-      #   of the five rule kinds
+      # Compiles one edge's rename/move/convert/drop/compute/backfill rules into a nested
+      # SQL expression over `state`, composed innermost-first in that phase order.
       def compile_rules(declared)
         expression = "state"
         declared.renames.each do |old_name, new_name|
@@ -54,85 +30,33 @@ module Hecks
         declared.computes.each do |compute|
           expression = compile_compute(expression, compute)
         end
-        # Backfills last, same order `Lineage#translate` already applies
-        # in-process (that method's own comment: "only where nothing
-        # already answered") — now compiled here too, closing the gap
-        # this rule kind otherwise leaves: `rust/host`'s boot-time mint
-        # audit reads this exact compiled expression, never
-        # `Lineage#translate`, so it cannot see a backfilled value unless
-        # backfills compile to SQL like every other rule kind here. A
-        # real, live gap for any new required value-object member with no
-        # source data at all — `compute` cannot fill it either, since its
-        # own guard requires a real, already-present field to consume
-        # (found live: a client site's Attendee redesign, commit 4326dcd,
-        # needed exactly this and had nothing that worked).
+        # Backfilled last, same order as `Lineage#translate`'s in-process pass, so the
+        # boot-time mint audit (which reads only this compiled SQL) sees the same result.
         declared.backfills.each do |backfill|
           expression = compile_backfill(expression, backfill)
         end
         expression
       end
 
-      # 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
-      # `Ports::Persistence::Lineage` wrapper the app-level consumers
-      # (coverage_check.rb, minter.rb, layer_two.rb) go through — this
-      # module builds SQL straight off the IR either way.
-      # Reports whether an edge's declared rules for an aggregate include a rekey.
-      #
-      # @param declared [Bluebook::TranslationAggregate, nil] this edge's declared rules for
-      #   one aggregate; nil for an aggregate the edge declares nothing about
-      # @return [Boolean] true when `declared` is present and its `rekeys` is non-empty
+      # Reports whether an edge's declared rules for an aggregate include a rekey, read
+      # directly off the raw IR like every other rule kind `compile_rules` checks.
       def rekeyed?(declared) = declared && !declared.rekeys.empty?
 
-      # 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
-      # one.
-      #
-      # @param guard [String] a SQL boolean expression gating when the rekey applies, such as
-      #   `"operation = 'save'"`
-      # @param declared [Bluebook::TranslationAggregate] this edge's declared rules; must
-      #   declare a rekey (`rekeyed?(declared)` true)
-      # @return [String] a `"CASE WHEN ... END AS aggregate_id"` SQL expression
+      # Builds a `CASE WHEN ... END AS aggregate_id` expression that only overrides
+      # `aggregate_id` when `guard` matches, leaving the common no-rekey case untouched.
       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
-      # 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
-      # it needs to see first — it reads the record's stored fields
-      # exactly as they already are, the same `__s` convention
-      # `compile_compute` exposes.
-      #
-      # @param declared [Bluebook::TranslationAggregate] this edge's declared rules; its
-      #   first `rekeys` entry supplies the SQL
-      # @return [String] a SQL expression evaluating the rekey's own SQL against the record's
-      #   current `state`
+      # Evaluates a rekey's own SQL against the record's current `state`, read directly
+      # rather than through `compile_rules`'s progressively-built expression chain.
       def compile_id_expression(declared)
         rekey = declared.rekeys.first
         "(SELECT (#{rekey.sql}) FROM (SELECT (state) AS __s) __outer)"
       end
 
-      # A compute is the one rule whose SQL is its only implementation
-      # — evaluated exclusively inside the compiled head, never
-      # in-process. The source is read as a path through
-      # `hecks_tr_extract`, bare or a dotted value-object member alike,
-      # the same way the destination goes through `path_literal`. The
-      # source's value is exposed to the author's SQL as text under a
-      # column named by the source exactly as declared (`price_cents`,
-      # or `"price.cents"` for a dotted member), and the whole record
-      # stays readable as `__s`.
-      #
-      # @param expression [String] the SQL expression built so far by `compile_rules`, read as
-      #   `__s` inside the compute's own SQL
-      # @param compute [Bluebook::TranslationCompute] the declared compute rule
-      # @return [String] `expression` wrapped so the compute's field lands at its declared
-      #   destination when the source path is present, unchanged otherwise
+      # Wraps `expression` so a compute's SQL result lands at its declared destination
+      # when the source path is present; the whole record stays readable as `__s`.
       def compile_compute(expression, compute)
         from = compute.from.to_s
         to = compute.to.to_s
@@ -145,23 +69,8 @@ module Hecks
           "LATERAL (SELECT (__s #>> #{path_literal(from)}) AS #{quote(from)}) __fields)"
       end
 
-      # A newly added, required attribute with no source at all — the
-      # addition-side sibling of `compile_compute`'s own header, but with
-      # no field to consume: `hecks_tr_extract`'s own `.present` flag
-      # (already installed for `hecks_tr_drop`/`hecks_tr_move`/
-      # `hecks_tr_convert` — no new database function needed) answers
-      # "is this path — bare or a dotted value-object member alike —
-      # already there," and `hecks_tr_insert` (already merge-safe: it
-      # creates a missing intermediate container without disturbing any
-      # sibling member already in it) fills it only when it is not, the
-      # exact "never overwrites a value already there" rule `Lineage#
-      # translate`'s own in-process backfill already holds itself to.
-      #
-      # @param expression [String] the SQL expression built so far by `compile_rules`, read as
-      #   `__s` inside this backfill's own check
-      # @param backfill [Bluebook::TranslationBackfill] the declared backfill rule
-      # @return [String] `expression` wrapped so the backfill's default lands at its declared
-      #   path when nothing is there yet, unchanged otherwise
+      # Wraps `expression` so a backfill's default lands at its declared path only when
+      # nothing is already there, the same rule `Lineage#translate`'s own pass holds to.
       def compile_backfill(expression, backfill)
         name = backfill.name.to_s
         default_json = JSON.generate(backfill.default)
@@ -171,32 +80,17 @@ module Hecks
           "FROM (SELECT (#{expression}) AS __s) __outer)"
       end
 
-      # `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
-      # itself to, so a build tool that exports translations for a
-      # non-Postgres-bound domain (there are none today, but nothing
-      # here should assume there never will be) doesn't gain a hard
-      # dependency on `pg` just by loading this file.
-      #
-      # @param name [String, Symbol] the identifier to quote
-      # @return [String] `name` as a double-quoted Postgres identifier
+      # Quotes a Postgres identifier; requires "pg" lazily so a non-Postgres-bound
+      # domain never gains a hard dependency on the gem just by loading this file.
       def quote(name)
         require "pg"
         PG::Connection.quote_ident(name.to_s)
       end
 
       # Renders a Ruby value as a single-quoted SQL text literal, escaping embedded quotes.
-      #
-      # @param text [String, Symbol, Object] the value to render; converted with `to_s`
-      # @return [String] a single-quoted SQL literal
       def text_literal(text) = "'#{text.to_s.gsub("'", "''")}'"
 
       # Renders a dotted path as a SQL `text[]` array literal, one element per segment.
-      #
-      # @param path [String, Symbol] a bare or dotted path, such as `"price.cents"`
-      # @return [String] a SQL `ARRAY[...]::text[]` expression
       def path_literal(path)
         segments = path.to_s.split(".").map { |segment| text_literal(segment) }
         "ARRAY[#{segments.join(', ')}]::text[]"

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

@@ -3,18 +3,16 @@ require_relative "../../storage_shape"
 module Hecks
   module Translation
     module Scaffold
-      # Diff two eras' storage-shape projections into the edge's
-      # declarations — confident rules by unique signature pairing,
-      # everything ambiguous left unresolved for a human.
+      # Diffs two eras' storage shapes into the edge's declarations; rules are written only
+      # for unique signature pairs, everything else is left unresolved.
       module Differ
-        # Diff two bluebook IRs into the edge's declarations.
+        # Diffs two bluebook IRs into the edge's declarations.
         #
         # @param held_bluebook [Bluebook::Chapter] the era being translated from
         # @param current_bluebook [Bluebook::Chapter] the era being translated to
-        # @return [Hash{Symbol => Object}] `:aggregates` (Array<Scaffold::ScaffoldedAggregate>,
-        #   one per matched aggregate carrying a rename or a rule), `:retired` (Array<String>,
-        #   vanished aggregate names with no successor), `:unclaimed` (Array<String>, vanished
-        #   aggregate names left ambiguous)
+        # @return [Hash{Symbol => Object}] `:aggregates` (Array<Scaffold::ScaffoldedAggregate>),
+        #   `:retired` (Array<String>, vanished names with no successor), `:unclaimed`
+        #   (Array<String>, vanished names left ambiguous)
         def diff(held_bluebook, current_bluebook)
           held_shapes = projections(held_bluebook)
           current_shapes = projections(current_bluebook)
@@ -34,31 +32,19 @@ module Hecks
           { aggregates: aggregates, retired: matched[:retired], unclaimed: matched[:unclaimed] }
         end
 
-        # Projects a bluebook's storage shape and indexes its aggregates by name.
-        #
-        # @param bluebook [Bluebook::Chapter] the bluebook to project
-        # @return [Hash{String => Hash}] the bluebook's storage-shape aggregates (see
-        #   `Runtime::StorageShape.project`), keyed by aggregate name
+        # Projects a bluebook's storage shape, indexing its aggregates by name.
         def projections(bluebook)
           Runtime::StorageShape.project(bluebook)["aggregates"].to_h { |shape| [shape["name"], shape] }
         end
 
-        # A vanished aggregate whose full shape reappears under exactly one
-        # new name counts as a rename. `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.
-        # Anything ambiguous stays unclaimed, and the coverage gate names
-        # it until a human decides.
+        # Pairs vanished aggregates with new ones whose full shape reappears under exactly one
+        # name. A vanished aggregate is `retired` only when no unmatched new one remains, since
+        # it could be a rename-plus-reshape and guessing would strand data.
         #
-        # @param held_shapes [Hash{String => Hash}] the held era's aggregate shapes, keyed by
-        #   name (see `projections`)
-        # @param current_shapes [Hash{String => Hash}] the current era's aggregate shapes,
-        #   keyed by name
-        # @return [Hash{Symbol => Object}] `:pairs` (Hash{String => String, nil}, each current
-        #   name to its matched held name, or nil when unmatched), `:retired` (Array<String>,
-        #   vanished names with no successor), `:unclaimed` (Array<String>, vanished names
-        #   left ambiguous)
+        # @param held_shapes [Hash{String => Hash}] held aggregate shapes, keyed by name
+        # @param current_shapes [Hash{String => Hash}] current aggregate shapes, keyed by name
+        # @return [Hash{Symbol => Object}] `:pairs` (current name to held name, or nil),
+        #   `:retired` (Array<String>), `:unclaimed` (Array<String>)
         def match_aggregates(held_shapes, current_shapes)
           pairs = {}
           current_shapes.each_key { |name| pairs[name] = held_shapes.key?(name) ? name : nil }
@@ -81,20 +67,14 @@ module Hecks
           { pairs: pairs, retired: retired, unclaimed: retired.empty? ? unclaimed : [] }
         end
 
-        # Every changed path in one aggregate, resolved into rules by
-        # 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
-        # type-compatible candidates (an empty list is the arrow toward
-        # compute, or drop).
+        # Resolves every changed path in one aggregate into rules by signature matching:
+        # a unique pair is a rename (both top-level) or a move (any dotted end), same members
+        # under a new type name is a retype, anything else is unresolved with its candidates.
         #
-        # @param held_shape [Hash{String => Object}] the held era's aggregate shape (see
-        #   `projections`)
+        # @param held_shape [Hash{String => Object}] the held era's aggregate shape
         # @param current_shape [Hash{String => Object}] the current era's aggregate shape
-        # @return [Array<Hash{Symbol => Object}>] one rule Hash per changed path — `:kind`
-        #   plus `:from`/`:to` for `:rename`/`:move`/`:retype`, or `:from`/`:candidates` for
-        #   `:unresolved` (see `Renderer#render_rule`); `[]` when nothing changed
+        # @return [Array<Hash{Symbol => Object}>] one rule per changed path (see
+        #   `Renderer#render_rule`); `[]` when nothing changed
         def attribute_rules(held_shape, current_shape)
           rules = []
           rules << identity_hint(held_shape, current_shape)
@@ -108,26 +88,13 @@ module Hecks
           vanished = vanished_paths(held_attrs, current_attrs, retyped)
           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:
-          # `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
-          # snapshot instead of the live array would let two vanished
-          # paths both match the same appeared target.
+          # Mutates `rules` in place: each iteration must see targets claimed by earlier ones,
+          # or two vanished paths could match the same appeared target.
           resolve_vanished_rules!(rules, vanished, appeared)
           rules
         end
 
-        # retype pass: same attribute name, same member structure, the
-        # type's own name changed
-        #
-        # @param held_attrs [Hash{String => Hash}] the held era's attributes, keyed by name
-        # @param current_attrs [Hash{String => Hash}] the current era's attributes, keyed by
-        #   name
-        # @return [Array<Hash{Symbol => String}>] one `{kind: :retype, from:, to:}` rule per
-        #   attribute whose members are unchanged but whose type name changed; `[]` when none
-        #   match
+        # Retype rules for attributes whose members are unchanged but whose type name changed.
         def retype_rules(held_attrs, current_attrs)
           (held_attrs.keys & current_attrs.keys).filter_map do |name|
             held = held_attrs[name]
@@ -140,16 +107,7 @@ module Hecks
           end
         end
 
-        # Resolves each vanished path into a rename, move or unresolved rule, appended to
-        # `rules` in place.
-        #
-        # @param rules [Array<Hash{Symbol => Object}>] the rule list to append to; also read
-        #   for `:rename`/`:move` targets an earlier iteration already claimed
-        # @param vanished [Hash{String => Object}] vanished paths to type signature (see
-        #   `vanished_paths`)
-        # @param appeared [Hash{String => Object}] appeared paths to type signature (see
-        #   `appeared_paths`)
-        # @return [void]
+        # Resolves each vanished path into a rename, move or unresolved rule appended to `rules`.
         def resolve_vanished_rules!(rules, vanished, appeared)
           vanished.each do |path, signature|
             matches = appeared.select { |_, candidate| candidate == signature }.keys
@@ -166,18 +124,9 @@ module Hecks
           end
         end
 
-        # Held paths that need explaining: whole attributes that vanished,
-        # and members that vanished (or changed type) inside a kept
-        # attribute — mirroring exactly what EraGuard will demand coverage
-        # for.
-        #
-        # @param held_attrs [Hash{String => Hash}] the held era's attributes, keyed by name
-        # @param current_attrs [Hash{String => Hash}] the current era's attributes, keyed by
-        #   name
-        # @param retyped [Array<String>] type names already claimed by a `:retype` rule,
-        #   excluded here
-        # @return [Hash{String => Object}] each vanished or changed path, dotted for a member,
-        #   valued by that path's type signature
+        # Held paths that need explaining: vanished attributes, and members that vanished or
+        # changed type inside a kept attribute — the set EraGuard demands coverage for.
+        # Returns each path (dotted for a member) valued by its type signature.
         def vanished_paths(held_attrs, current_attrs, retyped)
           paths = {}
           held_attrs.each do |name, held|
@@ -199,17 +148,7 @@ module Hecks
           paths
         end
 
-        # Current paths that need explaining: whole attributes that appeared, and members
-        # that appeared (or changed type) inside a kept attribute — the mirror of
-        # `vanished_paths`.
-        #
-        # @param held_attrs [Hash{String => Hash}] the held era's attributes, keyed by name
-        # @param current_attrs [Hash{String => Hash}] the current era's attributes, keyed by
-        #   name
-        # @param retyped [Array<String>] type names already claimed by a `:retype` rule,
-        #   excluded here
-        # @return [Hash{String => Object}] each appeared or changed path, dotted for a
-        #   member, valued by that path's type signature
+        # Current paths that need explaining; the mirror of `vanished_paths`.
         def appeared_paths(held_attrs, current_attrs, retyped)
           paths = {}
           current_attrs.each do |name, current|
@@ -230,58 +169,30 @@ module Hecks
           paths
         end
 
-        # 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
-        # `check_identity_unchanged!` is the real gate this only hints
-        # toward, the same "tool proactively guides you" pattern the
-        # generic unresolved message already gives unfed fields.
-        #
-        # @param held_shape [Hash{String => Object}] the held era's aggregate shape
-        # @param current_shape [Hash{String => Object}] the current era's aggregate shape
-        # @return [Hash{Symbol => Object}, nil] `{kind: :unresolved, from: :identity,
-        #   candidates: []}` when the identity paths differ; nil when they match
+        # An unresolved placeholder when the identity paths differ; nil when they match.
+        # It only hints: `check_identity_unchanged!` in `coverage_check.rb` is the real gate.
         def identity_hint(held_shape, current_shape)
           return if held_shape["identity"] == current_shape["identity"]
 
           { kind: :unresolved, from: :identity, candidates: [] }
         end
 
-        # Finds appeared paths type-compatible with a vanished path's own signature.
-        #
-        # @param appeared [Hash{String => Object}] appeared paths to type signature (see
-        #   `appeared_paths`)
-        # @param signature [Object] the vanished path's own type signature to match against
-        # @return [Array<String>] appeared paths whose scalar signature (see `scalar_of`)
-        #   matches `signature`'s
+        # Appeared paths type-compatible with a vanished path's signature.
         def compatible_candidates(appeared, signature)
           appeared.select { |_, candidate| scalar_of(candidate) == scalar_of(signature) }.keys
         end
 
-        # Reduces a type signature to the shape `compatible_candidates` compares by.
-        #
-        # @param signature [Object, Hash] a path's type signature
-        # @return [Object] `signature["members"]` for a container Hash, else `signature`
-        #   unchanged
+        # Reduces a type signature to what `compatible_candidates` compares: members or the scalar.
         def scalar_of(signature) = signature.is_a?(Hash) ? signature["members"] : signature
 
-        # Reads a container attribute's own members, keyed by name.
-        #
-        # @param attribute [Hash{String => Object}] one path's type signature
-        # @return [Hash{String => Object}] each member's name to its type; `{}` when
-        #   `attribute` is not a container
+        # A container attribute's members keyed by name; `{}` for a scalar.
         def members_of(attribute)
           return {} unless container?(attribute)
 
           attribute["type"]["members"].to_h { |member| [member["name"], member["type"]] }
         end
 
-        # Reports whether a type signature is a container (value object or entity), not a
-        # scalar.
-        #
-        # @param attribute [Hash{String => Object}] one path's type signature
-        # @return [Boolean] true if `attribute["type"]` is a Hash, false for a scalar
+        # Whether the attribute's type is a container (value object or entity), not a scalar.
         def container?(attribute) = attribute["type"].is_a?(Hash)
       end
     end

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

@@ -1,14 +1,13 @@
 module Hecks
   module Translation
     module Scaffold
-      # Render an edge into .bluebook text — confident rules inline,
-      # ambiguities as parse-refusing `unresolved` constructs, never
+      # Renders an edge as .bluebook text. Ambiguities become `unresolved` constructs, not
       # comments, so an unresolved file can only boot into a refusal.
       module Renderer
         # Renders a scaffolded edge as loadable `.bluebook` translation source.
         #
         # @param edge [Scaffold::Edge] the edge to render
-        # @return [String] the edge's `.bluebook` text, ending in a newline
+        # @return [String] the `.bluebook` text, ending in a newline
         def render(edge)
           lines = ["Hecks.data_translation #{edge.domain.inspect}, from: #{edge.from.inspect}, to: #{edge.to.inspect} do"]
           edge.aggregates.each do |aggregate|
@@ -25,10 +24,8 @@ module Hecks
 
         # Renders one scaffolded rule as a line of `.bluebook` source.
         #
-        # @param rule [Hash{Symbol => Object}] a rule Hash as `Differ#attribute_rules` builds
-        #   it: `:kind` plus `:from`/`:to`, or `:from`/`:candidates` for `:unresolved`
-        # @return [String, nil] the rendered line; nil if `rule[:kind]` is none of `:rename`,
-        #   `:move`, `:retype` or `:unresolved`
+        # @param rule [Hash{Symbol => Object}] a rule as `Differ#attribute_rules` builds it
+        # @return [String, nil] the rendered line; nil for an unknown `rule[:kind]`
         def render_rule(rule)
           case rule[:kind]
           when :rename then "rename :#{rule[:from]}, to: :#{rule[:to]}"
@@ -40,11 +37,7 @@ module Hecks
           end
         end
 
-        # Renders a path as bluebook source: a Symbol literal when bare, a String literal
-        # when dotted.
-        #
-        # @param path [String, Symbol] a bare or dotted path
-        # @return [String] `":name"` for a bare path, `path.inspect` for a dotted one
+        # Renders a bare path as a Symbol literal and a dotted path as a String literal.
         def render_path(path) = path.to_s.include?(".") ? path.to_s.inspect : ":#{path}"
       end
     end

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

@@ -3,16 +3,10 @@ require "fileutils"
 module Hecks
   module Translation
     module Scaffold
-      # Put the rendered edge on disk, regenerating in place when a file
-      # for the same shape pair already exists.
+      # Writes the rendered edge to disk, reusing the file for the same shape pair if present.
       module Writer
-        # Renders an edge and writes it under `directory/translations`, regenerating in
-        # place when a file for the same shape pair already exists.
-        #
-        # 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
-        # unresolved).
+        # Renders an edge and writes it under `directory/translations`.
+        # An existing file is matched textually because an unresolved file cannot be loaded.
         #
         # @param directory [String] the domain's root directory
         # @param edge [Scaffold::Edge] the edge to render and write