hecks 1.3.0 → 1.5.0

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/coverage_check.rb

@@ -10,12 +10,26 @@ module Hecks
       module LineageManager
         # What a mint must prove before it may happen: the edge covers
         # the whole diff, no identity path was re-keyed, and the audit's
-        # first two layers pass over the LIVE compiled chain.
+        # first two layers pass over the live compiled chain.
         module CoverageCheck
-          # Layer 1 against THIS edge specifically: every vanished or
+          # Refuses a mint whose translation edge leaves any part of the shape change
+          # unexplained.
+          #
+          # Layer 1 against this edge specifically: every vanished or
           # retyped path in the held→current diff must be explained, and
           # every held aggregate must still be claimed. The refusal is
           # EraGuard's own, byte for byte.
+          #
+          # @param registry [Runtime::Registry] the registry whose loaded translations may
+          #   claim a held aggregate through `was:` or `retired`
+          # @param bluebook [Bluebook::Chapter] the domain as currently declared
+          # @param held_bluebook [Bluebook::Chapter] the domain as the latest held era's
+          #   text declares it (a shadow parse)
+          # @param edge [Bluebook::Translation] the one edge leaving the latest held era
+          # @return [void]
+          # @raise [Runtime::WiringError] if an identity path changed without a `rekey`
+          #   rule, a vanished or retyped path has no rule, a new required attribute has
+          #   nothing to fill it, or a held aggregate is neither renamed nor retired
           def check_coverage!(registry, bluebook, held_bluebook, edge)
             bluebook.aggregates.each do |aggregate|
               rules = Ports::Persistence::Lineage.from_declared(edge.for_aggregate(aggregate.name), aggregate.name)
@@ -32,15 +46,28 @@ module Hecks
             Runtime::EraGuard.check_vanished_aggregates!(registry, bluebook, held_bluebook)
           end
 
-          # An identity-path change is a RE-KEYING, not an ordinary
+          # Refuses a mint that changes an aggregate's identity paths without declaring
+          # a `rekey`.
+          #
+          # An identity-path change is a re-keying, not an ordinary
           # translation — stored ids were fixed at write time under the old
-          # key, so this refuses UNLESS the edge declares a `rekey` for
+          # key, so this refuses unless the edge declares a `rekey` for
           # this aggregate covering exactly that. `rules.rekey?` (see
           # `Ports::Persistence::Lineage`'s own comment) is the single
           # source of truth every consumer of this fact asks — this is not
           # a second, independent check of `declared.rekeys`.
+          #
+          # @param bluebook [Bluebook::Chapter] the domain, named in the refusal
+          # @param aggregate [Bluebook::Aggregate] the aggregate as currently declared
+          # @param held_aggregate [Bluebook::Aggregate] the same aggregate as the held
+          #   era's text declares it
+          # @param rules [Ports::Persistence::Lineage, nil] the edge's rules for this
+          #   aggregate; nil when the edge declares none, which cannot excuse a change
+          # @return [nil] when the identity paths are unchanged or a `rekey` covers them
+          # @raise [Runtime::WiringError] if the identity paths differ and no `rekey` rule
+          #   is declared
           def check_identity_unchanged!(bluebook, aggregate, held_aggregate, rules)
-            # The FULL declared path lists, in declaration order — never the
+            # The full declared path lists, in declaration order — never the
             # single-head shortcut, which is nil for every composite identity
             # and so would let two different composites compare as unchanged.
             return if held_aggregate.identity_paths == aggregate.identity_paths
@@ -56,10 +83,28 @@ module Hecks
                   "data explicitly"
           end
 
-          # Layers 1 and 2 of the audit, over the LIVE compiled chain —
+          # Previews every aggregate's translated head through the pending chain and
+          # refuses the mint if the audit finds a violation.
+          #
+          # Layers 1 and 2 of the audit, over the live compiled chain —
           # before anything is minted, so a refusal leaves no half-born
           # era. (A convert meeting an unmapped value raises inside the
           # preview query itself: same rollback-shaped outcome.)
+          #
+          # @param bluebook [Bluebook::Chapter] the domain as currently declared
+          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, on an open
+          #   connection
+          # @param chain [Array<Hash{Symbol => Bluebook::Translation}>] the full edge chain
+          #   ending in `edge`, as `edge_chain` returns it
+          # @param ordinal [Integer] the ordinal of the era about to be minted
+          # @param edge [Bluebook::Translation] the pending edge, whose per-aggregate rules
+          #   the audit checks
+          # @return [nil] when no aggregate reports a violation
+          # @raise [Runtime::WiringError] if Postgres refuses the translated preview query
+          #   (a `convert` meeting an unmapped value, for one), or the audit reports any
+          #   violation; the message lists them all
+          # @raise [PG::Error] if Postgres refuses the "before" query; only the translated
+          #   preview is rescued into a `Runtime::WiringError`
           def audit!(bluebook, lineage, chain, ordinal, edge)
             violations = []
             bluebook.aggregates.each do |aggregate|

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/era_resolver.rb

@@ -5,12 +5,15 @@ module Hecks
   module Adapters
     class PostgresEra
       module LineageManager
-        # The boot-time resolution: which era IS this checkout? First
+        # The boot-time resolution: which era is this checkout? First
         # boot holds era 1; a quiet reboot changes nothing; a
         # held-but-superseded shape boots read-only-toward-the-fence; an
         # unheld shape goes to the minter.
         module EraResolver
           # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+          # Resolves which era this boot is and records it on the registry, holding era 1
+          # on a first boot and minting the next era when the shape is one no era holds.
+          #
           # A single order-dependent dispatch over a closed set of four
           # boot scenarios (first boot / quiet reboot / held-but-superseded
           # / unheld-shape-goes-to-minter), each already explained by its
@@ -18,11 +21,32 @@ module Hecks
           # `ensure`. Splitting the branches into separate methods would
           # turn each `return` (which exits `check!`, closing `db`) into a
           # sentinel value threaded back up, obscuring the mutual
-          # exclusivity that IS the method's whole point.
+          # exclusivity that is the method's whole point.
+          #
+          # @param registry [Runtime::Registry] the booting registry; `resolved_eras` gets
+          #   this domain's ordinal on every path but a first boot (where the adapter
+          #   self-resolves to era 1), and `superseded_eras` gets the newest ordinal when
+          #   this checkout's shape is held but superseded
+          # @param bluebook [Bluebook::Chapter] the domain being booted
+          # @param current_text [String] the domain's bluebook source as it stands on disk,
+          #   held verbatim as the new era's text on a first boot or a mint
+          # @param settings [Hash{Symbol, String => Object}] the world's persistence settings
+          #   for this binding; `database` is required, `schema`, `role` (a Postgres role to
+          #   grant this era's privileges to) and `allow_superuser` are honored
+          # @param directory [String, nil] the domain's bluebook directory, where
+          #   `HECKS_SCAFFOLD=1` writes a translation edge; nil disables scaffolding
+          # @return [Integer, nil] the ordinal of the era this boot minted, or nil when it
+          #   minted nothing (first boot, quiet reboot, or a held-but-superseded shape)
+          # @raise [Runtime::WiringError] if the database cannot be reached, the connection
+          #   is a superuser or has BYPASSRLS without `allow_superuser`, a declared
+          #   `formerly_known_as` rename cannot be applied, a held text fails its integrity
+          #   check, or the shape is unheld and `mint!` refuses
+          # @raise [Bluebook::DSL::Malformed] if a held era's text parses under neither the
+          #   current nor the legacy grammar
           def check!(registry:, bluebook:, current_text:, settings:, directory: nil)
             db = PostgresEra.connect_for(bluebook.name, settings)
             lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as)
-            # FIRST, before ensure_base! provisions or verifies anything —
+            # First, before ensure_base! provisions or verifies anything —
             # the one point every PostgresEra boot passes through, and the
             # earliest at which the connection's own role is known. See
             # check_fence_applies!'s own header (BUG#24) for why a
@@ -39,7 +63,7 @@ module Hecks
               lineage.hold_first!(current_text, projection: Runtime::StorageShape.project(bluebook))
               bluebook.aggregates.each { |aggregate| lineage.ensure_first_head!(aggregate.storage_name) }
               # hold_first! already established era 1 as current for
-              # EVERY role; this one just needs its own privileges.
+              # every role; this one just needs its own privileges.
               lineage.grant_role!(role, aggregates: bluebook.aggregates, era: 1) if role
               return
             end
@@ -52,7 +76,7 @@ module Hecks
               # is permanently the old one — the frozen text is authentic
               # record ("this domain really was called that, at the
               # time") and must never be rewritten. Only the in-memory
-              # shape used for THIS comparison is normalized, and only
+              # shape used for this comparison is normalized, and only
               # where it exactly matches the declared old name, so an
               # unrelated domain that happens to shape-match some other
               # domain's history still shows up as a real mismatch.
@@ -74,9 +98,9 @@ module Hecks
             matched, = shapes.find { |_, shape| shape == current_shape }
             if matched
               # A held-but-superseded era — an old checkout still running.
-              # It may keep BOOTING and READING (PostgresEra is the one
+              # It may keep booting and reading (PostgresEra is the one
               # adapter that recognizes this rather than refusing), but it
-              # may not keep WRITING: the shared era fence was already
+              # may not keep writing: the shared era fence was already
               # advanced past this ordinal by whichever mint superseded
               # it, and nothing here may roll that back. Granting only
               # this role's privileges, never advance_era!, is what keeps
@@ -84,11 +108,11 @@ module Hecks
               # called with a superseded ordinal.
               lineage.grant_role!(role, aggregates: bluebook.aggregates, era: matched[:ordinal]) if role
               registry.resolved_eras[bluebook.name] = matched[:ordinal]
-              # ...and the boot REMEMBERS that it is superseded, not only
+              # ...and the boot remembers that it is superseded, not only
               # which era it is: `RepositoryFactory.build` hands this to
               # the adapter as `superseded_by:`, and `PostgresEra#append`
               # refuses on it before issuing the INSERT. That is the
-              # in-process half of "may not keep WRITING" — the half that
+              # in-process half of "may not keep writing" — the half that
               # holds even for a connection the RLS fence cannot bite
               # (a superuser under allow_superuser; BUG#24).
               registry.superseded_eras[bluebook.name] = latest[:ordinal]

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/merge_coordinator.rb

@@ -10,6 +10,22 @@ module Hecks
         # world's post-cut writes into the head by their recorded global
         # ordinals, under the full audit, in one transaction.
         module MergeCoordinator
+          # Merges the writes old checkouts made after the last mint into the current
+          # era's head, on a connection of its own that it closes afterwards.
+          #
+          # @param registry [Runtime::Registry] the loaded registry; supplies the
+          #   translation edges the chain is built from
+          # @param bluebook [Bluebook::Chapter] the domain whose tail is merged
+          # @param settings [Hash{Symbol, String => Object}] the world's persistence
+          #   settings for this binding; `database` is required
+          # @param winners [Hash{String => String}] record id to `"old"` or `"new"`, naming
+          #   which world's whole record wins for each id both worlds touched since the cut
+          # @return [true] when the merge committed
+          # @raise [Runtime::WiringError] if the database cannot be reached, the domain
+          #   stands at era 1, the edge chain is broken, a record touched by both worlds
+          #   has no named winner, the post-merge audit reports violations, another mint
+          #   or merge holds the domain lock for 10 seconds, or Postgres refuses a
+          #   statement; every refusal rolls the merge back
           def merge!(registry:, bluebook:, settings:, winners: {})
             db = PostgresEra.connect_for(bluebook.name, settings)
             lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as)

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/minter.rb

@@ -12,6 +12,29 @@ module Hecks
         # reviewed, check coverage, audit the live chain, and mint — or
         # refuse toward the authoring loop by name.
         module Minter
+          # Mints the next era for a drifted shape in one transaction, after proving the
+          # edge is present, current, approved where it must be, covering, and audited.
+          #
+          # @param registry [Runtime::Registry] the booting registry; supplies the loaded
+          #   translation edges
+          # @param bluebook [Bluebook::Chapter] the domain as currently declared
+          # @param current_text [String] the domain's bluebook source, held verbatim as the
+          #   new era's text
+          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, on an open
+          #   connection
+          # @param latest [Hash{Symbol => Object}] the newest held era, as `Lineage#eras`
+          #   returns it (`:ordinal`, `:hash`, `:label`, `:held_text`, `:watermark`)
+          # @param role [String, nil] a Postgres role to grant the new era's privileges to;
+          #   nil grants nothing
+          # @param directory [String, nil] the domain's bluebook directory, where
+          #   `HECKS_SCAFFOLD=1` writes a missing edge; nil disables scaffolding
+          # @return [Integer] the ordinal of the era just minted
+          # @raise [Runtime::WiringError] if no edge leaves the latest era, more than one
+          #   does, the edge targets another shape, a compute or rekey edge lacks a current
+          #   approval, the edge leaves drift uncovered, the chain is broken, the audit
+          #   reports violations, or the mint transaction itself fails
+          # @raise [Bluebook::DSL::Malformed] if the latest held text parses under neither
+          #   the current nor the legacy grammar
           def mint!(registry, bluebook, current_text, lineage, latest, role: nil, directory: nil)
             ensure_named!(lineage, latest)
             latest = lineage.eras.last
@@ -34,12 +57,28 @@ module Hecks
             ordinal
           end
 
-          # Find the one translation edge that leaves the held era, and
-          # validate it: exactly one edge must leave (eras fork
+          # Finds the one translation edge that leaves the held era, and
+          # validates it: exactly one edge must leave (eras fork
           # mechanically — a second edge from the same source is a wiring
           # mistake, not a merge to resolve automatically), and it must
           # target the current shape's label (otherwise the edge is stale
           # and boot must not silently mint past it).
+          #
+          # @param registry [Runtime::Registry] the registry whose loaded `translations`
+          #   are searched
+          # @param bluebook [Bluebook::Chapter] the domain as currently declared
+          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, used only
+          #   when scaffolding a missing edge
+          # @param latest [Hash{Symbol => Object}] the newest held era, already named;
+          #   `:label` is the edge's required source and `:ordinal` appears in refusals
+          # @param label [String] the current shape's label, the edge's required target
+          # @param ordinal [Integer] the ordinal of the era about to be minted
+          # @param directory [String, nil] where `HECKS_SCAFFOLD=1` writes a missing edge;
+          #   nil disables scaffolding
+          # @return [Bluebook::Translation] the single edge from `latest[:label]` to `label`
+          # @raise [Runtime::WiringError] if no edge leaves the latest era (naming the
+          #   scaffold it wrote, when it wrote one), more than one does, or the one edge
+          #   targets a label other than `label`
           def resolve_edge!(registry, bluebook, lineage, latest, label, ordinal, directory)
             edges = registry.translations.select { |t| t.domain == bluebook.name && t.from == latest[:label] }
             refuse_toward_the_scaffold!(registry, bluebook, lineage, latest, ordinal, directory) if edges.empty?
@@ -58,15 +97,29 @@ module Hecks
             edge
           end
 
+          # Refuses a mint whose edge carries a compute or rekey rule without a recorded
+          # approval that still matches the edge and the journal.
+          #
           # A compute's (and, the same way, a rekey's) only verification
           # is the audit's human-approved sample — mint stays
           # non-interactive by requiring the approval to already exist,
-          # recorded IN THIS DATABASE by `bin/translation_audit …
+          # recorded in this database by `bin/translation_audit …
           # --approve` and bound to what was actually reviewed: this
           # edge's parsed content, and the journal as it stood when the
           # samples were read. A journal that has advanced past the
           # review invalidates it — the approved samples no longer cover
           # the data.
+          #
+          # @param bluebook [Bluebook::Chapter] the domain, named in the refusal
+          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, which holds
+          #   the recorded approvals and the journal's last ordinal
+          # @param edge [Bluebook::Translation] the edge about to be minted through
+          # @param ordinal [Integer] the ordinal of the era about to be minted
+          # @return [nil] when the edge has no compute or rekey rule, or its approval is
+          #   current
+          # @raise [Runtime::WiringError] if no approval is recorded for this shape pair, the
+          #   approval's edge digest differs from this edge's, or the journal has advanced
+          #   past the reviewed ordinal
           def ensure_compute_rekey_approved!(bluebook, lineage, edge, ordinal)
             return unless edge.aggregates.any? { |declared| !declared.computes.empty? || !declared.rekeys.empty? }
 
@@ -86,10 +139,28 @@ module Hecks
                   "human approved no longer cover the data; re-run bin/translation_audit with --approve"
           end
 
+          # Refuses a mint that found no translation edge, naming the authoring tools —
+          # or, with scaffolding on, the file it just wrote.
+          #
           # No edge yet: the boot refuses toward the authoring loop —
           # naming both tools and the era ordinal. With HECKS_SCAFFOLD=1
-          # the boot RUNS the scaffold first (an explicit flag, never a
+          # the boot runs the scaffold first (an explicit flag, never a
           # silent side-effect) and the refusal names the file it wrote.
+          #
+          # @param registry [Runtime::Registry] the registry, forwarded to `scaffold!` when
+          #   scaffolding is on
+          # @param bluebook [Bluebook::Chapter] the domain, named in the refusal
+          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, forwarded
+          #   to `scaffold!` when scaffolding is on
+          # @param latest [Hash{Symbol => Object}] the newest held era, forwarded to
+          #   `scaffold!` when scaffolding is on
+          # @param ordinal [Integer] the ordinal of the era about to be minted, named in
+          #   the refusal
+          # @param directory [String, nil] the domain's bluebook directory; scaffolding
+          #   requires this to be present as well as `HECKS_SCAFFOLD=1`
+          # @return [void] never returns
+          # @raise [Runtime::WiringError] always; the message names the scaffolded file
+          #   when `HECKS_SCAFFOLD=1` and `directory` wrote one
           def refuse_toward_the_scaffold!(registry, bluebook, lineage, latest, ordinal, directory)
             if ENV["HECKS_SCAFFOLD"] == "1" && directory
               path = scaffold!(registry, bluebook, lineage, latest, directory)
@@ -104,9 +175,19 @@ module Hecks
                   "check it with bin/translation_audit, then boot again"
           end
 
-          # Diff the held era against the current shape and write the edge
+          # Diffs the held era against the current shape and writes the edge
           # file — confident rules inline, ambiguities as parse-refusing
-          # `unresolved` lines. Returns the file path.
+          # `unresolved` lines.
+          #
+          # @param _registry [Runtime::Registry] unused; kept so the signature matches its
+          #   caller's own arguments
+          # @param bluebook [Bluebook::Chapter] the domain as currently declared
+          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage; named so
+          #   `ensure_named!` can mint a name for `latest` first if it has none
+          # @param latest [Hash{Symbol => Object}] the newest held era, as `Lineage#eras`
+          #   returns it
+          # @param directory [String] the domain's bluebook directory to write the edge under
+          # @return [String] the path `Translation::Scaffold::Writer#write!` wrote
           def scaffold!(_registry, bluebook, lineage, latest, directory)
             ensure_named!(lineage, latest)
             latest = lineage.eras.last
@@ -126,9 +207,17 @@ module Hecks
             Translation::Scaffold.write!(directory, edge)
           end
 
+          # Mints a name for an era that has none yet, leaving an already-named era untouched.
+          #
           # Era names are minted once. An era held before any drift was
           # seen has no name yet; it gets one the moment an edge needs to
           # leave it.
+          #
+          # @param lineage [Adapters::PostgresEra::Lineage] the domain's lineage, which
+          #   records the minted name
+          # @param era [Hash{Symbol => Object}] the era to name, as `Lineage#eras` returns it;
+          #   `:hash` present means it is already named
+          # @return [void]
           def ensure_named!(lineage, era)
             return if era[:hash]
 

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

@@ -12,7 +12,7 @@ module Hecks
     class PostgresEra
       # The PostgresEra side of the boot-time era gate. Where every other
       # adapter's era check can only hold texts and refuse, this one
-      # ACTS: a drifted shape whose translation edge exists, matches by
+      # acts: a drifted shape whose translation edge exists, matches by
       # shape label, covers the whole diff, and passes the audit mints
       # the next era — one transaction — and boots into it. Everything
       # else refuses, as loudly and as specifically as the situation
@@ -38,10 +38,24 @@ module Hecks
 
         module_function
 
-        # The FULL chain, one edge per step in original mint order —
+        # Collects the translation edge for every step from era 1 to the current shape.
+        #
+        # The full chain, one edge per step in original mint order —
         # never flattened. Each step is found by its stored labels;
         # every mint required its own edge, so a break in the chain is a
         # deleted file, and deserves its own refusal.
+        #
+        # @param registry [Runtime::Registry] the registry whose loaded `translations`
+        #   are searched
+        # @param bluebook [Bluebook::Chapter] the domain; only edges declared for its
+        #   name are considered
+        # @param eras [Array<Hash{Symbol => Object}>] the ancestor eras in ordinal order,
+        #   as `Lineage#eras` returns them; only `:label` is read
+        # @param current_label [String] the shape label the last step must lead to
+        # @return [Array<Hash{Symbol => Bluebook::Translation}>] one `{ translation: edge }`
+        #   per step, in mint order; `[]` when `eras` is empty
+        # @raise [Runtime::WiringError] if no loaded translation leads one label to the
+        #   next
         def edge_chain(registry, bluebook, eras, current_label)
           labels = eras.map { |era| era[:label] } + [current_label]
           (0...(labels.size - 1)).map do |index|
@@ -57,9 +71,18 @@ module Hecks
           end
         end
 
+        # Parses a held era's bluebook text into a throwaway registry, leaving the live
+        # one untouched.
+        #
         # Held texts live in rows, not files, but the predicate
         # extractor reads source from disk at the eval path — so a
         # shadow parse writes the text to a scratch file first.
+        #
+        # @param source [String] bluebook source text, as held in `hecks_eras.held_text`
+        # @return [Bluebook::Chapter, nil] the first bluebook the text declares, or nil
+        #   when it declares none
+        # @raise [Bluebook::DSL::Malformed] if the text parses under neither the current
+        #   grammar nor the legacy shadow-parse fallback
         def shadow(source)
           file = Tempfile.new(["hecks-era-", ".bluebook"])
           file.write(source)