hecks 2.7.0 → 2.9.0

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

@@ -3,45 +3,8 @@ require "digest"
 
 module Hecks
   module Runtime
-    # The storage-shape projection of a bluebook: exactly the parts of
-    # the IR that decide what persisted data looks like — aggregates,
-    # their attributes (with full value-object/entity structure and
-    # cardinality), references, the lifecycle field, and the identity
-    # paths. Everything behavioral — commands, invariants, queries,
-    # policies, lifecycle transitions, defaults, descriptions, comments,
-    # the declared routing `version:` — is excluded, so editing behavior
-    # never bumps an era and editing shape always does.
-    #
-    # ## Constraints left out on purpose
-    #
-    # Three attribute facts on the wire are constraints on persisted
-    # values, not behavior, and are still excluded — each decided, not
-    # overlooked:
-    #
-    #   `optional`  — required-ness is enforced at dispatch; stored rows
-    #                 are never re-validated on read, so flipping it
-    #                 strands nothing already written. Excluded.
-    #   `pattern`   — same argument: a fact about what may be written
-    #                 next, not about what was stored. Excluded.
-    #   `admits`    — the sharpest of the three: narrowing a closed set
-    #                 can strand stored rows outside it, and the wire
-    #                 carries only the set's name, so a set whose members
-    #                 changed under a stable name is invisible even to a
-    #                 projection that included the fact (the same lesson
-    #                 recursive value-object drift taught). Excluded, and
-    #                 named as a gap: constraint tightening has no
-    #                 translation-rule vocabulary to acknowledge it yet,
-    #                 so including it would mint era bumps nothing can
-    #                 explain. When the translation language grows a
-    #                 constraint-acknowledgment rule, `admits` (by member
-    #                 list, not by name) is first in line, and that
-    #                 change bumps `FORM_VERSION`.
-    #
-    # ## Structural comparison over the dump form
-    #
-    # Projection runs over the canonical dump form (`to_h`, JSON
-    # round-tripped), so a verdict depends only on the IR — never on live
-    # object graphs. Structural comparison only, never a hash comparison.
+    # The storage-shape projection of a bluebook: only the IR parts that decide how persisted
+    # data looks, so behavior edits never bump an era and shape edits always do.
     module StorageShape
       module_function
 
@@ -67,10 +30,7 @@ module Hecks
       # @return [Boolean] true when both project to an equal structure
       def same?(held, current) = project(held) == project(current)
 
-      # The canonical serialization the Ruby scaffold hashes at mint time
-      # — the one moment identity is computed. Nothing ever recomputes a
-      # stored era name to verify it, so this form can evolve freely.
-      #
+      # The canonical serialization hashed at mint time; stored era names are never recomputed.
       # @param bluebook [Bluebook::Chapter] the bluebook to serialize
       # @return [String] compact JSON text of `project(bluebook)`
       def canonical(bluebook) = JSON.generate(project(bluebook))
@@ -89,12 +49,8 @@ module Hecks
       # @return [String] the first `LABEL_LENGTH` hex characters of `mint_hash(bluebook)`
       def mint_label(bluebook) = mint_hash(bluebook)[0, LABEL_LENGTH]
 
-      # The version of the canonical serialization above. Minted-once
-      # means a stored name stays valid across form changes — but only
-      # if each name records which form minted it, so v1-named and
-      # v2-named eras coexist legibly. Stored beside every minted hash
-      # (names.tsv fourth field / hecks_eras.canon_form); bump this in
-      # the same change that alters project/canonical output.
+      # Version of the canonical form, stored beside each minted hash; bump it with any
+      # change to project/canonical output.
       FORM_VERSION = 1
 
       # Projects one dumped aggregate down to its identity, lifecycle field and attributes.
@@ -108,11 +64,7 @@ module Hecks
       def project_aggregate(aggregate)
         {
           "name"            => aggregate["name"],
-          # The declared identity paths, as a list, in declaration order —
-          # order is semantic (the paths join in order to form the id).
-          # No "id" fallback: an aggregate that declares nothing has [],
-          # and that is a real declared state, distinct from an aggregate
-          # identified by a field named "id".
+          # Declaration order is semantic (paths join in order to form the id); no "id" fallback.
           "identity"        => Array(aggregate["identified_by"]).map(&:to_s),
           "lifecycle_field" => aggregate.dig("lifecycle", "field"),
           "attributes"      => (aggregate["attributes"] || [])
@@ -121,12 +73,13 @@ module Hecks
         }
       end
 
+      # `optional`, `pattern` and `admits` are left out: they constrain future writes, not
+      # stored rows. Including `admits` needs a translation rule to acknowledge it first.
+      #
       # Projects one dumped attribute to its name, cardinality and full type signature.
       #
-      # @param aggregate [Hash{String => Object}] the dumped aggregate that owns the attribute,
-      #   searched for the value objects and entities its type may name
-      # @param attribute [Hash{String => Object}] the dumped attribute, read for `"name"`,
-      #   `"list"` and `"type"`
+      # @param aggregate [Hash{String => Object}] the dumped aggregate that owns the attribute
+      # @param attribute [Hash{String => Object}] the dumped attribute
       # @param seen [Array<String>] type names already being expanded, which stops a
       #   self-referencing type from recursing forever
       # @return [Hash{String => Object}] `"name"` (String), `"list"` (Boolean) and `"type"`
@@ -139,11 +92,8 @@ module Hecks
         }
       end
 
-      # A plain type name for a primitive; the type name plus its
-      # members' full signatures for a value object or entity — so two
-      # attributes with the same declared type name but different
-      # internals are never mistaken for unchanged.
-      #
+      # A primitive's type name, or for a value object or entity the name plus its members'
+      # signatures, so same-named types with different internals never look unchanged.
       # @param aggregate [Hash{String => Object}] the dumped aggregate whose value objects and
       #   entities are searched for `type_name`
       # @param type_name [String] the attribute's declared type name

data/lib/hecks/ports/persistence/plugins/era/translation/audit/approval_digest.rb

@@ -4,23 +4,8 @@ require_relative "../../../../../../projector/exporter"
 module Hecks
   module Translation
     module Audit
-      # ── the human gate, made real ──────────────────────────────────
-      #
-      # For the five portable rule kinds the mint verifies the edge
-      # mechanically (Layer 2 is the cross-execution equivalence gate).
-      # A compute has no mechanical verification — the Layer-3 sample a
-      # human reads is the only one there is — so a compute edge cannot
-      # mint until someone has run `bin/translation_audit … --approve`.
-      #
-      # The approval binds to what was actually reviewed, on both axes:
-      # a content digest of the parsed edge (change the edge's meaning
-      # and the approval lapses; a comment does not), and the journal's
-      # high-water ordinal at review time, recorded in the target
-      # database — a token in the repo could not bind to the data, and
-      # samples reviewed against staging or against production-as-of-T
-      # say nothing about a database that has moved on. Mint stays
-      # non-interactive and its lock stays short; the human decision
-      # happens in the audit tool, where the samples are.
+      # The human gate: a compute edge cannot mint until `bin/translation_audit --approve`
+      # binds an approval to the edge's content digest and the journal's ordinal at review.
       module ApprovalDigest
         # Fingerprints a parsed translation edge, so an approval lapses when the edge's
         # meaning changes but not when only a comment does.

data/lib/hecks/ports/persistence/plugins/era/translation/audit/layer_one.rb

@@ -6,12 +6,8 @@ require_relative "../../../../../../bluebook/model_check"
 module Hecks
   module Translation
     module Audit
-      # Layer 1 — from the bluebook alone: every translated state must
-      # pass the new era's types, value-object invariants, and lifecycle.
-      # This is also where a new, stricter invariant that old records
-      # violate surfaces — there is no "grandfather old records"
-      # construct, and the remedy is relaxing the invariant or explicit
-      # remediation, never a translation rule.
+      # Layer 1: every translated state must pass the new era's types, invariants and lifecycle.
+      # Old records that violate a stricter invariant surface here; no translation rule fixes them.
       module LayerOne
         # Hydrates every translated state as a current-era instance and records each one
         # the era's types, invariants or lifecycle refuse.
@@ -28,14 +24,7 @@ module Hecks
             next unless lifecycle
 
             held = instance[lifecycle.field]
-            # `Lifecycle#states` answers default+targets only — a state
-            # legitimately declared just as a `from:` (a terminal
-            # transition's source, never anyone's target) is real and
-            # reachable but invisible to it. `ModelCheck.full_states`
-            # is the full declared set (default, every target, and
-            # every from) that `fuzzing/properties.rb`'s own replay
-            # check already uses for this identical question — see its
-            # comment on this same hole.
+            # `Lifecycle#states` omits states declared only as a `from:`; `full_states` has them.
             allowed = Bluebook::ModelCheck.full_states(lifecycle)
             unless held.nil? || allowed.include?(held.to_s)
               violations << "#{aggregate.name}##{id}: #{lifecycle.field} is #{held.inspect}, " \

data/lib/hecks/ports/persistence/plugins/era/translation/audit/layer_two.rb

@@ -4,48 +4,27 @@ require_relative "../../lineage"
 module Hecks
   module Translation
     module Audit
-      # Layer 2 — from the edge alone: per-rule value preservation, no
-      # leftover source keys, and id-set conservation across the edge.
+      # Layer 2: from the edge alone, per-rule value preservation and id-set conservation.
       module LayerTwo
         # Checks one aggregate's records across the edge for id conservation and, where a
         # per-record comparison is possible, agreement with the reference transform.
         #
-        # Per-rule value preservation and leftover source keys are checked
-        # against the reference transform in full — never rule by rule in
-        # isolation, because rules interact (a rename whose value a later
-        # move partially consumes preserves exactly what the transform
-        # says it preserves, no more). This makes every mint a run of the
-        # cross-execution equivalence gate for the five portable rule
-        # kinds: the compiled SQL produced `after`; the port's entry-JSON
-        # transform produces `expected`; they must agree byte-for-byte on
-        # every path a compute doesn't own. Compute paths are exempt — the
-        # SQL is their only implementation, and the Layer-3 sample is
-        # their only review. A rekeyed aggregate is exempt from this whole
-        # per-record check, for the same reason and one more: there is no
-        # old-id → new-id correspondence to look `after` up by once the id
-        # itself is what changed.
+        # Compute paths and rekeyed aggregates are exempt from the comparison.
         #
         # @param violations [Array<String>] collector this method appends messages to
         # @param aggregate [Bluebook::Aggregate] the current era's IR for the aggregate
-        # @param declared [Bluebook::TranslationAggregate, nil] this edge's rules for the
-        #   aggregate; nil limits the check to id conservation
+        # @param declared [Bluebook::TranslationAggregate, nil] nil limits the check to ids
         # @param before [Hash{String => Hash}] source state per record id, as parsed JSON
         # @param after [Hash{String => Hash}] translated state per record id, as parsed JSON
         # @return [void]
-        # @raise [Runtime::WiringError] if the reference transform cannot translate a `before`
-        #   state: a convert meets an unmapped value, or a move nests under a non-Hash
+        # @raise [Runtime::WiringError] if the reference transform cannot translate `before`
         def layer_two!(violations, aggregate, declared, before, after)
           rekeyed = declared && !declared.rekeys.empty?
 
           check_id_conservation!(violations, aggregate, before, after, rekeyed: rekeyed)
 
           return unless declared
-          # No correspondence between an old id and its rekeyed row exists
-          # in Ruby (the rekey's SQL is its only implementation, same as
-          # compute's) — exempt from the per-record equivalence gate for
-          # the same reason compute paths already are, extended to the
-          # whole record since an old-id lookup into `after` can never
-          # succeed once the id itself has changed.
+          # A rekey's SQL is its only implementation and `after` cannot be looked up by old id.
           return if rekeyed
 
           check_value_preservation!(violations, aggregate, declared, before, after)
@@ -53,12 +32,6 @@ module Hecks
 
         # Records a violation when the edge loses, gains or collides record ids.
         #
-        # Record-count / id-set conservation — one of the two properties
-        # this module's own header names, and independent of the other
-        # (per-rule value preservation, below): it needs only `before`,
-        # `after`, and whether the edge rekeyed, never the declared rules
-        # themselves.
-        #
         # @param violations [Array<String>] collector this method appends at most one message to
         # @param aggregate [Bluebook::Aggregate] the aggregate, named in the message
         # @param before [Hash{String => Hash}] source state per record id
@@ -67,13 +40,7 @@ module Hecks
         #   counts instead of id sets
         # @return [void]
         def check_id_conservation!(violations, aggregate, before, after, rekeyed:)
-          # A rekey legitimately changes the id set (that's the entire
-          # point) — set-equality would flag every honest rekey as data
-          # loss. What must still hold is record count: a botched rekey
-          # colliding two distinct old ids onto one new id, or dropping one
-          # (its SQL returning NULL), shows up as the count going down —
-          # caught here without needing to track the old→new mapping
-          # itself.
+          # A rekey changes the id set, so compare counts: a collision or a NULL id lowers it.
           if rekeyed
             unless before.keys.size == after.keys.size
               violations << "#{aggregate.name}: the record count changed across a rekeying edge " \
@@ -88,15 +55,14 @@ module Hecks
           end
         end
 
-        # Per-rule value preservation — the other property this module's
-        # header names. Only reached once `layer_two!` has already ruled
-        # out "no declared edge" and "rekeyed" (see its own comment on
-        # that second guard); this method assumes both are false.
+        # Records a violation for each record whose translated state diverges from the reference.
+        # Assumes the edge is declared and does not rekey.
+        #
         # @param violations [Array<String>] mutated in place with one message per divergent id
         # @param aggregate [Bluebook::Aggregate] the aggregate being audited
         # @param declared [Bluebook::Translation] the declared translation to check against
-        # @param before [Hash{String => Hash}] the old world's own records, keyed by id
-        # @param after [Hash{String => Hash}] the new world's own records, keyed by id
+        # @param before [Hash{String => Hash}] source records, keyed by id
+        # @param after [Hash{String => Hash}] translated records, keyed by id
         # @return [void]
         def check_value_preservation!(violations, aggregate, declared, before, after)
           rules = Ports::Persistence::Lineage.from_declared(declared, aggregate.name)
@@ -124,19 +90,8 @@ module Hecks
 
         # Removes the paths a compute owns from a normalized state, in place.
         #
-        # Exempts exactly the paths a compute owns, not the whole
-        # top-level attribute it happens to live under. A bare path
-        # ("price_cents") is itself the compute's entire value — dropping
-        # the whole top-level key is correct, there's nothing else there
-        # to check. A dotted path ("price.cents") only owns that one
-        # member of the value object it reaches into; every sibling
-        # member (e.g. "price.currency") is untouched by the compute and
-        # must stay subject to the equivalence check below. Blanket-
-        # dropping the whole top-level key for a dotted compute would
-        # exempt the entire attribute — silent data loss elsewhere in the
-        # same value object (a migration that nulls or drops a sibling
-        # field) would produce zero violations, defeating the one gate
-        # whose entire purpose is to catch exactly that.
+        # A dotted path removes only its own member, never the whole top-level key, so sibling
+        # members stay under the equivalence check and silent loss there is still caught.
         #
         # @param state [Hash{String => Object}] a normalized state; mutated
         # @param paths [Array<String>] bare (`"price_cents"`) or dotted (`"price.cents"`)

data/lib/hecks/ports/persistence/plugins/era/translation/audit/unfed_report.rb

@@ -1,22 +1,11 @@
 module Hecks
   module Translation
     module Audit
-      # New-era attributes that nothing feeds: absent from every
-      # translated state, produced by no rule, and carrying no default.
-      # A report, not a violation — the remedy is a `default:` on the
-      # attribute, and the loud refusal for a required one comes from
-      # Layer 1 the moment an invariant reads it.
+      # New-era attributes that nothing feeds: no translated state, rule or default supplies them.
+      # A report, not a violation; a required one is refused by Layer 1 once an invariant reads it.
       module UnfedReport
         # Lists the current era's attributes that no rule, default or translated record feeds.
         #
-        # `fed` build-up plus one ordered guard chain per attribute
-        # (already fed, has a default, actually present in some record, no
-        # records to check at all) answering a single question — "is
-        # anything, ever, going to feed this field" — where each `next`
-        # rules out one way the answer is "not unfed after all" before the
-        # next is even worth asking. Splitting the guards out would just
-        # turn each into a same-shaped one-line predicate call.
-        #
         # @param aggregate [Bluebook::Aggregate] the current era's IR for the aggregate
         # @param declared [Bluebook::TranslationAggregate, nil] this edge's rules; the
         #   destinations of its renames, moves, converts and computes count as fed
@@ -57,10 +46,7 @@ module Hecks
           path.to_s.split(".").reduce(state) do |node, segment|
             break nil unless node.is_a?(Hash)
 
-            # `key?` decides which spelling answers, never `||` — a
-            # `false` genuinely held at this path must not fall through
-            # to the other spelling (usually absent) and read as `nil`,
-            # which would wrongly mark a `false`-valued attribute "unfed".
+            # `key?`, not `||`: a held `false` must not fall through and read as nil (unfed).
             node.key?(segment) ? node[segment] : node[segment.to_sym]
           end
         end

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

@@ -7,13 +7,8 @@ require_relative "audit/approval_digest"
 
 module Hecks
   module Translation
-    # The audit derives its assertions; nobody hand-lists them. One file
-    # per layer beside this one: audit/layer_one.rb (the bluebook's own
-    # rules), audit/layer_two.rb (the edge against the reference
-    # transform), audit/unfed_report.rb (what nothing feeds), and
-    # audit/approval_digest.rb (the human gate's binding). Layer 3 — the
-    # before/after sample a human approves, intent not being derivable —
-    # is assembled right here in `check`.
+    # Derives the audit's assertions per layer (audit/layer_one, layer_two, unfed_report,
+    # approval_digest); Layer 3, the human-approved sample, is assembled in `check`.
     module Audit
       Verdict = Struct.new(:violations, :dropped, :unfed, :samples, keyword_init: true) do
         # Reports whether the mechanical layers found nothing to refuse.
@@ -38,14 +33,12 @@ module Hecks
       # @param aggregate [Bluebook::Aggregate] the current era's IR for the aggregate
       # @param declared [Bluebook::TranslationAggregate, nil] this edge's rules for the
       #   aggregate; nil when the edge declares none
-      # @param before [Hash{String => Hash}] the source era's latest state per record id, as
-      #   parsed JSON
-      # @param after [Hash{String => Hash}] the translated state per record id, as parsed JSON
-      # @return [Translation::Audit::Verdict] `violations` (Layer 1 and 2 messages), `dropped`
-      #   (declared drop paths as Strings), `unfed` (attribute names nothing feeds) and
-      #   `samples` (the Layer 3 before/after pairs)
+      # @param before [Hash{String => Hash}] source state per record id, as parsed JSON
+      # @param after [Hash{String => Hash}] translated state per record id, as parsed JSON
+      # @return [Translation::Audit::Verdict] Layer 1 and 2 `violations`, `dropped` paths,
+      #   `unfed` attribute names and Layer 3 `samples`
       # @raise [Runtime::WiringError] if Layer 2's reference transform cannot translate a
-      #   `before` state: a convert meets an unmapped value, or a move nests under a non-Hash
+      #   `before` state
       def check(aggregate:, declared:, before:, after:)
         violations = []
 
@@ -74,19 +67,9 @@ module Hecks
         before.keys.sort.first(SAMPLE_SIZE).map { |id| { id: id, before: before[id], after: after[id] } }
       end
 
-      # Samples both sides of a rekeying edge separately instead of pairing them by id.
-      #
-      # A rekey changes the id itself, so `before`'s and `after`'s
-      # keyspaces share nothing — pairing by matching id (the ordinary
-      # path above) would show every `after` as nil, telling a human
-      # nothing. Nothing in-process can compute the old→new
-      # correspondence either (the rekey's SQL is its only
-      # implementation, same as compute's own). Shown side by side
-      # instead, each labelled by its own id: real records going in,
-      # real records coming out — not claimed to correspond one-to-one,
-      # but enough for the human this rule's only verification depends
-      # on to actually see real shapes and values, not a wall of null.
+      # Samples both sides of a rekeying edge separately, each labelled by its own id.
       #
+      # A rekey changes the id, so pairing by id would show every `after` as nil.
       # @param before [Hash{String => Hash}] source state per old record id
       # @param after [Hash{String => Hash}] translated state per new record id
       # @return [Array<Hash{Symbol => Object}>] up to `SAMPLE_SIZE` Hashes whose `:id` ends in

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

@@ -5,17 +5,8 @@ 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
 
@@ -25,14 +16,12 @@ module Hecks
       # @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
@@ -41,13 +30,8 @@ module Hecks
                 "bluebook — a held era text is bootable source; restore a loadable text"
         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 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 :cosmetic if edited == stored_projection