hecks 2.8.0 → 2.9.0

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

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

@@ -4,20 +4,8 @@ require_relative "scaffold/writer"
 
 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
-    # (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
-    # `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
-    # decision, not a default. Re-running regenerates the file, matched
-    # by shape pair.
+    # Diffs the held era's storage shape against the current one and writes the edge file.
+    # Ambiguities become parse-refusing `unresolved` constructs; it never proposes compute or drop.
     module Scaffold
       Edge = Struct.new(:domain, :from, :to, :ordinal, :label, :aggregates, :retired, keyword_init: true)
       ScaffoldedAggregate = Struct.new(:name, :was, :rules, keyword_init: true)

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

@@ -11,34 +11,15 @@ module Hecks
   module Ports
     module Persistence
       module Plugins
-        # ADR 0033 — requiring this file is installing the plugin. Nothing in
-        # Hecks core requires it. A boot loads it on demand for a domain that
-        # binds `PostgresEra` (`Runtime::Loader.load_bound_adapters!` resolves the
-        # adapter, which autoloads this file, before the gates are collected). An
-        # app that wants schema-translation support without binding `PostgresEra`
-        # requires it explicitly, the same shape every adapter-specific spec
-        # fixture already uses to load one particular `.adapter` file rather than
-        # all of them.
+        # ADR 0033 — requiring this file installs the plugin; nothing in Hecks core
+        # requires it, so it loads only for a domain that binds `PostgresEra` (or asks explicitly).
         module Era
           module_function
 
           # Registers this plugin's era gates on one boot's gate list.
           #
-          # `Runtime::Loader.run_boot_gates!` asks every loaded persistence
-          # plugin to contribute here, generically — it never mentions
-          # `EraCheck` or "era" by name. Two gates, both `:pre_verify`:
-          #
-          # `:era_compute_rules` — unconditional, whenever this plugin is
-          # loaded at all. A `compute`/`rekey` rule requires Postgres
-          # whatever adapter is actually bound (ADR 0031's own reasoning,
-          # unchanged) — this is the rich, adapter-aware version of that
-          # check; `Runtime::Loader`'s own structural backstop (plain
-          # `Bluebook::Translation` data, no plugin-specific class) only
-          # ever fires when no persistence plugin is loaded at all.
-          #
-          # `:era_check` — conditional, exactly ADR 0031's own gate,
-          # unchanged: registered only when this registry has an aggregate
-          # actually bound to a lineage-capable adapter.
+          # Two `:pre_verify` gates: `era_compute_rules` always runs; `era_check` (ADR 0031)
+          # runs only when the registry binds something lineage-capable.
           #
           # @param registry [Runtime::Registry] the registry being booted, asked whether any
           #   bluebook's first aggregate is bound to a lineage-capable adapter

data/lib/hecks/ports/persistence/postgres_dump/connection.rb

@@ -4,39 +4,28 @@ module Hecks
   module Ports
     module Persistence
       class PostgresDump
-        # A Postgres connection URL, split so a password reaches the tools run
-        # against it through their environment and never on a command line, where
-        # any user of the machine can read it from the process list.
+        # A Postgres connection URL, split so a password reaches child-process tools
+        # through their environment, never on a command line the process list exposes.
         class Connection
-          # @param url [String] a `postgres://` or `postgresql://` URL
-          # @raise [PostgresDump::Error] if `url` is not a Postgres URL
           def initialize(url)
             @uri = URI.parse(url)
             raise Error, "not a postgres URL" unless %w[postgres postgresql].include?(@uri.scheme)
           end
 
-          # Names the database the URL points at.
-          #
-          # @return [String] the database name, empty when the URL names none
+          # Names the database the URL points at, empty when the URL names none.
           def database
             @uri.path.to_s.delete_prefix("/")
           end
 
-          # Points the same server and credentials at another database.
-          #
-          # @param name [String] the database to connect to instead
-          # @return [Connection] a new connection; this one is unchanged
+          # Points the same server and credentials at another database; this one is unchanged.
           def with_database(name)
             copy = @uri.dup
             copy.path = "/#{name}"
             self.class.new(copy.to_s)
           end
 
-          # Lists the connection settings the URL carries, in `PG.connect` keyword form.
-          #
-          # @return [Hash{Symbol => String, Integer}] `host`, `port`, `user`, `password`,
-          #   `dbname` and `sslmode`, each only when the URL gives one; the user and password
-          #   are percent-decoded
+          # Lists the connection settings the URL carries, in `PG.connect` keyword form; the
+          # user and password come back percent-decoded.
           def settings
             {
               host: (@uri.host unless @uri.host.to_s.empty?), port: @uri.port,
@@ -46,16 +35,11 @@ module Hecks
           end
 
           # Builds the libpq environment variables for a child process.
-          #
-          # @return [Hash{String => String}] `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`,
-          #   `PGDATABASE` and `PGSSLMODE`, each only when `settings` has the matching key
           def env
             settings.to_h { |key, value| ["PG#{key.to_s.sub('dbname', 'database').upcase}", value.to_s] }
           end
 
-          # Opens a connection with the `pg` gem.
-          #
-          # @return [PG::Connection] an open connection; the caller closes it
+          # Opens a connection with the `pg` gem; the caller closes it.
           def connect
             require "pg"
             PG.connect(**settings)