hecks 2.8.0 → 3.0.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/approval_file.rb

@@ -0,0 +1,227 @@
+require "json"
+require "date"
+require "fileutils"
+require_relative "audit/approval_digest"
+require_relative "../../../../../version"
+
+module Hecks
+  module Translation
+    # The committed form of an edge's approval: `translations/<edge>.approval`, a JSON file beside
+    # the edge that a reviewer sees in the same diff.
+    #
+    # It binds to the edge's content digest and not to the journal's tip, so a production journal
+    # that keeps writing between the commit and the deploy does not void it. An edge with a compute
+    # or rekey rule also carries the rehearsal a person ran against real data, since the audit's
+    # samples are that edge's only other verification.
+    module ApprovalFile
+      EXTENSION = ".approval".freeze
+
+      # The keys of a rehearsal block; every one is required when the block is required.
+      #
+      # `host_version` is the Hecks release the rehearsal ran on, and the gate checks it: a
+      # rehearsal counts only on a host whose release shares its `major.minor` (see
+      # `host_compatible?`).
+      REHEARSAL_KEYS = %w[snapshot host_version result at].freeze
+
+      # How a `host_version` reads: `major.minor`, an optional patch, an optional pre-release or
+      # build suffix. Only the first two numbers take part in the comparison.
+      HOST_LINE = /\A(\d+)\.(\d+)(?:\.\d+)?(?:[-+][0-9A-Za-z.+-]+)?\z/
+
+      # The release the running host reports: the Hecks release this code was built for. The Rust
+      # host embeds the same string from `rust/host/HECKS_RELEASE`, and a spec fails when the two
+      # drift.
+      HOST_RELEASE = Hecks::VERSION
+
+      # An ISO 8601 time: `2026-09-28T12:30:00Z`, with optional fraction and `+HH:MM` offset. The
+      # host's approval.rs accepts the same shape.
+      TIMESTAMP = /\A(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})\z/
+
+      extend Audit::ApprovalDigest
+
+      module_function
+
+      # Names an edge by the labels it joins; labels are hex, so the dash cannot be part of one.
+      #
+      # @param edge [Bluebook::Translation] the parsed translation edge
+      # @return [String] `<from>-<to>`
+      def edge_name(edge) = "#{edge.from}-#{edge.to}"
+
+      # Where an edge's approval lives.
+      #
+      # @param directory [String] the domain's bluebook directory
+      # @param edge [Bluebook::Translation] the parsed translation edge
+      # @return [String] `<directory>/translations/<edge>.approval`
+      def path_for(directory, edge) = File.join(directory, "translations", "#{edge_name(edge)}#{EXTENSION}")
+
+      # Whether the edge carries a rule whose only verification is a human's review of samples.
+      #
+      # @param edge [Bluebook::Translation] the parsed translation edge
+      # @return [Boolean] true when any aggregate declares a compute or a rekey
+      def needs_rehearsal?(edge)
+        edge.aggregates.any? { |declared| !declared.computes.empty? || !declared.rekeys.empty? }
+      end
+
+      # Whether a rehearsal block records a run that passed, with every field named.
+      #
+      # @param rehearsal [Hash, nil] the block, string-keyed as it reads from JSON
+      # @return [Boolean] true when all of `REHEARSAL_KEYS` are non-empty Strings and `result` is
+      #   `pass`
+      def rehearsed?(rehearsal)
+        return false unless rehearsal.is_a?(Hash)
+
+        REHEARSAL_KEYS.all? { |key| named?(rehearsal[key]) } && rehearsal["result"] == "pass"
+      end
+
+      # The `major.minor` a version names.
+      #
+      # @param version [Object] a `host_version` as it reads from JSON
+      # @return [Array<Integer>, nil] `[major, minor]`, or nil when it is not a version
+      def release_line(version)
+        match = HOST_LINE.match(version) if version.is_a?(String)
+        match && [match[1].to_i, match[2].to_i]
+      end
+
+      # Whether a rehearsal ran on a host compatible with the running one.
+      #
+      # The rule is the smallest sound one: equal `major.minor`. A patch release does not change
+      # what a mint does, so a rehearsal survives it; a minor or major release may, so a rehearsal
+      # from an older host (or a newer one, which proves nothing about this one) does not.
+      #
+      # @param rehearsal [Hash] a rehearsal block, string-keyed
+      # @param host_version [String] the running host's release
+      # @return [Boolean] true when both versions parse and share `major.minor`
+      def host_compatible?(rehearsal, host_version = HOST_RELEASE)
+        line = release_line(rehearsal["host_version"])
+        !line.nil? && line == release_line(host_version)
+      end
+
+      # The refusal for a rehearsal that ran on another host line; rust/host words it the same.
+      #
+      # @param rehearsal [Hash] a rehearsal block, string-keyed
+      # @param host_version [String] the running host's release
+      # @return [String] names both versions
+      def host_refusal(rehearsal, host_version = HOST_RELEASE)
+        line = release_line(host_version)&.join(".")
+        "the rehearsal ran on Hecks #{rehearsal['host_version']}, but this host is Hecks #{host_version}; " \
+          "a rehearsal counts only on a host of the same major.minor (#{line}.x) — " \
+          "re-run the rehearsal on this host and approve again"
+      end
+
+      # Whether a value is a String with something in it; a number or nil names nothing.
+      #
+      # @param value [Object] a field as it reads from JSON
+      # @return [Boolean] true for a String that is not blank
+      def named?(value) = value.is_a?(String) && !value.strip.empty?
+
+      # Whether a value is an ISO 8601 time that exists on the calendar.
+      #
+      # @param value [Object] a field as it reads from JSON
+      # @return [Boolean] true for a String of the `TIMESTAMP` shape with a real date and clock time
+      def timestamp?(value)
+        return false unless value.is_a?(String) && (match = TIMESTAMP.match(value))
+
+        year, month, day, hour, minute, second = match.captures.map(&:to_i)
+        Date.valid_date?(year, month, day) && hour < 24 && minute < 60 && second < 60
+      end
+
+      # Whether an approval names who approved it and when, the two things a reviewer signs.
+      #
+      # @param approval [Hash] the file, string-keyed as it reads from JSON
+      # @return [Boolean] true when `approved_by` is a non-empty String and `approved_at` a time
+      def attributed?(approval)
+        named?(approval["approved_by"]) && timestamp?(approval["approved_at"])
+      end
+
+      # Builds the JSON document of one approval.
+      #
+      # @param edge [Bluebook::Translation] the parsed translation edge
+      # @param approved_by [String] who approved it, from their git identity
+      # @param approved_at [String] when, as an ISO 8601 UTC time
+      # @param rehearsal [Hash{String => String}, nil] the block; required for a compute or rekey
+      # @return [Hash{String => Object}] `edge`, `edge_digest`, `approved_by`, `approved_at`, and
+      #   `rehearsal` when one was given
+      # @raise [ArgumentError] if `approved_by` is blank or `approved_at` is not a time, or if the
+      #   edge needs a rehearsal and none that passed was given
+      def build(edge:, approved_by:, approved_at:, rehearsal: nil)
+        unless attributed?("approved_by" => approved_by, "approved_at" => approved_at)
+          raise ArgumentError, "an approval names who approved it (approved_by, your git identity) " \
+                               "and when (approved_at, an ISO 8601 time)"
+        end
+
+        if needs_rehearsal?(edge) && !rehearsed?(rehearsal)
+          raise ArgumentError, "an edge with a compute or rekey rule is approved on a rehearsal that passed: " \
+                               "name the snapshot, the host version, the result (pass) and when it ran"
+        end
+
+        document = { "edge" => edge_name(edge), "edge_digest" => edge_digest(edge),
+                     "approved_by" => approved_by, "approved_at" => approved_at }
+        document["rehearsal"] = rehearsal.slice(*REHEARSAL_KEYS) if rehearsal
+        document
+      end
+
+      # Writes an edge's approval file, replacing an earlier approval of the same edge.
+      #
+      # @param directory [String] the domain's bluebook directory
+      # @param edge [Bluebook::Translation] the parsed translation edge
+      # @param document [Hash{String => Object}] what `build` answered
+      # @return [String] the path written
+      def write!(directory, edge, document)
+        path = path_for(directory, edge)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, "#{JSON.pretty_generate(document)}\n")
+        path
+      end
+
+      # Reads every committed approval of a domain.
+      #
+      # @param directory [String] the domain's bluebook directory
+      # @return [Array<Hash{String => Object}>] each parsed file; one that is not JSON is skipped,
+      #   since a file that cannot be read approves nothing
+      def read_all(directory)
+        Dir[File.join(directory, "translations", "*#{EXTENSION}")].filter_map do |path|
+          parsed = JSON.parse(File.read(path))
+          parsed if parsed.is_a?(Hash)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      # The committed approval that lets an edge mint, if there is one.
+      #
+      # @param directory [String, nil] the domain's bluebook directory
+      # @param edge [Bluebook::Translation] the parsed translation edge
+      # @param host_version [String] the running host's release
+      # @return [Hash{String => Object}, nil] an approval whose digest is the edge's, that names
+      #   who approved it and when, and whose rehearsal passed on a compatible host when the edge
+      #   needs one; nil when none applies
+      def applicable(directory, edge, host_version: HOST_RELEASE)
+        return unless directory
+
+        digest = edge_digest(edge)
+        read_all(directory).find do |approval|
+          approval["edge_digest"] == digest && attributed?(approval) &&
+            (!needs_rehearsal?(edge) ||
+              (rehearsed?(approval["rehearsal"]) && host_compatible?(approval["rehearsal"], host_version)))
+        end
+      end
+
+      # Why a committed approval that covers the edge was still not applied, when the only thing
+      # wrong is the host it was rehearsed on.
+      #
+      # @param directory [String, nil] the domain's bluebook directory
+      # @param edge [Bluebook::Translation] the parsed translation edge
+      # @param host_version [String] the running host's release
+      # @return [String, nil] `host_refusal`'s text, or nil when no such approval exists
+      def host_mismatch(directory, edge, host_version: HOST_RELEASE)
+        return unless directory && needs_rehearsal?(edge)
+
+        digest = edge_digest(edge)
+        stale = read_all(directory).find do |approval|
+          approval["edge_digest"] == digest && attributed?(approval) && rehearsed?(approval["rehearsal"]) &&
+            !host_compatible?(approval["rehearsal"], host_version)
+        end
+        host_refusal(stale["rehearsal"], host_version) if stale
+      end
+    end
+  end
+end

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 `hecks audit_translation --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