hecks 1.3.0 → 1.4.0

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? }
 
@@ -88,7 +141,7 @@ module Hecks
 
           # 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.
           def refuse_toward_the_scaffold!(registry, bluebook, lineage, latest, ordinal, directory)
             if ENV["HECKS_SCAFFOLD"] == "1" && directory

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)